homelab/project-usage/authentik-oidc.md

Authentik Federated OIDC & SSO

Provider: https://authentik.riotpiao.homelab.com
OIDC Issuer: https://authentik.riotpiao.homelab.com/application/o/talos-federation/
Namespace: iam

When to Use

• Federated login — Single sign-on for Grafana, MinIO, Forgejo, Argo CD
• User groups — RBAC via group membership (admins, devops, read-only)
• JWT tokens — Authenticate CLI tools, API clients
• SSO for custom apps — OAuth2/OIDC redirect flow

Quick Start

1. Login to Authentik console:

# Browser: https://authentik.riotpiao.homelab.com
# Default user: akadmin
# Password: AUTHENTIK_BOOTSTRAP_PASSWORD (from .env)

# Or via OIDC (after initial setup)
# Click "Sign in with talos-federation"

2. Create user:

Authentik console → Users → Create
- Username: alice
- Email: [email protected]
- Group: homelab-devs (or homelab-admins)

3. User logs into Grafana:

https://grafana.riotpiao.homelab.com
→ Sign in with Authentik (auto-redirects to OIDC provider)
→ Approve access
→ Logged in as alice (group determines role: Admin or Viewer)

Configuration

Key	Value
OIDC provider	talos-federation (federated)
OIDC issuer	https://authentik.riotpiao.homelab.com/application/o/talos-federation/
JWKS endpoint	https://authentik.riotpiao.homelab.com/application/o/talos-federation/.well-known/openid-configuration
Database	PostgreSQL (ddb namespace, authentik user)
Backups	WAL archived to MinIO

Common Patterns

Grafana OIDC login:

# k8s/logging/grafana-values.yaml
grafana:
  auth.generic_oauth:
    enabled: true
    name: Authentik
    client_id: grafana
    client_secret: $GRAFANA_OIDC_CLIENT_SECRET  # from Vault
    auth_url: https://authentik.riotpiao.homelab.com/application/o/authorize/
    token_url: https://authentik.riotpiao.homelab.com/application/o/token/
    api_url: https://authentik.riotpiao.homelab.com/application/o/userinfo/
    scopes: openid profile email groups
    use_pkce: true

MinIO OIDC login:

# k8s/storage/minio-values.yaml
minio:
  identity_oauth:
    provider: authentik
    client_id: minio
    client_secret: $MINIO_OIDC_CLIENT_SECRET
    redirect_uri: https://minio.riotpiao.homelab.com/oauth_callback
    config_url: https://authentik.riotpiao.homelab.com/application/o/talos-federation/.well-known/openid-configuration
    policy_mappings:
      - group: homelab-admins → consoleAdmin
      - group: homelab-devops → readwrite

CLI device code flow (talos-cli):

# Get JWT token (no kubeconfig needed)
talos secrets login
# → Opens browser, approve device code
# → Token cached in ~/.talos/token

# Use token to access Vault
talos get cluster/ANTHROPIC_API_KEY --key ANTHROPIC_API_KEY
# → Vault validates JWT from Authentik
# → Returns secret

Custom app OIDC redirect:

import "github.com/coreos/go-oidc/v3/oidc"

provider, _ := oidc.NewProvider(ctx, "https://authentik.riotpiao.homelab.com/application/o/talos-federation/")

verifier := provider.Verifier(&oidc.Config{ClientID: "my-app"})

// After OAuth2 redirect & token exchange:
idToken, _ := verifier.Verify(ctx, rawIDToken)

// Extract claims
var claims struct {
  Email string `json:"email"`
  Groups []string `json:"groups"`
}
idToken.Claims(&claims)

Group-Based RBAC

Default groups:

• homelab-admins — Full cluster access (Grafana Admin, MinIO admin, Argo CD admin, Vault admin)
• homelab-devops — Deploy & monitor (Grafana Editor, MinIO readwrite, Argo CD user)
• homelab-viewers — Read-only (Grafana Viewer, MinIO readonly)

Assign user to group:

Authentik console → Users → alice → Edit
→ Groups → Add "homelab-devops"
→ Save

Custom group-to-role mapping:

# Per-service (see cicd-workflow.md, monitoring-metrics.md for examples)
# Grafana: auth.generic_oauth.role_attribute_path = contains(groups[*], 'homelab-admins') && 'Admin' || 'Viewer'
# MinIO: policy_mappings (see above)

Monitoring

Authentik dashboard: https://authentik.riotpiao.homelab.com/api/v3/admin/dashboards

Key metrics:

• Login attempts (success/failure)
• Active sessions
• Token issuance rate
• Provider sync status

Troubleshooting

Users can't login (redirect loop):

# Check redirect URI matches
# Authentik console → Applications → grafana → Edit
# Verify Redirect URI = https://grafana.riotpiao.homelab.com/login/generic_oauth

# Check OIDC provider is running
k get pods -n iam -l app=authentik

JWT token expired:

# CLI tokens have 24h expiry
# Re-authenticate
talos secrets login

Groups not syncing:

# Check group attribute in OIDC config
# Authentik console → Applications → <app> → OIDC Configuration
# groups_attribute = "groups" (or custom claim name)

Vault can't validate JWT:

# Verify JWKS endpoint is accessible
curl https://authentik.riotpiao.homelab.com/application/o/talos-federation/.well-known/openid-configuration

# Restart Vault to refresh JWKS cache
k rollout restart -n iam deployment/vault

See /TROUBLESHOOTING.md for full incident guide.