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:**
```bash
# 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:**
```yaml
# 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:**
```yaml
# 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):**
```bash
# 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:**
```go
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:**
```yaml
# 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):**
```bash
# 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:**
```bash
# CLI tokens have 24h expiry
# Re-authenticate
talos secrets login
```

**Groups not syncing:**
```bash
# Check group attribute in OIDC config
# Authentik console → Applications → <app> → OIDC Configuration
# groups_attribute = "groups" (or custom claim name)
```

**Vault can't validate JWT:**
```bash
# 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.