# AuthentiKate ![banner](banner.gif) 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: ```bash # 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: ```bash docker logs ``` 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**: ```bash git clone authentikate cd authentikate ``` 2. **Install dependencies**: ```bash composer install --no-dev --optimize-autoloader npm install && npm run build ``` 3. **Environment configuration**: ```bash cp .env.example .env php artisan key:generate ``` 4. **Configure your `.env` file**: ```env 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**: ```bash php artisan migrate ``` 6. **Generate OIDC keys**: ```bash php artisan app:generate-keys ``` 7. **Create initial admin user**: ```bash php artisan authentikate:create-admin ``` 8. **Set up the web server**: Configure your web server to serve the `public` directory. For Nginx: ```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): ```bash 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 ```yaml # 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 ```yaml # 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 ` ## Development ### Running for Development ```bash 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 ```bash 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.