prole/docs/grafana-sso.md

Grafana SSO (Kerberos via Knoe auth)

This repo’s first-pass Grafana SSO is implemented as:

1. Users authenticate at https://api.knoe.org/auth/login.
   • Primary: Kerberos/SPNEGO (/auth/spnego)
   • Fallback: form login (/auth/form) only when explicitly enabled
2. On success, knoe-auth issues a signed session cookie scoped to Domain=.knoe.org.
3. Users access Grafana at https://svc.knoe.org/ as usual.
4. svc.knoe.org is routed to an internal Nginx knoe-grafana-proxy service.
   • The proxy calls knoe-auth (/auth/verify) via auth_request on every request.
   • On success it injects X-WEBAUTH-USER and forwards to Grafana.
   • On failure it redirects to https://api.knoe.org/auth/login?next=... (fail-closed).
5. Grafana is configured with auth.proxy to trust X-WEBAUTH-USER.

Key configuration knobs

• Kong routing + TLS:

  • SERVICE_HOSTNAME (default svc.knoe.org)
  • AUTH_HOSTNAME (default api.knoe.org)
  • PROLE_GRAFANA_SSO_ENABLED=1 to route svc.knoe.org → knoe-grafana-proxy instead of directly to Grafana

• Grafana chart values:

  • PROLE_GRAFANA_SSO_ENABLED=1 enables grafana.ini.auth.proxy and disables the Grafana login form / anonymous access

• knoe-auth service (environment variables):

  • PROLE_AUTH_ENABLED=true
  • PROLE_AUTH_SESSION_SECRET (required; strong random)
  • PROLE_AUTH_COOKIE_DOMAIN=.knoe.org
  • PROLE_KERBEROS_SERVICE_PRINCIPAL (required for SPNEGO)
  • PROLE_KERBEROS_KEYTAB_PATH (required for SPNEGO)
  • PROLE_AUTH_FORM_ENABLED=true (optional; enables password fallback)

Kubernetes resources

Manifests are under deploy/opentofu/k3s/manifests/knoe/:

• knoe-auth-deployment.yaml / knoe-auth-service.yaml
• knoe-kdc-configmap.yaml (embedded KDC sidecar configuration)
• grafana-proxy-configmap.yaml / grafana-proxy-deployment.yaml / grafana-proxy-service.yaml

Required (provided externally):

• Secret knoe-auth-secrets with key sessionSecret
• Secret knoe-auth-keytab containing the HTTP service keytab at http.keytab
• Secret knoe-kdc-secrets with keys master_password and admin_password (for the embedded KDC)

Logout / session invalidation

• GET /auth/logout clears the Knoe session cookie (Max-Age=0).
• Grafana access is effectively revoked on the next request because the proxy calls /auth/verify for every request.