authentikate/docs/guide/first-setup.md

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:

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:

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

3. Set Your Domain

Update the APP_URL to match your actual domain:

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)

# 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

# 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
• Configure Nextcloud authentication
• Integrate with Traefik forward auth

Advanced Configuration

• Environment variables reference
• Database configuration
• Security settings

User Management

• Create user invitations
• Manage user profiles
• Handle user permissions

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! 🎉