thegrind/authentikate
4
0
Fork 0
generated from thegrind/laravel-dockerized
Code Issues Pull Requests Actions Packages Projects Releases 5 Wiki Activity

Remove docs from here
All checks were successful
linter / quality (push) Successful in 10m16s
Details
tests / ci (push) Successful in 12m58s
Details

Browse Source
This commit is contained in:
Javier Feliz 2025-08-03 18:54:24 -04:00
parent 9db9b0f6b3
commit 7ee4e5002e
12 changed files with 0 additions and 2760 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

89
docs/.vitepress/config.mjs
View File

@ -1,89 +0,0 @@
import { defineConfig } from 'vitepress'
// https://vitepress.dev/reference/site-config
export default defineConfig({
title: "AuthentiKate",
description: "A lightweight SSO/OIDC solution built for homelabbers",
head: [
['meta', { name: 'theme-color', content: '#3b82f6' }],
],
themeConfig: {
// https://vitepress.dev/reference/default-theme-config
logo: '/logo.svg',
nav: [
{ text: 'Home', link: '/' },
{ text: 'Guide', link: '/guide/installation' },
{ text: 'Configuration', link: '/config/environment' },
{ text: 'Integrations', link: '/integrations/overview' }
],
sidebar: {
'/guide/': [
{
text: 'Getting Started',
items: [
{ text: 'Installation', link: '/guide/installation' },
{ text: 'Quick Start', link: '/guide/quick-start' },
{ text: 'First Setup', link: '/guide/first-setup' }
]
},
{
text: 'User Management',
items: [
{ text: 'Creating Users', link: '/guide/users' },
{ text: 'Invitations', link: '/guide/invitations' },
{ text: 'User Profiles', link: '/guide/profiles' }
]
},
{
text: 'Applications',
items: [
{ text: 'Managing Apps', link: '/guide/applications' },
{ text: 'OAuth Configuration', link: '/guide/oauth' }
]
}
],
'/config/': [
{
text: 'Configuration',
items: [
{ text: 'Environment Variables', link: '/config/environment' },
{ text: 'Database Setup', link: '/config/database' },
{ text: 'Security Settings', link: '/config/security' },
{ text: 'Email Configuration', link: '/config/email' }
]
}
],
'/integrations/': [
{
text: 'Integrations',
items: [
{ text: 'Overview', link: '/integrations/overview' },
{ text: 'Grafana', link: '/integrations/grafana' },
{ text: 'Nextcloud', link: '/integrations/nextcloud' },
{ text: 'Traefik', link: '/integrations/traefik' },
{ text: 'Other Applications', link: '/integrations/generic' }
]
}
]
},
socialLinks: [
{ icon: 'github', link: 'https://github.com/jdubpark/authentikate' }
],
footer: {
message: 'Released under the MIT License.',
copyright: 'Copyright © 2024-present AuthentiKate'
},
editLink: {
pattern: 'https://github.com/jdubpark/authentikate/edit/main/docs/:path'
},
search: {
provider: 'local'
}
}
})

360
docs/config/email.md
View File

