Grafana Single Sign-On

Grafana authenticates against the Keycloak FAS realm via OpenID Connect. One identity across every Federal Frontier UI, with access level driven by realm roles.

Grafana single sign-on

Grafana signs users in through the same Keycloak FAS realm used by every other Federal Frontier UI — Compass, OutpostAI, the VDI portal, and the OpenStack consoles. A user authenticates once against Keycloak and lands in Grafana with an access level that follows automatically from the realm roles they already hold. There is no separate Grafana account to provision and no second password to manage.

This is the same federated-identity pattern described in VDI Authentication and the platform authorization architecture (ADR-001): Keycloak is the single identity provider, and each application maps the user’s realm roles onto its own permission model.

Why SSO for Grafana

  • One identity — the same credentials and IdP across the whole platform. Nothing Grafana-specific to remember.
  • Centralized lifecycle — disabling a user in Keycloak revokes Grafana access immediately. There is no parallel Grafana user store to keep in sync.
  • Role-driven access — a user’s Grafana role is derived from their FAS realm roles, so granting or revoking dashboard access is done in Keycloak, not in Grafana.

Architecture

Grafana uses the OpenID Connect authorization-code flow against the FAS realm. Keycloak runs with a fixed external hostname, so every token it issues carries the same issuer regardless of the network path used to reach it — which lets the browser redirect, the backend token exchange, and the userinfo lookup all use the one public Keycloak URL without an issuer mismatch.

Browser ──(1) click "Sign in with Keycloak"──▶ Grafana
Grafana ──(2) 302 redirect────────────────────▶ Keycloak (FAS realm) authorize endpoint
Browser ──(3) user authenticates──────────────▶ Keycloak
Keycloak ─(4) 302 with authorization code─────▶ Grafana  /login/generic_oauth
Grafana ──(5) exchange code for token─────────▶ Keycloak token endpoint  (backend)
Grafana ──(6) read realm roles from token─────▶ map to a Grafana role

Roles

Grafana has four access levels. Under SSO these are not assigned in Grafana’s own user interface — they are derived from the FAS realm roles on the authenticated user. The first matching rule wins, and a user who authenticates but matches no rule defaults to Viewer rather than being denied.

Grafana role Scope Granted to FAS realm role(s) Capability
Grafana Server Admin Global superadmin Manage all organizations, users, and server settings
Admin Per-org platformadmin, ffp-admin, frontieradmin Full control of dashboards, data sources, users, and alerts
Editor Per-org ffp-operator, operator, sre-agent Create and edit dashboards and alerts
Viewer Per-org everyone else (ffp-viewer, viewer, user) Read-only

To give someone Grafana admin, assign them the platformadmin / ffp-admin realm role (organization Admin) or superadmin (global server admin) in Keycloak. No change inside Grafana is required.

Identity provider configuration

A confidential OpenID Connect client named grafana is registered in the FAS realm. Its redirect URI points at Grafana’s OAuth callback, and its default scopes include the realm roles scope so that the user’s realm roles are present in the issued token for role mapping.

Setting Value
Client ID grafana
Client type Confidential (authorization-code flow)
Redirect URI Grafana’s /login/generic_oauth callback
Scopes openid, email, profile, roles

The client secret is held in a Kubernetes secret and injected into Grafana at runtime — it is never stored in source control.

Break-glass access

Grafana’s built-in local administrator login is intentionally left enabled as a break-glass path. If Keycloak is ever unavailable, an operator can still reach Grafana with the local admin credentials kept in the team vault. Day-to-day, all users sign in through Keycloak.

Operational notes

  • The monitoring stack is installed via Helm. The SSO settings live in a committed values override, which is the source of truth — any future Helm upgrade must include it so the configuration is not lost.
  • For LAN-internal traffic to the Keycloak host, Grafana skips certificate verification because the endpoint is signed by the internal certificate authority. To remove this, the internal CA can be mounted into the Grafana pod.