AuthentiKate

The SSO/OIDC solution for homelabbers. No more Authentik overcomplicating your life (and taking 2G of ram) just so you can give your friends convenient access to your services.

What is AuthentiKate?

AuthentiKate is a lightweight, self-hosted Single Sign-On (SSO) and OpenID Connect (OIDC) provider designed specifically for homelab enthusiasts. Built with Laravel and Livewire, it provides enterprise-grade authentication features without the complexity and resource overhead of larger solutions.

Key Features

• OpenID Connect Provider: Full OIDC implementation with JWT tokens signed with RSA256
• PKCE Support: Secure authorization code flow with Proof Key for Code Exchange
• User Management: Admin interface for managing users and invitations
• Application Management: Easy registration and management of OAuth applications
• Auto-Approval: Skip consent screens for previously authorized applications
• Avatar Support: User profile pictures with file upload
• Responsive Design: Modern UI built with Flux components and Tailwind CSS
• Lightweight: Minimal resource usage compared to alternatives
• Docker Ready: Containerized deployment with automatic setup

Quick Start with Docker

The easiest way to run AuthentiKate is using Docker:

# Build the container
docker build -t authentikate .

# Run with basic configuration
docker run -p 8000:8000 \
  -e APP_NAME="AuthentiKate" \
  -e APP_ENV=production \
  -e APP_KEY=base64:$(openssl rand -base64 32) \
  -e APP_URL=https://auth.yourdomain.com \
  -e DB_CONNECTION=sqlite \
  -e DB_DATABASE=/app/database/database.sqlite \
  -v authentikate_keys:/app/storage/oauth \ # Important to keys persist between restarts
  -v authentikate_db:/app/database \
  authentikate

What Happens on First Run

When the container starts for the first time, the following setup commands run automatically via hook.sh:

1. RSA Key Generation (php artisan app:generate-keys)

   • Generates 2048-bit RSA private/public key pair
   • Keys stored in /app/storage/oauth/private.pem and /app/storage/oauth/public.pem
   • Used for signing JWT tokens with RS256 algorithm

2. Initial Admin Creation (php artisan authentikate:create-admin)

   • Creates the first admin user account
   • Prompts for email and name (or uses defaults)
   • Generates a secure random password
   • Important: Check the container logs for login credentials!

After First Run

1. Check the logs for your admin credentials:

   docker logs <container_name>
   

   Look for output like:

   ✅ Initial admin user created successfully!
   
   🔐 Login Credentials:
   📧 Email:    admin@authentikate.local
   🔑 Password: Xy9$kL2m@Qp3nR8t
   
   ⚠️  Please log in and change your password immediately!
   

2. Log in and change your password:

   • Navigate to your AuthentiKate URL
   • Log in with the generated credentials
   • Go to Settings → Profile to change your password

3. Configure your first application:

   • Go to Applications in the admin panel
   • Create a new OAuth application
   • Note the Client ID and Client Secret for your services

Manual Installation

Requirements

• PHP 8.2 or higher
• Composer
• Node.js 18+ and npm
• Database (SQLite, MySQL, or PostgreSQL)
• Web server (Apache, Nginx, etc.)

Installation Steps

1. Clone the repository:

   git clone <repository-url> authentikate
   cd authentikate
   

2. Install dependencies:

   composer install --no-dev --optimize-autoloader
   npm install && npm run build
   

3. Environment configuration:

   cp .env.example .env
   php artisan key:generate
   

4. Configure your .env file:

   APP_NAME=AuthentiKate
   APP_ENV=production
   APP_DEBUG=false
   APP_URL=https://auth.yourdomain.com
   
   # Database (SQLite example)
   DB_CONNECTION=sqlite
   DB_DATABASE=/path/to/database.sqlite
   
   # Mail configuration (for invitations)
   MAIL_MAILER=smtp
   MAIL_HOST=your-smtp-server
   MAIL_PORT=587
   MAIL_USERNAME=your-email
   MAIL_PASSWORD=your-password
   MAIL_ENCRYPTION=tls
   MAIL_FROM_ADDRESS=noreply@yourdomain.com
   MAIL_FROM_NAME="AuthentiKate"
   

5. Set up the database:

   php artisan migrate
   

6. Generate OIDC keys:

   php artisan app:generate-keys
   

7. Create initial admin user:

   php artisan authentikate:create-admin
   