@ -1,360 +0,0 @@
# Email Configuration
Email is essential for user invitations, password resets, and account verification. This guide covers how to configure email in AuthentiKate.
## Why Email Matters
Email is used for:
- **User Invitations**: Send registration links to new users
- **Password Resets**: Allow users to reset forgotten passwords
- **Email Verification**: Verify user email addresses
- **Account Notifications**: Security alerts and updates
## Basic SMTP Configuration
Set these environment variables for SMTP email:
```bash
MAIL_MAILER=smtp
MAIL_HOST=your-smtp-server.com
MAIL_PORT=587
MAIL_USERNAME=your-email@domain.com
MAIL_PASSWORD=your-password
MAIL_ENCRYPTION=tls
MAIL_FROM_ADDRESS=auth@yourdomain.com
MAIL_FROM_NAME="AuthentiKate"
```
## Provider-Specific Configurations
### Gmail
```bash
MAIL_MAILER=smtp
MAIL_HOST=smtp.gmail.com
MAIL_PORT=587
MAIL_USERNAME=your-email@gmail.com
MAIL_PASSWORD=your-app-password # Not your regular Gmail password!
MAIL_ENCRYPTION=tls
MAIL_FROM_ADDRESS=your-email@gmail.com
MAIL_FROM_NAME="Your Name"
```
**Important**: Use an [App Password](https://support.google.com/accounts/answer/185833), not your regular Gmail password.
#### Creating Gmail App Password
1. Enable 2-Factor Authentication on your Google account
2. Go to **Google Account** → **Security** → **App passwords**
3. Generate a new app password for "Mail"
4. Use this 16-character password in `MAIL_PASSWORD`
### Outlook/Hotmail
```bash
MAIL_MAILER=smtp
MAIL_HOST=smtp-mail.outlook.com
MAIL_PORT=587
MAIL_USERNAME=your-email@outlook.com
MAIL_PASSWORD=your-password
MAIL_ENCRYPTION=tls
MAIL_FROM_ADDRESS=your-email@outlook.com
MAIL_FROM_NAME="Your Name"
```
### Custom Domain Email
If you have your own domain with email hosting:
```bash
MAIL_MAILER=smtp
MAIL_HOST=mail.yourdomain.com
MAIL_PORT=587
MAIL_USERNAME=auth@yourdomain.com
MAIL_PASSWORD=your-password
MAIL_ENCRYPTION=tls
MAIL_FROM_ADDRESS=auth@yourdomain.com
MAIL_FROM_NAME="AuthentiKate"
```
## Email Service Providers
### SendGrid
```bash
MAIL_MAILER=smtp
MAIL_HOST=smtp.sendgrid.net
MAIL_PORT=587
MAIL_USERNAME=apikey
MAIL_PASSWORD=your-sendgrid-api-key
MAIL_ENCRYPTION=tls
MAIL_FROM_ADDRESS=auth@yourdomain.com
MAIL_FROM_NAME="AuthentiKate"
```
### Mailgun
```bash
MAIL_MAILER=smtp
MAIL_HOST=smtp.mailgun.org
MAIL_PORT=587
MAIL_USERNAME=your-mailgun-username
MAIL_PASSWORD=your-mailgun-password
MAIL_ENCRYPTION=tls
MAIL_FROM_ADDRESS=auth@yourdomain.com
MAIL_FROM_NAME="AuthentiKate"
```
### Amazon SES
```bash
MAIL_MAILER=smtp
MAIL_HOST=email-smtp.us-east-1.amazonaws.com # Change region as needed
MAIL_PORT=587
MAIL_USERNAME=your-ses-smtp-username
MAIL_PASSWORD=your-ses-smtp-password
MAIL_ENCRYPTION=tls
MAIL_FROM_ADDRESS=auth@yourdomain.com
MAIL_FROM_NAME="AuthentiKate"
```
### Postmark
```bash
MAIL_MAILER=smtp
MAIL_HOST=smtp.postmarkapp.com
MAIL_PORT=587
MAIL_USERNAME=your-postmark-token
MAIL_PASSWORD=your-postmark-token
MAIL_ENCRYPTION=tls
MAIL_FROM_ADDRESS=auth@yourdomain.com
MAIL_FROM_NAME="AuthentiKate"
```
## Docker Compose Configuration
### Environment Variables
```yaml
services:
authentikate:
image: authentikate/authentikate:latest
environment:
# Gmail example
MAIL_MAILER: smtp
MAIL_HOST: smtp.gmail.com
MAIL_PORT: 587
MAIL_USERNAME: your-email@gmail.com
MAIL_PASSWORD: your-app-password
MAIL_ENCRYPTION: tls
MAIL_FROM_ADDRESS: your-email@gmail.com
MAIL_FROM_NAME: "AuthentiKate"
```
### Environment File
Create a `.env` file:
```bash
# Email configuration
MAIL_MAILER=smtp
MAIL_HOST=smtp.gmail.com
MAIL_PORT=587
MAIL_USERNAME=your-email@gmail.com
MAIL_PASSWORD=your-app-password
MAIL_ENCRYPTION=tls
MAIL_FROM_ADDRESS=your-email@gmail.com
MAIL_FROM_NAME="AuthentiKate"
```
Reference it in docker-compose.yml:
```yaml
services:
authentikate:
image: authentikate/authentikate:latest
env_file: .env
```
## Testing Email Configuration
### Send Test Email
AuthentiKate includes a command to test email sending:
```bash
# Test email configuration
docker exec -it authentikate php artisan tinker
# In the tinker console:
Mail::raw('Test email from AuthentiKate', function($message) {
$message->to('test@example.com')->subject('Test Email');
});
```
### Check Logs
If emails aren't sending, check the logs:
```bash
# View container logs
docker logs authentikate
# Look for email-related errors
docker logs authentikate 2>&1 | grep -i mail
```
## Advanced Configuration
### Custom SMTP Port
Some providers use different ports:
```bash
# Standard ports
MAIL_PORT=25 # Unencrypted (not recommended)
MAIL_PORT=587 # STARTTLS (recommended)
MAIL_PORT=465 # SSL/TLS
# Custom port
MAIL_PORT=2525 # Some providers use alternate ports
```
### SSL/TLS Configuration
```bash
# Use TLS (recommended)
MAIL_ENCRYPTION=tls
# Use SSL (older, but still secure)
MAIL_ENCRYPTION=ssl
# No encryption (not recommended)
MAIL_ENCRYPTION=null
```
### Multiple From Addresses
Configure different senders for different email types:
```bash
# Default sender
MAIL_FROM_ADDRESS=auth@yourdomain.com
MAIL_FROM_NAME="AuthentiKate"
# Admin notifications (configure in application)
ADMIN_EMAIL_FROM=admin@yourdomain.com
ADMIN_EMAIL_NAME="AuthentiKate Admin"
```
## Email Templates
AuthentiKate uses customizable email templates for different purposes:
### Invitation Email
- **Subject**: "You're invited to join AuthentiKate"
- **Content**: Welcome message with registration link
- **Action**: "Complete Registration" button
### Password Reset
- **Subject**: "Reset your AuthentiKate password"
- **Content**: Instructions for password reset
- **Action**: "Reset Password" button
### Email Verification
- **Subject**: "Verify your email address"
- **Content**: Verification instructions
- **Action**: "Verify Email" button
## Troubleshooting
### Common Issues
#### "Connection could not be established"
```
Swift_TransportException: Connection could not be established
```
**Solutions**:
- Check SMTP server address and port
- Verify firewall isn't blocking SMTP ports
- Try different encryption settings (TLS vs SSL)
#### "Authentication failed"
```
Swift_TransportException: Expected response code 235 but got code "535"
```
**Solutions**:
- Verify username and password
- Use App Password for Gmail
- Check if 2FA is enabled and requires app password
#### "From address not allowed"
```
Message: From address not allowed
```
**Solutions**:
- Ensure `MAIL_FROM_ADDRESS` matches authenticated user
- Configure your email provider to allow sending from this address
- Use provider's verified domain
### Debug Mode
Enable email debugging:
```bash
# Add to environment
LOG_LEVEL=debug
MAIL_LOG_CHANNEL=single
# Check detailed logs
docker logs authentikate | grep -i mail
```
### Test with Different Providers
If one provider doesn't work, try another:
```bash
# Try Gmail first (easiest to set up)
MAIL_HOST=smtp.gmail.com
# Then try SendGrid (good for production)
MAIL_HOST=smtp.sendgrid.net
# Or use a transactional service
MAIL_HOST=smtp.mailgun.org
```
## Production Recommendations
### Dedicated Email Service
For production, use a dedicated email service:
- **SendGrid**: Easy setup, good deliverability
- **Mailgun**: Reliable, detailed analytics
- **Amazon SES**: Cost-effective, AWS integration
- **Postmark**: Fast delivery, great for transactional emails
### Domain Authentication
Set up SPF, DKIM, and DMARC records:
```dns
# SPF record
yourdomain.com. TXT "v=spf1 include:_spf.google.com ~all"
# DKIM (provided by email service)
default._domainkey.yourdomain.com. TXT "v=DKIM1; k=rsa; p=..."
# DMARC
_dmarc.yourdomain.com. TXT "v=DMARC1; p=quarantine; rua=mailto:dmarc@yourdomain.com"
```
### Monitoring
Monitor email delivery:
- Track bounce rates
- Monitor spam complaints
- Watch delivery statistics
- Set up alerts for failures
Your email configuration is now ready! Users will receive professional-looking emails for invitations, password resets, and other notifications.

402
docs/config/environment.md
View File

@ -1,402 +0,0 @@
# Environment Variables
AuthentiKate is configured through environment variables. This page covers all available configuration options.
## Core Application Settings
### APP_URL
**Required** - The URL where AuthentiKate is accessible.
```bash
APP_URL=https://auth.yourdomain.com
```
::: warning
This URL must match exactly how users access AuthentiKate. OAuth redirects and JWT tokens depend on this value.
:::
### APP_ENV
**Default**: `production`
```bash
APP_ENV=production # or 'local' for development
```
### APP_DEBUG
**Default**: `false`
```bash
APP_DEBUG=false # Set to 'true' only for debugging
```
::: danger
Never set `APP_DEBUG=true` in production as it exposes sensitive information.
:::
### APP_KEY
**Auto-generated** - Laravel application key for encryption.
```bash
APP_KEY=base64:generated-key-here
```
The key is automatically generated on first run. Do not change this after deployment as it will invalidate existing sessions and tokens.
## Database Configuration
### SQLite (Default)
```bash
DB_CONNECTION=sqlite
DB_DATABASE=/var/www/html/storage/database/database.sqlite
```
### PostgreSQL
```bash
DB_CONNECTION=pgsql
DB_HOST=postgres
DB_PORT=5432
DB_DATABASE=authentikate
DB_USERNAME=authentikate
DB_PASSWORD=secure_password
```
### MySQL/MariaDB
```bash
DB_CONNECTION=mysql
DB_HOST=mysql
DB_PORT=3306
DB_DATABASE=authentikate
DB_USERNAME=authentikate
DB_PASSWORD=secure_password
```
## Email Configuration
Email is used for user invitations, password resets, and verification.
### SMTP
```bash
MAIL_MAILER=smtp
MAIL_HOST=smtp.gmail.com
MAIL_PORT=587
MAIL_USERNAME=your-email@gmail.com
MAIL_PASSWORD=your-app-password
MAIL_ENCRYPTION=tls
MAIL_FROM_ADDRESS=auth@yourdomain.com
MAIL_FROM_NAME="AuthentiKate"
```
### Common SMTP Providers
#### Gmail
```bash
MAIL_MAILER=smtp
MAIL_HOST=smtp.gmail.com
MAIL_PORT=587
MAIL_USERNAME=your-email@gmail.com
MAIL_PASSWORD=your-app-password # Use App Password, not regular password
MAIL_ENCRYPTION=tls
```
#### Outlook/Hotmail
```bash
MAIL_MAILER=smtp
MAIL_HOST=smtp-mail.outlook.com
MAIL_PORT=587
MAIL_USERNAME=your-email@outlook.com
MAIL_PASSWORD=your-password
MAIL_ENCRYPTION=tls
```
#### SendGrid
```bash
MAIL_MAILER=smtp
MAIL_HOST=smtp.sendgrid.net
MAIL_PORT=587
MAIL_USERNAME=apikey
MAIL_PASSWORD=your-sendgrid-api-key
MAIL_ENCRYPTION=tls
```
#### Mailgun
```bash
MAIL_MAILER=smtp
MAIL_HOST=smtp.mailgun.org
MAIL_PORT=587
MAIL_USERNAME=your-mailgun-username
MAIL_PASSWORD=your-mailgun-password
MAIL_ENCRYPTION=tls
```
### Disable Email
```bash
MAIL_MAILER=log # Emails will be written to logs instead of sent
```
## Cache Configuration
### Redis (Recommended for Production)
```bash
CACHE_DRIVER=redis
REDIS_HOST=redis
REDIS_PORT=6379
REDIS_PASSWORD=your-redis-password
```
### File Cache (Default)
```bash
CACHE_DRIVER=file
```
### Database Cache
```bash
CACHE_DRIVER=database
```
## Session Configuration
### Redis Sessions (Recommended for Production)
```bash
SESSION_DRIVER=redis
SESSION_LIFETIME=120 # Minutes
```
### File Sessions (Default)
```bash
SESSION_DRIVER=file
SESSION_LIFETIME=120
```
### Database Sessions
```bash
SESSION_DRIVER=database
```
## Security Settings
### SSL/HTTPS
```bash
# Force HTTPS redirects
FORCE_HTTPS=true
# Set secure cookie settings
SESSION_SECURE_COOKIE=true
SANCTUM_STATEFUL_DOMAINS=auth.yourdomain.com
```
### CORS Configuration
```bash
# Allow CORS for your domains
CORS_ALLOWED_ORIGINS=https://yourdomain.com,https://app.yourdomain.com
```
## Logging
### Log Level
```bash
LOG_LEVEL=info # debug, info, notice, warning, error, critical, alert, emergency
```
### Log Channel
```bash
LOG_CHANNEL=stack # single, daily, slack, syslog, errorlog
```
### Daily Log Rotation
```bash
LOG_CHANNEL=daily
LOG_DAILY_DAYS=14 # Keep logs for 14 days
```
## Queue Configuration
For background job processing:
### Redis Queue
```bash
QUEUE_CONNECTION=redis
```
### Database Queue
```bash
QUEUE_CONNECTION=database
```
### Sync Queue (Default)
```bash
QUEUE_CONNECTION=sync # Process jobs immediately
```
## OAuth/OIDC Settings
### Token Lifetimes
```bash
# Access token lifetime (in minutes)
OAUTH_ACCESS_TOKEN_LIFETIME=60
# Refresh token lifetime (in days)
OAUTH_REFRESH_TOKEN_LIFETIME=30
# Authorization code lifetime (in minutes)
OAUTH_AUTHORIZATION_CODE_LIFETIME=10
```
### JWT Configuration
```bash
# JWT algorithm (default: RS256)
JWT_ALGORITHM=RS256
# Key paths (automatically set)
OAUTH_PRIVATE_KEY_PATH=storage/oauth/private.pem
OAUTH_PUBLIC_KEY_PATH=storage/oauth/public.pem
```
## Performance Settings
### PHP Configuration
```bash
# Memory limit
PHP_MEMORY_LIMIT=256M
# Upload limits
PHP_UPLOAD_MAX_FILESIZE=10M
PHP_POST_MAX_SIZE=10M
# Execution time
PHP_MAX_EXECUTION_TIME=300
```
### Application Optimization
```bash
# Enable optimizations for production
APP_OPTIMIZE=true
# Cache configuration
CONFIG_CACHE=true
ROUTE_CACHE=true
VIEW_CACHE=true
```
## Development Settings
These should only be used in development environments:
```bash
APP_ENV=local
APP_DEBUG=true
LOG_LEVEL=debug
# Disable HTTPS for local development
FORCE_HTTPS=false
SESSION_SECURE_COOKIE=false
```
## Complete Production Example
Here's a complete environment configuration for production:
```bash
# Application
APP_ENV=production
APP_DEBUG=false
APP_URL=https://auth.yourdomain.com
FORCE_HTTPS=true
# Database
DB_CONNECTION=pgsql
DB_HOST=postgres
DB_DATABASE=authentikate
DB_USERNAME=authentikate
DB_PASSWORD=secure_database_password
# Email
MAIL_MAILER=smtp
MAIL_HOST=smtp.gmail.com
MAIL_PORT=587
MAIL_USERNAME=auth@yourdomain.com
MAIL_PASSWORD=gmail_app_password
MAIL_ENCRYPTION=tls
MAIL_FROM_ADDRESS=auth@yourdomain.com
MAIL_FROM_NAME="Your Company Auth"
# Cache & Sessions
CACHE_DRIVER=redis
SESSION_DRIVER=redis
REDIS_HOST=redis
REDIS_PASSWORD=secure_redis_password
# Security
SESSION_SECURE_COOKIE=true
SESSION_LIFETIME=120
SANCTUM_STATEFUL_DOMAINS=yourdomain.com
# Performance
LOG_LEVEL=warning
LOG_CHANNEL=daily
LOG_DAILY_DAYS=30
```
## Docker Compose Integration
Add environment variables to your `docker-compose.yml`:
```yaml
services:
authentikate:
image: authentikate/authentikate:latest
environment:
- APP_URL=https://auth.yourdomain.com
- APP_ENV=production
- DB_CONNECTION=pgsql
- DB_HOST=postgres
- MAIL_MAILER=smtp
- MAIL_HOST=smtp.gmail.com
# ... other variables
env_file:
- .env # Or load from file
```
## Environment File
Create a `.env` file for easier management:
```bash
# Create environment file
cat > .env << 'EOF'
APP_URL=https://auth.yourdomain.com
APP_ENV=production
DB_CONNECTION=pgsql
# ... other settings
EOF
# Reference in docker-compose.yml
services:
authentikate:
env_file: .env
```
::: tip
Keep your `.env` file secure and never commit it to version control.
:::

188
docs/guide/applications.md
View File

@ -1,188 +0,0 @@
# Managing Applications
Learn how to create and manage OAuth applications in AuthentiKate.
## Creating Applications
### Via Web Interface
1. **Navigate** to **Applications** in the admin panel
2. **Click** "Create Application"
3. **Fill in** the application details:
- **Name**: Display name for your application
- **Redirect URI**: OAuth callback URL
- **Icon**: Optional icon URL for the application
4. **Save** the application
### Application Details
Each application gets:
- **Unique Client ID**: Public identifier for your application
- **Client Secret**: Private key for token exchange
- **Redirect URI**: Where users return after authentication
::: warning
Keep your Client Secret secure! It should never be exposed in client-side code.
:::
## Application Templates
AuthentiKate includes templates for popular applications:
### Available Templates
- **Grafana**: Analytics and monitoring
- **Nextcloud**: File sharing and collaboration
- **Proxmox**: Virtualization management
- **Portainer**: Docker container management
- **GitLab**: Git repository hosting
Templates automatically configure:
- Correct redirect URI patterns
- Appropriate application icons
- Common configuration settings
## OAuth Configuration
### Client Credentials
```yaml
Client ID: f47ac10b-58cc-4372-a567-0e02b2c3d479
Client Secret: 40-character-random-string
```
### Endpoints
Your applications will use these endpoints:
- **Authorization**: `/oauth/authorize`
- **Token**: `/oauth/token`
- **User Info**: `/oauth/userinfo`
- **JWKS**: `/.well-known/jwks.json`
### Supported Features
- **Authorization Code Flow**: Standard OAuth2 flow
- **PKCE**: Enhanced security for public clients
- **JWT Tokens**: Signed with RSA256
- **Refresh Tokens**: Long-lived token renewal
## Security Best Practices
### Redirect URI Validation
- Use exact URI matching
- Always use HTTPS in production
- Avoid wildcard redirects
### Client Secret Management
- Store secrets securely
- Rotate secrets regularly
- Use different secrets per environment
### Token Handling
- Validate token signatures
- Respect token expiration
- Implement proper logout
## Common Integration Patterns
### Server-Side Applications
Best for applications that can securely store client secrets:
```javascript
// Example: Node.js application
const config = {
clientId: 'your-client-id',
clientSecret: 'your-client-secret',
authorizationURL: 'https://auth.yourdomain.com/oauth/authorize',
tokenURL: 'https://auth.yourdomain.com/oauth/token',
callbackURL: 'https://yourapp.com/auth/callback'
};
```
### Single Page Applications (SPA)
For client-side applications using PKCE:
```javascript
// Example: React application with PKCE
const config = {
clientId: 'your-client-id',
// No client secret for public clients
authorizationURL: 'https://auth.yourdomain.com/oauth/authorize',
tokenURL: 'https://auth.yourdomain.com/oauth/token',
redirectUri: 'https://yourapp.com/callback',
usePKCE: true
};
```
### Mobile Applications
Similar to SPAs, always use PKCE:
```swift
// Example: iOS Swift
let config = OIDServiceConfiguration(
authorizationEndpoint: URL(string: "https://auth.yourdomain.com/oauth/authorize")!,
tokenEndpoint: URL(string: "https://auth.yourdomain.com/oauth/token")!
)
```
## Testing Applications
### Manual Testing
1. **Start OAuth flow** from your application
2. **Verify redirect** to AuthentiKate
3. **Complete authentication**
4. **Confirm successful** return to your app
5. **Check user data** is populated correctly
### Automated Testing
```bash
# Test authorization endpoint
curl "https://auth.yourdomain.com/oauth/authorize?client_id=YOUR_CLIENT_ID&redirect_uri=YOUR_REDIRECT_URI&response_type=code&scope=openid"
# Test token exchange (after getting auth code)
curl -X POST https://auth.yourdomain.com/oauth/token \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "grant_type=authorization_code&code=AUTH_CODE&client_id=CLIENT_ID&client_secret=CLIENT_SECRET&redirect_uri=REDIRECT_URI"
```
## Troubleshooting
### Invalid Redirect URI
**Error**: `The redirect URI is invalid`
**Solutions**:
- Verify exact URL match in application settings
- Check for trailing slashes
- Ensure HTTPS is used
### Invalid Client
**Error**: `Client authentication failed`
**Solutions**:
- Verify Client ID and Secret
- Check that application exists and is active
- Ensure secrets haven't been regenerated
### Token Validation Issues
**Error**: `Invalid token signature`
**Solutions**:
- Use JWKS endpoint for signature validation
- Verify token hasn't expired
- Check token issuer matches AuthentiKate URL
## Application Management
### Updating Applications
- **Edit** application details anytime
- **Regenerate** client secrets if compromised
- **Update** redirect URIs for new environments
### Deactivating Applications
- **Disable** applications to prevent new logins
- Existing tokens remain valid until expiration
- **Re-enable** anytime to restore access
### Monitoring Usage
View application usage in the admin panel:
- **Active tokens** per application
- **Recent authentications**
- **User access patterns**
Your applications are now ready for OAuth integration with AuthentiKate!

202
docs/guide/first-setup.md
View File

@ -1,202 +0,0 @@
# First Setup
After installing AuthentiKate, you'll want to complete the initial configuration to make it ready for production use.
## Initial Login
When you first start AuthentiKate, it automatically creates an admin user. The credentials are shown in the container logs:
```bash
docker logs authentikate
```
Look for:
```
✅ Initial admin user created:
Email: admin@authentikate.local
Password: randomly-generated-password
```
::: tip
Save these credentials securely! You'll need them to access the admin interface.
:::
## Admin Dashboard
After logging in, you'll see the AuthentiKate dashboard with:
- **Applications**: Manage OAuth applications
- **Users**: User management and invitations
- **Tokens**: View active authentication tokens
- **Profile**: Your user profile settings
## Essential Configuration Steps
### 1. Update Your Profile
1. Click your avatar in the top right
2. Select **"Profile"**
3. Update your information:
- Change the email from `admin@authentikate.local` to your real email
- Set a preferred username
- Upload an avatar (optional)
- **Change your password** to something secure
### 2. Configure Email (Recommended)
Email is used for:
- User invitations
- Password resets
- Account verification
Set up email by updating your environment variables:
```yaml
environment:
MAIL_MAILER: smtp
MAIL_HOST: smtp.gmail.com
MAIL_PORT: 587
MAIL_USERNAME: your-email@gmail.com
MAIL_PASSWORD: your-app-password
MAIL_ENCRYPTION: tls
MAIL_FROM_ADDRESS: auth@yourdomain.com
MAIL_FROM_NAME: "AuthentiKate"
```
[→ See full email configuration guide](/config/email)
### 3. Set Your Domain
Update the `APP_URL` to match your actual domain:
```yaml
environment:
APP_URL: https://auth.yourdomain.com
```
This ensures:
- Correct OAuth redirect URLs
- Proper JWT issuer claims
- Working email links
### 4. Create Your First Application
1. Go to **Applications** → **Create Application**
2. Fill in the basic information:
- **Name**: Your application name (e.g., "Grafana")
- **Redirect URI**: Where users return after authentication
- **Icon**: Optional app icon URL
3. Note the generated **Client ID** and **Client Secret**
4. Use these in your application's OAuth configuration
## Security Checklist
Before going to production, verify these security settings:
### ✅ Admin Account
- [ ] Changed default admin email
- [ ] Set a strong, unique password
- [ ] Enabled email verification (if email is configured)
### ✅ Environment
- [ ] Set `APP_ENV=production`
- [ ] Set `APP_DEBUG=false`
- [ ] Using HTTPS with valid SSL certificate
- [ ] `APP_URL` matches your actual domain
### ✅ Database
- [ ] Using persistent volume for data
- [ ] Consider using PostgreSQL/MySQL for production
- [ ] Regular backups configured
### ✅ Reverse Proxy
- [ ] Proper SSL termination
- [ ] Security headers configured
- [ ] Rate limiting in place
## Application Integration
### OIDC Endpoints
Your applications will need these endpoints:
| Endpoint | URL |
|----------|-----|
| Authorization | `https://auth.yourdomain.com/oauth/authorize` |
| Token | `https://auth.yourdomain.com/oauth/token` |
| User Info | `https://auth.yourdomain.com/oauth/userinfo` |
| JWKS | `https://auth.yourdomain.com/.well-known/jwks.json` |
| Discovery | `https://auth.yourdomain.com/.well-known/openid_configuration` |
### OAuth Flow
1. **User clicks login** in your application
2. **Redirect to AuthentiKate** with authorization request
3. **User authenticates** (if not already logged in)
4. **User consents** to application access (if required)
5. **Redirect back** to your application with authorization code
6. **Exchange code** for access token and ID token
7. **Access user info** using the access token
## User Management
### Invitation System
AuthentiKate uses an invitation-based registration system:
1. **Admin creates invitation** with user's email
2. **Invitation email sent** with registration link
3. **User completes registration** using the invitation
4. **User can access applications** they're authorized for
### User Permissions
- **Admin users**: Full access to manage applications and users
- **Regular users**: Can only access authorized applications and manage their own profile
## Backup Strategy
Set up regular backups of your AuthentiKate data:
### SQLite (Default)
```bash
# Daily backup script
#!/bin/bash
docker exec authentikate cp /var/www/html/storage/database/database.sqlite /tmp/backup.sqlite
docker cp authentikate:/tmp/backup.sqlite ./backups/authentikate-$(date +%Y%m%d).sqlite
```
### Full Volume Backup
```bash
# Backup all persistent data
docker run --rm -v authentikate_data:/data -v $(pwd)/backups:/backup alpine tar czf /backup/authentikate-full-$(date +%Y%m%d).tar.gz -C /data .
```
## Common Next Steps
### Popular Integrations
- [Set up Grafana SSO](/integrations/grafana)
- [Configure Nextcloud authentication](/integrations/nextcloud)
- [Integrate with Traefik forward auth](/integrations/traefik)
### Advanced Configuration
- [Environment variables reference](/config/environment)
- [Database configuration](/config/database)
- [Security settings](/config/security)
### User Management
- [Create user invitations](/guide/invitations)
- [Manage user profiles](/guide/profiles)
- [Handle user permissions](/guide/users)
## Getting Help
If you run into issues:
1. **Check the logs**: `docker logs authentikate`
2. **Verify configuration**: Compare with working examples
3. **Test endpoints**: Use curl or Postman to test OIDC endpoints
4. **Community support**: Check GitHub issues and discussions
Your AuthentiKate instance is now ready for production use! 🎉

259
docs/guide/installation.md
View File

@ -1,259 +0,0 @@
# Installation
AuthentiKate is designed to be deployed easily with Docker, making it perfect for homelab environments. This guide will walk you through different installation methods.
## Quick Start with Docker
The fastest way to get AuthentiKate running is with Docker:
```bash
docker run -d \
--name authentikate \
-p 8080:8080 \
-e APP_URL=http://localhost:8080 \
-v authentikate_data:/var/www/html/storage \
authentikate/authentikate:latest
```
AuthentiKate will be available at `http://localhost:8080` with automatic setup completing in the background.
## Docker Compose (Recommended)
For production use, we recommend using Docker Compose for better configuration management:
```yaml
version: '3.8'
services:
authentikate:
image: authentikate/authentikate:latest
container_name: authentikate
restart: unless-stopped
ports:
- "8080:8080"
environment:
# Required
APP_URL: https://auth.yourdomain.com
APP_ENV: production
# Database (SQLite by default)
DB_CONNECTION: sqlite
# Email (optional but recommended)
MAIL_MAILER: smtp
MAIL_HOST: your-smtp-server.com
MAIL_PORT: 587
MAIL_USERNAME: your-email@domain.com
MAIL_PASSWORD: your-password
MAIL_ENCRYPTION: tls
MAIL_FROM_ADDRESS: auth@yourdomain.com
MAIL_FROM_NAME: "AuthentiKate"
volumes:
- authentikate_data:/var/www/html/storage
- authentikate_logs:/var/www/html/storage/logs
# Optional: Use external database
# depends_on:
# - postgres
labels:
# Traefik labels (if using Traefik)
- "traefik.enable=true"
- "traefik.http.routers.authentikate.rule=Host(`auth.yourdomain.com`)"
- "traefik.http.routers.authentikate.entrypoints=websecure"
- "traefik.http.routers.authentikate.tls.certresolver=letsencrypt"
- "traefik.http.services.authentikate.loadbalancer.server.port=8080"
volumes:
authentikate_data:
authentikate_logs:
```
## Environment Variables
### Required Variables
| Variable | Description | Example |
|----------|-------------|---------|
| `APP_URL` | The URL where AuthentiKate will be accessible | `https://auth.yourdomain.com` |
### Optional Variables
| Variable | Default | Description |
|----------|---------|-------------|
| `APP_ENV` | `production` | Application environment |
| `APP_DEBUG` | `false` | Enable debug mode |
| `DB_CONNECTION` | `sqlite` | Database type (`sqlite`, `mysql`, `postgres`) |
| `DB_DATABASE` | `/var/www/html/storage/database/database.sqlite` | Database path/name |
## Database Options
### SQLite (Default)
Perfect for most homelab setups. No additional configuration required.
### PostgreSQL
For larger installations:
```yaml
services:
postgres:
image: postgres:15
environment:
POSTGRES_DB: authentikate
POSTGRES_USER: authentikate
POSTGRES_PASSWORD: secure_password
volumes:
- postgres_data:/var/lib/postgresql/data
authentikate:
# ... other config
environment:
DB_CONNECTION: pgsql
DB_HOST: postgres
DB_DATABASE: authentikate
DB_USERNAME: authentikate
DB_PASSWORD: secure_password
depends_on:
- postgres
volumes:
postgres_data:
```
### MySQL/MariaDB
```yaml
services:
mysql:
image: mariadb:10
environment:
MYSQL_DATABASE: authentikate
MYSQL_USER: authentikate
MYSQL_PASSWORD: secure_password
MYSQL_ROOT_PASSWORD: root_password
volumes:
- mysql_data:/var/lib/mysql
authentikate:
# ... other config
environment:
DB_CONNECTION: mysql
DB_HOST: mysql
DB_DATABASE: authentikate
DB_USERNAME: authentikate
DB_PASSWORD: secure_password
depends_on:
- mysql
volumes:
mysql_data:
```
## Reverse Proxy Setup
### Traefik
AuthentiKate works perfectly with Traefik. Add these labels to your Docker Compose:
```yaml
labels:
- "traefik.enable=true"
- "traefik.http.routers.authentikate.rule=Host(`auth.yourdomain.com`)"
- "traefik.http.routers.authentikate.entrypoints=websecure"
- "traefik.http.routers.authentikate.tls.certresolver=letsencrypt"
- "traefik.http.services.authentikate.loadbalancer.server.port=8080"
```
### Nginx
```nginx
server {
listen 443 ssl http2;
server_name auth.yourdomain.com;
ssl_certificate /path/to/cert.pem;
ssl_certificate_key /path/to/key.pem;
location / {
proxy_pass http://localhost:8080;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
}
}
```
### Caddy
```caddyfile
auth.yourdomain.com {
reverse_proxy localhost:8080
}
```
## First Run
When you first start AuthentiKate, it will automatically:
1. **Generate RSA Keys**: Creates public/private key pair for JWT signing
2. **Run Database Migrations**: Sets up all necessary database tables
3. **Create Admin User**: Generates an initial admin account
The initial admin credentials will be displayed in the container logs:
```bash
docker logs authentikate
```
Look for output like:
```
✅ Initial admin user created:
Email: admin@authentikate.local
Password: randomly-generated-password
```
## Updating
To update AuthentiKate:
```bash
# Pull the latest image
docker pull authentikate/authentikate:latest
# Stop and remove the old container
docker stop authentikate
docker rm authentikate
# Start with the new image
docker-compose up -d
```
Your data will be preserved in the Docker volumes.
## Backup
### Database Backup (SQLite)
```bash
# Create backup
docker exec authentikate cp /var/www/html/storage/database/database.sqlite /tmp/backup.sqlite
docker cp authentikate:/tmp/backup.sqlite ./authentikate-backup-$(date +%Y%m%d).sqlite
# Restore backup
docker cp ./authentikate-backup-20240101.sqlite authentikate:/tmp/restore.sqlite
docker exec authentikate cp /tmp/restore.sqlite /var/www/html/storage/database/database.sqlite
```
### Full Data Backup
```bash
# Backup all data
docker run --rm -v authentikate_data:/data -v $(pwd):/backup alpine tar czf /backup/authentikate-data-$(date +%Y%m%d).tar.gz -C /data .
# Restore data
docker run --rm -v authentikate_data:/data -v $(pwd):/backup alpine tar xzf /backup/authentikate-data-20240101.tar.gz -C /data
```
## Next Steps
Once AuthentiKate is running:
1. [Complete the first setup →](/guide/first-setup)
2. [Configure your first application →](/guide/applications)
3. [Set up email notifications →](/config/email)

159
docs/guide/quick-start.md
View File

@ -1,159 +0,0 @@
# Quick Start
This guide will get you up and running with AuthentiKate in under 5 minutes.
## Prerequisites
- Docker installed on your system
- A domain name (optional, can use localhost for testing)
## Step 1: Deploy AuthentiKate
Run the following command to start AuthentiKate:
```bash
docker run -d \
--name authentikate \
-p 8080:8080 \
-e APP_URL=http://localhost:8080 \
-v authentikate_data:/var/www/html/storage \
authentikate/authentikate:latest
```
## Step 2: Get Your Admin Credentials
AuthentiKate automatically creates an admin user on first run. Get the credentials from the logs:
```bash
docker logs authentikate
```
Look for output like:
```
✅ Initial admin user created:
Email: admin@authentikate.local
Password: Xy9#mK2$vB8nQ4!p
```
## Step 3: Access the Interface
1. Open your browser and go to `http://localhost:8080`
2. Log in with the admin credentials from Step 2
3. You'll be taken to the AuthentiKate dashboard
## Step 4: Create Your First Application
1. Click **"Applications"** in the navigation
2. Click **"Create Application"**
3. Fill in the details:
- **Name**: `Test App`
- **Redirect URI**: `http://localhost:3000/auth/callback`
- **Client ID**: (auto-generated)
- **Client Secret**: (auto-generated)
4. Click **"Save"**
## Step 5: Test the Integration
Your application is now configured! Here are the OIDC endpoints you'll need:
- **Authorization**: `http://localhost:8080/oauth/authorize`
- **Token**: `http://localhost:8080/oauth/token`
- **User Info**: `http://localhost:8080/oauth/userinfo`
- **JWKS**: `http://localhost:8080/.well-known/jwks.json`
- **Discovery**: `http://localhost:8080/.well-known/openid_configuration`
## Common Integration Examples
### Test with curl
```bash
# Get authorization URL (replace CLIENT_ID with your actual client ID)
CLIENT_ID="your-client-id"
REDIRECT_URI="http://localhost:3000/auth/callback"
echo "Visit this URL to authorize:"
echo "http://localhost:8080/oauth/authorize?client_id=${CLIENT_ID}&redirect_uri=${REDIRECT_URI}&response_type=code&scope=openid profile email"
```
### Simple HTML Test Page
Create a simple test page to try the OAuth flow:
```html
<!DOCTYPE html>
<html>
<head>
<title>AuthentiKate Test</title>
</head>
<body>
<h1>AuthentiKate OAuth Test</h1>
<button onclick="authenticate()">Login with AuthentiKate</button>
<script>
function authenticate() {
const clientId = 'your-client-id'; // Replace with your actual client ID
const redirectUri = 'http://localhost:3000/auth/callback';
const authUrl = `http://localhost:8080/oauth/authorize?client_id=${clientId}&redirect_uri=${redirectUri}&response_type=code&scope=openid profile email`;
window.location.href = authUrl;
}
</script>
</body>
</html>
```
## What's Next?
Now that you have AuthentiKate running:
### Configure Your Environment
- [Set up email notifications](/config/email)
- [Configure a custom domain](/config/environment)
- [Set up reverse proxy](/guide/installation#reverse-proxy-setup)
### Add Real Applications
- [Integrate with Grafana](/integrations/grafana)
- [Set up Nextcloud SSO](/integrations/nextcloud)
- [Configure other applications](/integrations/generic)
### Manage Users
- [Create user invitations](/guide/invitations)
- [Set up user profiles](/guide/profiles)
- [Configure user permissions](/guide/users)
### Production Setup
- [Use PostgreSQL/MySQL](/guide/installation#database-options)
- [Set up proper email](/config/email)
- [Configure security settings](/config/security)
## Troubleshooting
### Can't access AuthentiKate?
- Make sure the container is running: `docker ps`
- Check the logs: `docker logs authentikate`
- Verify the port is accessible: `curl http://localhost:8080`
### Forgot admin password?
Reset it by running:
```bash
docker exec -it authentikate php artisan app:create-initial-admin --force
```
### Need to change the URL?
Update the `APP_URL` environment variable and restart:
```bash
docker stop authentikate
docker rm authentikate
# Run again with new APP_URL
```
### Container won't start?
Check for port conflicts:
```bash
# See what's using port 8080
sudo netstat -tulpn | grep 8080
# Use a different port
docker run -d --name authentikate -p 8081:8080 ...
```

