Integrations · OIDC

Grafana SSO

Configure Grafana to authenticate users via Clavex using OpenID Connect. Supports automatic Org assignment and role provisioning (Admin, Editor, Viewer) from Clavex group claims. Works with Grafana OSS ≥ 8.3 and Grafana Enterprise.

Prerequisites

Grafana ≥ 8.3 (OSS or Enterprise)
Clavex at https://id.acme.eu, org slug acme
Access to grafana.ini or Grafana environment variables

Step 1 — Register an OIDC Client in Clavex

Admin API (curl)

$ curl -X POST https://id.acme.eu/api/v1/organizations/acme/clients \ -H 'Authorization: Bearer $ADMIN_TOKEN' \ -H 'Content-Type: application/json' \ -d '{ "client_id": "grafana", "client_name": "Grafana", "grant_types": ["authorization_code", "refresh_token"], "redirect_uris": ["https://grafana.acme.eu/login/generic_oauth"], "scopes": ["openid", "profile", "email", "groups"], "token_endpoint_auth_method": "client_secret_basic" }'
# Save the returned client_secret {"client_id":"grafana","client_secret":"cs_xxxxxxxxxxxxxxxx",...}

Clavex OIDC endpoint	URL
Discovery	`https://id.acme.eu/acme/.well-known/openid-configuration`
Authorization	`https://id.acme.eu/acme/authorize`
Token	`https://id.acme.eu/acme/token`
UserInfo	`https://id.acme.eu/acme/userinfo`

Step 2 — Configure Grafana

Edit /etc/grafana/grafana.ini (or set the equivalent env vars):

grafana.ini

[auth.generic_oauth] enabled = true name = Clavex icon = signin allow_sign_up = true auto_login = false
client_id = grafana client_secret = cs_xxxxxxxxxxxxxxxx
auth_url = https://id.acme.eu/acme/authorize token_url = https://id.acme.eu/acme/token api_url = https://id.acme.eu/acme/userinfo scopes = openid profile email groups
# Use sub as the user id (stable, not email) login_attribute_path = preferred_username name_attribute_path = name email_attribute_path = email
# Role mapping from groups claim # groups claim: ["grafana-admins","grafana-editors","grafana-viewers"] role_attribute_path = contains(groups[*], 'grafana-admins') && 'Admin' || contains(groups[*], 'grafana-editors') && 'Editor' || 'Viewer' role_attribute_strict = false
# Org mapping (optional — for multi-org Grafana) # org_attribute_path = org_id # org_mapping = acme:1:Admin
# Use PKCE (recommended) use_pkce = true use_refresh_token = true

Using Environment Variables (Docker / Kubernetes)

env

GF_AUTH_GENERIC_OAUTH_ENABLED=true GF_AUTH_GENERIC_OAUTH_NAME=Clavex GF_AUTH_GENERIC_OAUTH_CLIENT_ID=grafana GF_AUTH_GENERIC_OAUTH_CLIENT_SECRET=cs_xxxxxxxxxxxxxxxx GF_AUTH_GENERIC_OAUTH_AUTH_URL=https://id.acme.eu/acme/authorize GF_AUTH_GENERIC_OAUTH_TOKEN_URL=https://id.acme.eu/acme/token GF_AUTH_GENERIC_OAUTH_API_URL=https://id.acme.eu/acme/userinfo GF_AUTH_GENERIC_OAUTH_SCOPES=openid profile email groups GF_AUTH_GENERIC_OAUTH_USE_PKCE=true GF_AUTH_GENERIC_OAUTH_ROLE_ATTRIBUTE_PATH="contains(groups[*], 'grafana-admins') && 'Admin' || 'Viewer'"

Step 3 — Create Groups in Clavex

In the Clavex Admin Console → your org → Groups, create: grafana-admins, grafana-editors, grafana-viewers. Assign users to the appropriate group. The groups scope must be enabled for the client (it is included in the registration above).

Step 4 — Restart Grafana and Test

bash

$ systemctl restart grafana-server # Or for Docker: $ docker compose restart grafana
# Open https://grafana.acme.eu — you should see a "Sign in with Clavex" button

Troubleshooting

Symptom	Cause	Fix
No "Sign in with Clavex" button	`enabled = false` or config not reloaded	Check `grafana.ini` and restart Grafana
`invalid_client` error	Wrong `client_id` or `client_secret`	Re-check credentials; rotate secret in Clavex if needed
User logs in but gets role `Viewer`	Group claim empty or mapping expression wrong	Check `role_attribute_path` JMESPath syntax; verify groups scope
`lookup failed: user not found`	`login_attribute_path` points to missing claim	Use `sub` or `email` — both always present
Redirect URI mismatch	Grafana URL differs from registered redirect URI	Update `redirect_uris` in Clavex client registration