8. Set up the web server: Configure your web server to serve the public directory. For Nginx:

   server {
       listen 80;
       server_name auth.yourdomain.com;
       root /path/to/authentikate/public;
       index index.php;
   
       location / {
           try_files $uri $uri/ /index.php?$query_string;
       }
   
       location ~ \.php$ {
           fastcgi_pass unix:/var/run/php/php8.2-fpm.sock;
           fastcgi_index index.php;
           fastcgi_param SCRIPT_FILENAME $realpath_root$fastcgi_script_name;
           include fastcgi_params;
       }
   }
   

9. Set up queue worker (optional but recommended):

   php artisan queue:work --tries=3 --daemon
   

Configuration

Environment Variables

Key environment variables for AuthentiKate:

• APP_URL: Your AuthentiKate instance URL (used in OIDC issuer)
• DB_*: Database connection settings
• MAIL_*: Email configuration for sending invitations
• SESSION_DRIVER: Session storage (database recommended for production)
• CACHE_DRIVER: Cache storage (redis recommended for production)

File Permissions

Ensure proper permissions for:

• storage/ directory: writable by web server
• storage/oauth/: contains RSA keys (600 for private key)
• bootstrap/cache/: writable by web server

SSL/TLS

Important: AuthentiKate should always run behind HTTPS in production. OIDC requires secure connections for security. Configure your reverse proxy or web server to handle SSL termination.

Usage

Managing Applications

1. Log in as an admin
2. Navigate to "Applications" in the sidebar
3. Click "New Application"
4. Fill in:
   • Name: Display name for your application
   • Redirect URI: The callback URL for your application
5. Save and note the generated Client ID and Client Secret

Managing Users

1. Navigate to "User Management"
2. Create invitations for new users by email
3. Optionally send invitation emails automatically
4. Users can register using the invitation code
5. Promote users to admin status as needed

User Features

• Profile Management: Users can update their name, email, and avatar
• Auto-Approval: Users can enable auto-approval for previously authorized apps
• Token Management: View and revoke active authentication tokens

Integration Examples

Grafana

# grafana.yml
auth:
  generic_oauth:
    enabled: true
    name: AuthentiKate
    client_id: your-client-id
    client_secret: your-client-secret
    scopes: openid profile email
    auth_url: https://auth.yourdomain.com/auth/authorize
    token_url: https://auth.yourdomain.com/auth/token
    api_url: https://auth.yourdomain.com/auth/userinfo
    use_pkce: true

Traefik ForwardAuth

# docker-compose.yml
version: '3.7'
services:
  traefik-forward-auth:
    image: thomseddon/traefik-forward-auth:2
    environment:
      - DEFAULT_PROVIDER=oidc
      - PROVIDERS_OIDC_ISSUER_URL=https://auth.yourdomain.com
      - PROVIDERS_OIDC_CLIENT_ID=your-client-id
      - PROVIDERS_OIDC_CLIENT_SECRET=your-client-secret
      - SECRET=your-secret-key
      - AUTH_HOST=auth.yourdomain.com
      - COOKIE_DOMAIN=yourdomain.com

Troubleshooting

Common Issues

1. "Invalid client" errors:

   • Verify Client ID and Client Secret
   • Check that redirect URI matches exactly

2. JWT verification failures:

   • Ensure RSA keys are properly generated
   • Check that /auth/keys endpoint is accessible

3. Email not working:

   • Verify MAIL_* environment variables
   • Check Laravel logs in storage/logs/laravel.log

4. Permission denied errors:

   • Check file permissions on storage directories
   • Ensure web server can write to storage/cache

Logs

Check the following logs for debugging:

• Application logs: storage/logs/laravel.log
• Web server logs: Check your web server's error logs
• Docker logs: docker logs <container_name>

Development

Running for Development

composer install
npm install
cp .env.example .env
php artisan key:generate
php artisan migrate
php artisan app:generate-keys
php artisan authentikate:create-admin

# Start development servers
composer run dev  # Starts server, queue, logs, and vite

Testing

composer run test

The test suite includes comprehensive coverage for:

• OIDC endpoints and JWT generation
• User authentication and authorization
• Application management
• UUID-based user identification

Security

• JWT tokens use RS256 signing with 2048-bit RSA keys
• PKCE support for secure authorization flows
• UUID-based user identification in tokens (not sequential IDs)
• Secure session management
• Input validation and CSRF protection
• Email verification for new users

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes with tests
4. Submit a pull request

License

[Add your license information here]

Support

For issues and questions:

• Check the troubleshooting section above
• Review logs for error details
• Open an issue on the repository

---

Remember: Always run AuthentiKate behind HTTPS in production and keep your instance updated with security patches.