75
docs/index.md
View File

@ -1,75 +0,0 @@
---
# https://vitepress.dev/reference/default-theme-home-page
layout: home
hero:
name: "AuthentiKate"
text: "SSO/OIDC for Homelabbers"
tagline: A lightweight, self-hosted authentication solution that just works
image:
src: /logo.svg
alt: AuthentiKate
actions:
- theme: brand
text: Get Started
link: /guide/installation
- theme: alt
text: View on GitHub
link: https://github.com/jdubpark/authentikate
features:
- icon: 🔐
title: OpenID Connect Ready
details: Full OIDC compliance with JWT tokens, PKCE support, and industry-standard security practices. Integrate with any OAuth2/OIDC compatible application.
- icon: 🐳
title: Docker First
details: Single container deployment with automatic setup. No complex configuration files or multi-service orchestration required.
- icon: ⚡
title: Built for Speed
details: Powered by Laravel and optimized for homelab environments. Fast authentication flows and minimal resource usage.
- icon: 🎨
title: Beautiful Interface
details: Clean, modern UI built with Livewire and Tailwind CSS. Intuitive user management and application configuration.
- icon: 🔄
title: Auto-Configuration
details: Automatic RSA key generation, database setup, and admin user creation. Zero manual configuration needed.
- icon: 🏠
title: Homelab Optimized
details: Perfect for self-hosters. Integrates seamlessly with Traefik, includes popular app presets, and supports local networks.
- icon: 👥
title: User Management
details: Invitation-based registration, user profiles with avatars, and granular permission controls. Keep your homelab secure.
- icon: 📱
title: Modern Features
details: JWT tokens with UUID-based user identification, token management, and comprehensive audit logging.
---
## Why AuthentiKate?
AuthentiKate is designed specifically for homelabbers who want enterprise-grade authentication without the enterprise complexity. Unlike heavyweight solutions that require extensive setup and maintenance, AuthentiKate gets you up and running in minutes.
### Perfect for Your Homelab
- **One Container**: Deploy with a single Docker command
- **Zero Config**: Automatic setup with sensible defaults
- **Popular Apps**: Pre-configured templates for Grafana, Nextcloud, and more
- **Reverse Proxy Ready**: Works seamlessly with Traefik and other proxies
### Enterprise Features, Homelab Simplicity
- Full OpenID Connect compliance
- JWT tokens with RSA256 signing
- PKCE support for mobile apps
- Invitation-based user registration
- Comprehensive token management
- Beautiful, responsive interface
Ready to secure your homelab? [Get started in minutes →](/guide/installation)

