authentikate/README.md

# 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 <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**:
   ```bash
   git clone <repository-url> 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 <container_name>`

## 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.