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**](/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.