322
docs/integrations/grafana.md
View File

@ -1,322 +0,0 @@
# Grafana Integration
This guide shows how to integrate Grafana with AuthentiKate for single sign-on authentication.
## Prerequisites
- AuthentiKate running and accessible
- Grafana instance (Docker or standalone)
- Admin access to both systems
## Step 1: Create Application in AuthentiKate
1. Log into your AuthentiKate admin panel
2. Navigate to **Applications** → **Create Application**
3. Fill in the application details:
```
Name: Grafana
Redirect URI: https://grafana.yourdomain.com/login/generic_oauth
Icon: https://cdn.jsdelivr.net/gh/selfhst/icons/webp/grafana.webp
```
4. Click **Save** and note the generated:
- **Client ID**
- **Client Secret**
## Step 2: Configure Grafana
### Environment Variables (Docker)
Add these environment variables to your Grafana container:
```yaml
services:
grafana:
image: grafana/grafana:latest
environment:
# OAuth Settings
GF_AUTH_GENERIC_OAUTH_ENABLED: "true"
GF_AUTH_GENERIC_OAUTH_NAME: "AuthentiKate"
GF_AUTH_GENERIC_OAUTH_CLIENT_ID: "your-client-id"
GF_AUTH_GENERIC_OAUTH_CLIENT_SECRET: "your-client-secret"
GF_AUTH_GENERIC_OAUTH_SCOPES: "openid profile email"
GF_AUTH_GENERIC_OAUTH_AUTH_URL: "https://auth.yourdomain.com/oauth/authorize"
GF_AUTH_GENERIC_OAUTH_TOKEN_URL: "https://auth.yourdomain.com/oauth/token"
GF_AUTH_GENERIC_OAUTH_API_URL: "https://auth.yourdomain.com/oauth/userinfo"
# Auto-login (optional)
GF_AUTH_OAUTH_AUTO_LOGIN: "true"
GF_AUTH_DISABLE_LOGIN_FORM: "true"
# User mapping
GF_AUTH_GENERIC_OAUTH_LOGIN_ATTRIBUTE_PATH: "preferred_username"
GF_AUTH_GENERIC_OAUTH_NAME_ATTRIBUTE_PATH: "name"
GF_AUTH_GENERIC_OAUTH_EMAIL_ATTRIBUTE_PATH: "email"
# Role mapping (optional)
GF_AUTH_GENERIC_OAUTH_ROLE_ATTRIBUTE_PATH: "contains(groups[*], 'admin') && 'Admin' || 'Viewer'"
```
### Configuration File
Alternatively, configure via `grafana.ini`:
```ini
[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/oauth/authorize
token_url = https://auth.yourdomain.com/oauth/token
api_url = https://auth.yourdomain.com/oauth/userinfo
# Auto-login
auto_login = true
# User attribute mapping
login_attribute_path = preferred_username
name_attribute_path = name
email_attribute_path = email
# Role mapping (optional)
role_attribute_path = contains(groups[*], 'admin') && 'Admin' || 'Viewer'
[auth]
# Disable regular login form (optional)
disable_login_form = true
# Allow sign up
oauth_auto_login = true
```
## Step 3: Docker Compose Example
Complete Docker Compose configuration:
```yaml
version: '3.8'
services:
grafana:
image: grafana/grafana:latest
container_name: grafana
restart: unless-stopped
ports:
- "3000:3000"
environment:
# Basic settings
GF_SECURITY_ADMIN_PASSWORD: admin
GF_INSTALL_PLUGINS: grafana-piechart-panel
# OAuth with AuthentiKate
GF_AUTH_GENERIC_OAUTH_ENABLED: "true"
GF_AUTH_GENERIC_OAUTH_NAME: "AuthentiKate"
GF_AUTH_GENERIC_OAUTH_CLIENT_ID: "your-client-id-here"
GF_AUTH_GENERIC_OAUTH_CLIENT_SECRET: "your-client-secret-here"
GF_AUTH_GENERIC_OAUTH_SCOPES: "openid profile email"
GF_AUTH_GENERIC_OAUTH_AUTH_URL: "https://auth.yourdomain.com/oauth/authorize"
GF_AUTH_GENERIC_OAUTH_TOKEN_URL: "https://auth.yourdomain.com/oauth/token"
GF_AUTH_GENERIC_OAUTH_API_URL: "https://auth.yourdomain.com/oauth/userinfo"
# User mapping
GF_AUTH_GENERIC_OAUTH_LOGIN_ATTRIBUTE_PATH: "preferred_username"
GF_AUTH_GENERIC_OAUTH_NAME_ATTRIBUTE_PATH: "name"
GF_AUTH_GENERIC_OAUTH_EMAIL_ATTRIBUTE_PATH: "email"
# Auto-login
GF_AUTH_OAUTH_AUTO_LOGIN: "true"
GF_AUTH_DISABLE_LOGIN_FORM: "false" # Keep false for admin access
volumes:
- grafana_data:/var/lib/grafana
labels:
# Traefik labels (if using Traefik)
- "traefik.enable=true"
- "traefik.http.routers.grafana.rule=Host(`grafana.yourdomain.com`)"
- "traefik.http.routers.grafana.entrypoints=websecure"
- "traefik.http.routers.grafana.tls.certresolver=letsencrypt"
volumes:
grafana_data:
```
## Step 4: Advanced Configuration
### Role Mapping
Map AuthentiKate users to Grafana roles based on user attributes:
```ini
# Basic role mapping
role_attribute_path = preferred_username == 'admin' && 'Admin' || 'Viewer'
# Multiple admin users
role_attribute_path = contains(['admin', 'grafana-admin'], preferred_username) && 'Admin' || 'Editor'
# Default to Editor for all users
role_attribute_path = 'Editor'
```
### Team Mapping
Automatically assign users to Grafana teams:
```ini
# Team mapping (if you add groups to AuthentiKate in the future)
team_ids_attribute_path = groups
team_ids = 1,2,3
```
### Allow Sign-Up
Control whether new users can sign up automatically:
```ini
[users]
# Allow users to sign up
allow_sign_up = true
# Auto-assign organization
auto_assign_org = true
auto_assign_org_id = 1
# Default role for new users
auto_assign_org_role = Viewer
```
## Step 5: Testing
1. **Restart Grafana** after configuration changes
2. **Navigate to Grafana** in your browser
3. **Click "Sign in with AuthentiKate"** (or get redirected automatically)
4. **Authenticate with AuthentiKate** using your credentials
5. **Verify** you're logged into Grafana with the correct user info
## Troubleshooting
### Common Issues
#### "Invalid redirect URI" Error
Ensure the redirect URI in AuthentiKate exactly matches:
```
https://grafana.yourdomain.com/login/generic_oauth
```
#### Users Not Getting Correct Roles
Check the role mapping configuration:
```ini
# Debug role mapping
role_attribute_path = 'Admin' # Give everyone admin temporarily
```
#### OAuth Login Button Not Appearing
Verify these settings:
```ini
[auth.generic_oauth]
enabled = true
name = AuthentiKate # This shows as the button text
```
#### Auto-login Not Working
Check the auto-login settings:
```ini
[auth]
oauth_auto_login = true
disable_login_form = false # Keep false to allow admin login
```
### Debug Mode
Enable debug logging in Grafana:
```ini
[log]
level = debug
[log.console]
level = debug
```
Then check the Grafana logs:
```bash
docker logs grafana
```
### Testing OAuth Flow
Test the OAuth endpoints manually:
```bash
# Test AuthentiKate discovery
curl https://auth.yourdomain.com/.well-known/openid_configuration
# Test with specific parameters
curl "https://auth.yourdomain.com/oauth/authorize?client_id=YOUR_CLIENT_ID&redirect_uri=https://grafana.yourdomain.com/login/generic_oauth&response_type=code&scope=openid+profile+email"
```
## Advanced Features
### Custom Login Page
Create a custom login experience:
```ini
[auth]
disable_login_form = true
oauth_auto_login = true
[server]
# Custom login logo
login_logo = https://yourdomain.com/logo.png
```
### Organization Management
Control organization assignment:
```ini
[users]
# Assign all OAuth users to specific org
auto_assign_org = true
auto_assign_org_id = 1
# Allow org admins to invite users
allow_org_create = false
```
### Session Management
Configure session settings:
```ini
[session]
# Session timeout
session_life_time = 86400 # 24 hours
# Cookie settings
cookie_secure = true
cookie_samesite = strict
```
## Production Considerations
### Security
- Use HTTPS for both AuthentiKate and Grafana
- Store client secrets securely
- Consider using environment files for secrets
- Set up proper SSL certificates
### Performance
- Enable caching in Grafana
- Use external databases for larger installations
- Monitor authentication latency
### Backup
- Backup Grafana configuration
- Include OAuth settings in your backup strategy
- Test authentication after restores
Your Grafana instance is now integrated with AuthentiKate! Users can sign in with their AuthentiKate credentials and access Grafana with appropriate roles and permissions.

