authentikate/docs/integrations/overview.md

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 - Analytics and monitoring
• Nextcloud - File sharing and collaboration
• Traefik Forward Auth - 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:

// 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:

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:

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:

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

provider_url: https://auth.yourdomain.com
client_id: your-client-id
client_secret: your-client-secret
scopes: openid profile email

Advanced Settings

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

# 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

# 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 for a step-by-step walkthrough.