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:

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:

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

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:

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

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

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

# Debug role mapping
role_attribute_path = 'Admin'  # Give everyone admin temporarily

OAuth Login Button Not Appearing

Verify these settings:

[auth.generic_oauth]
enabled = true
name = AuthentiKate  # This shows as the button text

Auto-login Not Working

Check the auto-login settings:

[auth]
oauth_auto_login = true
disable_login_form = false  # Keep false to allow admin login

Debug Mode

Enable debug logging in Grafana:

[log]
level = debug

[log.console]
level = debug

Then check the Grafana logs:

docker logs grafana

Testing OAuth Flow

Test the OAuth endpoints manually:

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

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

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

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