370
docs/integrations/nextcloud.md
View File

@ -1,370 +0,0 @@
# Nextcloud Integration
This guide shows how to integrate Nextcloud with AuthentiKate using the OpenID Connect app for seamless single sign-on.
## Prerequisites
- AuthentiKate running and accessible
- Nextcloud instance with admin access
- Nextcloud OpenID Connect app installed
## Step 1: Install OpenID Connect App
### Via Nextcloud App Store
1. Log into Nextcloud as an administrator
2. Go to **Apps** → **Authentication**
3. Find and install **"OpenID Connect user backend"**
4. Enable the app
### Via Command Line
```bash
# Install via occ command
sudo -u www-data php occ app:install user_oidc
sudo -u www-data php occ app:enable user_oidc
```
## Step 2: Create Application in AuthentiKate
1. Log into your AuthentiKate admin panel
2. Navigate to **Applications** → **Create Application**
3. Fill in the application details:
```
Name: Nextcloud
Redirect URI: https://cloud.yourdomain.com/apps/user_oidc/code
Icon: https://cdn.jsdelivr.net/gh/selfhst/icons/webp/nextcloud.webp
```
4. Click **Save** and note the generated:
- **Client ID**
- **Client Secret**
## Step 3: Configure Nextcloud OIDC
### Via Web Interface
1. Go to **Settings** → **Administration** → **OpenID Connect**
2. Configure the OIDC provider:
```
Provider Name: AuthentiKate
Identifier: authentikate
Client ID: your-client-id
Client Secret: your-client-secret
Discovery endpoint: https://auth.yourdomain.com/.well-known/openid_configuration
```
3. **Advanced Settings** (click to expand):
```
Scope: openid profile email
Unique user identifier: preferred_username
```
4. Click **Save**
### Via Command Line
```bash
# Set OIDC configuration
sudo -u www-data php occ config:app:set user_oidc provider-authentikate-clientId --value="your-client-id"
sudo -u www-data php occ config:app:set user_oidc provider-authentikate-clientSecret --value="your-client-secret"
sudo -u www-data php occ config:app:set user_oidc provider-authentikate-discoveryUrl --value="https://auth.yourdomain.com/.well-known/openid_configuration"
sudo -u www-data php occ config:app:set user_oidc provider-authentikate-scope --value="openid profile email"
# Set unique identifier
sudo -u www-data php occ config:app:set user_oidc provider-authentikate-uniqueUid --value="1"
sudo -u www-data php occ config:app:set user_oidc provider-authentikate-uniqueUidMapping --value="preferred_username"
```
## Step 4: User Attribute Mapping
Configure how AuthentiKate user attributes map to Nextcloud:
### Via Web Interface
In **Settings** → **Administration** → **OpenID Connect** → **Advanced**:
```
Display name mapping: name
Email mapping: email
Unique user identifier: preferred_username
```
### Via Command Line
```bash
# User attribute mapping
sudo -u www-data php occ config:app:set user_oidc provider-authentikate-displayNameMapping --value="name"
sudo -u www-data php occ config:app:set user_oidc provider-authentikate-emailMapping --value="email"
sudo -u www-data php occ config:app:set user_oidc provider-authentikate-quotaMapping --value=""
```
## Step 5: Auto-Provisioning (Optional)
Enable automatic user creation on first login:
### Via Web Interface
In the OIDC settings, enable:
- **Auto provision users**
- **Respect email verified claim**
### Via Command Line
```bash
# Enable auto-provisioning
sudo -u www-data php occ config:app:set user_oidc auto-provision --value="1"
sudo -u www-data php occ config:app:set user_oidc provider-authentikate-provisioningEnabled --value="1"
# Respect email verification
sudo -u www-data php occ config:app:set user_oidc provider-authentikate-checkEmailVerification --value="1"
```
## Step 6: Group Mapping (Optional)
If you plan to add groups to AuthentiKate in the future:
```bash
# Enable group provisioning
sudo -u www-data php occ config:app:set user_oidc provider-authentikate-groupProvisioning --value="1"
sudo -u www-data php occ config:app:set user_oidc provider-authentikate-groupMapping --value="groups"
```
## Step 7: Login Button Customization
Customize the OAuth login button:
### Via Config
```bash
# Set custom button text
sudo -u www-data php occ config:app:set user_oidc provider-authentikate-buttonText --value="Login with AuthentiKate"
# Hide default login form (optional)
sudo -u www-data php occ config:system:set hide_login_form --value=true
```
### Custom CSS (Optional)
Add custom styling in **Settings** → **Administration** → **Theming**:
```css
/* Style the OIDC login button */
.oidc-login-button {
background-color: #3b82f6 !important;
border-color: #3b82f6 !important;
}
.oidc-login-button:hover {
background-color: #2563eb !important;
border-color: #2563eb !important;
}
```
## Complete Configuration Example
Here's a complete command-line setup:
```bash
#!/bin/bash
# Install and enable OIDC app
sudo -u www-data php occ app:install user_oidc
sudo -u www-data php occ app:enable user_oidc
# Configure OIDC provider
sudo -u www-data php occ config:app:set user_oidc provider-authentikate-clientId --value="your-client-id"
sudo -u www-data php occ config:app:set user_oidc provider-authentikate-clientSecret --value="your-client-secret"
sudo -u www-data php occ config:app:set user_oidc provider-authentikate-discoveryUrl --value="https://auth.yourdomain.com/.well-known/openid_configuration"
sudo -u www-data php occ config:app:set user_oidc provider-authentikate-scope --value="openid profile email"
# User mapping
sudo -u www-data php occ config:app:set user_oidc provider-authentikate-uniqueUid --value="1"
sudo -u www-data php occ config:app:set user_oidc provider-authentikate-uniqueUidMapping --value="preferred_username"
sudo -u www-data php occ config:app:set user_oidc provider-authentikate-displayNameMapping --value="name"
sudo -u www-data php occ config:app:set user_oidc provider-authentikate-emailMapping --value="email"
# Auto-provisioning
sudo -u www-data php occ config:app:set user_oidc auto-provision --value="1"
sudo -u www-data php occ config:app:set user_oidc provider-authentikate-provisioningEnabled --value="1"
sudo -u www-data php occ config:app:set user_oidc provider-authentikate-checkEmailVerification --value="1"
# Button customization
sudo -u www-data php occ config:app:set user_oidc provider-authentikate-buttonText --value="Login with AuthentiKate"
echo "Nextcloud OIDC integration configured successfully!"
```
## Docker Compose Example
Complete Docker setup with Nextcloud and AuthentiKate:
```yaml
version: '3.8'
services:
nextcloud:
image: nextcloud:latest
container_name: nextcloud
restart: unless-stopped
ports:
- "80:80"
environment:
- NEXTCLOUD_ADMIN_USER=admin
- NEXTCLOUD_ADMIN_PASSWORD=secure_password
- NEXTCLOUD_TRUSTED_DOMAINS=cloud.yourdomain.com
- OVERWRITEPROTOCOL=https
- OVERWRITEHOST=cloud.yourdomain.com
volumes:
- nextcloud_data:/var/www/html
- ./setup-oidc.sh:/docker-entrypoint-hooks.d/pre-installation/setup-oidc.sh:ro
labels:
# Traefik labels
- "traefik.enable=true"
- "traefik.http.routers.nextcloud.rule=Host(`cloud.yourdomain.com`)"
- "traefik.http.routers.nextcloud.entrypoints=websecure"
- "traefik.http.routers.nextcloud.tls.certresolver=letsencrypt"
volumes:
nextcloud_data:
```
## Testing the Integration
1. **Log out** of Nextcloud (if currently logged in)
2. **Navigate to** your Nextcloud login page
3. **Click "Login with AuthentiKate"** button
4. **Authenticate** with your AuthentiKate credentials
5. **Verify** you're logged into Nextcloud with correct user information
## Advanced Configuration
### Custom User Provisioning
Control how users are created:
```bash
# Set default quota for new users
sudo -u www-data php occ config:app:set user_oidc provider-authentikate-defaultQuota --value="5GB"
# Set default group for new users
sudo -u www-data php occ config:app:set user_oidc provider-authentikate-defaultGroup --value="users"
```
### Backup Users
Prevent deletion of users not found in OIDC:
```bash
# Enable soft delete (backup users)
sudo -u www-data php occ config:app:set user_oidc provider-authentikate-softAutoUpdate --value="1"
```
### Admin Users
Make specific users administrators:
```bash
# Add users to admin group (run after first login)
sudo -u www-data php occ group:adduser admin "admin_username"
```
## Troubleshooting
### Common Issues
#### "Invalid redirect URI" Error
Ensure the redirect URI in AuthentiKate exactly matches:
```
https://cloud.yourdomain.com/apps/user_oidc/code
```
#### OIDC Login Button Missing
Check that the app is enabled:
```bash
sudo -u www-data php occ app:list | grep user_oidc
```
#### Users Not Auto-Created
Verify auto-provisioning is enabled:
```bash
sudo -u www-data php occ config:app:get user_oidc auto-provision
sudo -u www-data php occ config:app:get user_oidc provider-authentikate-provisioningEnabled
```
#### Wrong User Information
Check the attribute mapping:
```bash
sudo -u www-data php occ config:app:get user_oidc provider-authentikate-displayNameMapping
sudo -u www-data php occ config:app:get user_oidc provider-authentikate-emailMapping
```
### Debug Mode
Enable debugging in Nextcloud:
```bash
# Enable debug mode
sudo -u www-data php occ config:system:set debug --value=true
# Check logs
sudo -u www-data php occ log:tail
```
### Configuration Check
Verify your OIDC configuration:
```bash
# List all OIDC settings
sudo -u www-data php occ config:list user_oidc
# Test OIDC discovery endpoint
curl https://auth.yourdomain.com/.well-known/openid_configuration
```
### Reset Configuration
If you need to start over:
```bash
# Remove OIDC configuration
sudo -u www-data php occ config:app:delete user_oidc provider-authentikate-clientId
sudo -u www-data php occ config:app:delete user_oidc provider-authentikate-clientSecret
sudo -u www-data php occ config:app:delete user_oidc provider-authentikate-discoveryUrl
# Disable auto-provisioning
sudo -u www-data php occ config:app:set user_oidc auto-provision --value="0"
```
## Security Considerations
### Trusted Domains
Ensure your domain is in Nextcloud's trusted domains:
```bash
sudo -u www-data php occ config:system:set trusted_domains 0 --value="cloud.yourdomain.com"
```
### HTTPS Configuration
Force HTTPS in Nextcloud:
```bash
sudo -u www-data php occ config:system:set overwriteprotocol --value="https"
sudo -u www-data php occ config:system:set overwrite.cli.url --value="https://cloud.yourdomain.com"
```
### Session Security
Configure secure sessions:
```bash
sudo -u www-data php occ config:system:set session_lifetime --value=3600
sudo -u www-data php occ config:system:set session_keepalive --value=false
```
Your Nextcloud instance is now integrated with AuthentiKate! Users can sign in with their AuthentiKate credentials and access their Nextcloud files and applications.

