authentikate/docs/integrations/grafana.md

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