324
docs/integrations/overview.md
View File

@ -1,324 +0,0 @@
# Integration Overview
AuthentiKate supports OpenID Connect (OIDC) and OAuth 2.0, making it compatible with hundreds of applications. This section covers how to integrate AuthentiKate with popular homelab applications.
## OIDC Endpoints
All applications will need these AuthentiKate endpoints:
| Endpoint | URL | Description |
|----------|-----|-------------|
| **Discovery** | `/.well-known/openid_configuration` | Auto-configuration endpoint |
| **Authorization** | `/oauth/authorize` | User authorization endpoint |
| **Token** | `/oauth/token` | Token exchange endpoint |
| **User Info** | `/oauth/userinfo` | User profile endpoint |
| **JWKS** | `/.well-known/jwks.json` | JSON Web Key Set |
::: tip
Most modern applications can auto-configure using just the discovery endpoint. Use `https://auth.yourdomain.com/.well-known/openid_configuration` when possible.
:::
## Quick Integration Steps
### 1. Create Application in AuthentiKate
1. Log into AuthentiKate admin panel
2. Go to **Applications** → **Create Application**
3. Fill in the details:
- **Name**: Your application name
- **Redirect URI**: Your app's OAuth callback URL
- **Icon**: Optional icon URL
4. Save and note the **Client ID** and **Client Secret**
### 2. Configure Your Application
Use the generated credentials in your application's OAuth/OIDC settings:
- **Provider URL**: `https://auth.yourdomain.com`
- **Client ID**: (from step 1)
- **Client Secret**: (from step 1)
- **Scopes**: `openid profile email`
### 3. Test the Integration
1. Try logging into your application
2. You should be redirected to AuthentiKate
3. After authentication, you'll be returned to your app
## Supported Applications
### Ready-to-Use Guides
- [**Grafana**](/integrations/grafana) - Analytics and monitoring
- [**Nextcloud**](/integrations/nextcloud) - File sharing and collaboration
- [**Traefik Forward Auth**](/integrations/traefik) - Reverse proxy authentication
### Compatible Applications
AuthentiKate works with any application that supports OIDC/OAuth2:
#### **Monitoring & Analytics**
- Grafana ✅
- Prometheus
- Uptime Kuma
- Tautulli
- Zabbix
- LibreNMS
#### **Media & Entertainment**
- Jellyfin
- Plex (via Tautulli)
- Overseerr
- Sonarr/Radarr/Lidarr
- Ombi
#### **Productivity & Files**
- Nextcloud ✅
- BookStack
- Paperless-ngx
- Standard Notes
- Joplin Server
- PhotoPrism
- Immich
#### **Development & Git**
- Gitea
- GitLab
- Forgejo
- Drone CI
- Jenkins
#### **Communication**
- Mattermost
- Rocket.Chat
- Element (Matrix)
#### **Infrastructure & Networking**
- Portainer
- Proxmox
- pfSense
- OPNsense
- Traefik ✅
#### **Finance & Business**
- Firefly III
- Invoice Ninja
- Crater
- Akaunting
## Application Templates
AuthentiKate includes templates for popular applications:
```javascript
// Example: Grafana template
{
name: "Grafana",
redirectUri: "https://grafana.yourdomain.com/login/generic_oauth",
icon: "https://cdn.jsdelivr.net/gh/selfhst/icons/webp/grafana.webp"
}
```
Available templates:
- Grafana
- Nextcloud
- Proxmox
- Portainer
- GitLab
- And many more...
## Integration Patterns
### Pattern 1: Direct OIDC Integration
Best for applications with built-in OIDC support:
```mermaid
graph LR
A[User] --> B[Application]
B --> C[AuthentiKate]
C --> B
B --> A
```
**Examples**: Grafana, Nextcloud, GitLab
### Pattern 2: Reverse Proxy Authentication
For applications without OIDC support:
```mermaid
graph LR
A[User] --> B[Reverse Proxy]
B --> C[AuthentiKate]
C --> B
B --> D[Application]
D --> B
B --> A
```
**Examples**: Traefik Forward Auth, nginx auth_request
### Pattern 3: Header-Based Authentication
Applications that accept authentication headers:
```mermaid
graph LR
A[User] --> B[Proxy + Headers]
B --> C[AuthentiKate]
C --> B
B --> D[Application]
```
**Examples**: Proxmox, Portainer (with middleware)
## Common Configuration Values
Most applications need these standard values:
### Basic OIDC Settings
```yaml
provider_url: https://auth.yourdomain.com
client_id: your-client-id
client_secret: your-client-secret
scopes: openid profile email
```
### Advanced Settings
```yaml
# Token validation
jwks_uri: https://auth.yourdomain.com/.well-known/jwks.json
issuer: https://auth.yourdomain.com
# User mapping
username_claim: preferred_username
email_claim: email
name_claim: name
# Security
require_https: true
verify_ssl: true
```
## User Attribute Mapping
AuthentiKate provides these user claims:
| Claim | Description | Example |
|-------|-------------|---------|
| `sub` | Unique user ID (UUID) | `f47ac10b-58cc-4372-a567-0e02b2c3d479` |
| `email` | User email address | `user@example.com` |
| `name` | Full display name | `John Doe` |
| `preferred_username` | Username | `john.doe` |
| `email_verified` | Email verification status | `true` |
| `picture` | Avatar URL | `https://auth.yourdomain.com/storage/avatars/...` |
### Custom User Mapping
Some applications need custom field mapping:
```yaml
# Grafana example
field_mapping:
login: preferred_username
email: email
name: name
# GitLab example
user_info_mapping:
username: preferred_username
email: email
name: name
```
## Troubleshooting Common Issues
### Invalid Redirect URI
```
Error: Invalid redirect URI
```
**Solution**: Ensure the redirect URI in AuthentiKate exactly matches your application's callback URL.
### Invalid Client
```
Error: Invalid client credentials
```
**Solution**: Double-check the Client ID and Client Secret in your application settings.
### SSL/HTTPS Issues
```
Error: SSL verification failed
```
**Solutions**:
- Ensure AuthentiKate is accessible via HTTPS
- Use valid SSL certificates
- Set `verify_ssl: false` only for testing
### Token Validation Errors
```
Error: Invalid token signature
```
**Solution**: Verify the JWKS endpoint is accessible and your application is using the correct validation method.
## Testing Your Integration
### 1. Manual Testing
1. Try logging into your application
2. Check that you're redirected to AuthentiKate
3. Verify successful authentication returns you to the app
4. Confirm user details are populated correctly
### 2. Token Validation
```bash
# Test the discovery endpoint
curl https://auth.yourdomain.com/.well-known/openid_configuration
# Test JWKS endpoint
curl https://auth.yourdomain.com/.well-known/jwks.json
# Test user info (requires valid token)
curl -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
https://auth.yourdomain.com/oauth/userinfo
```
### 3. Debug Mode
Enable debug logging in your application to see:
- OAuth request/response details
- Token validation steps
- User claim mapping
## Security Best Practices
### Client Configuration
- Use strong, unique Client Secrets
- Implement proper redirect URI validation
- Use HTTPS for all communication
- Validate SSL certificates
### Scope Management
- Request minimal necessary scopes
- Use `openid` scope for OIDC compliance
- Add `profile` and `email` as needed
### Token Handling
- Store tokens securely
- Implement proper token refresh
- Validate token signatures
- Respect token expiration
## Getting Help
If you're having trouble integrating an application:
1. **Check the logs**: Both AuthentiKate and your application logs
2. **Verify endpoints**: Test OIDC endpoints with curl
3. **Compare settings**: Use working examples as reference
4. **Community help**: Check GitHub discussions for similar integrations
Ready to integrate your first application? Start with our [Grafana guide](/integrations/grafana) for a step-by-step walkthrough.

10
docs/package.json
View File

@ -1,10 +0,0 @@
{
"scripts": {
"docs:dev": "vitepress dev",
"docs:build": "vitepress build",
"docs:preview": "vitepress preview"
},
"devDependencies": {
"vitepress": "^1.6.3"
}
}