Grafana with Keycloak integration

A concise guide to configuring Keycloak as your Identity Provider (IdP) for Grafana’s OAuth login, enabling seamless SSO, automatic user provisioning, and role-based access control.

1. Keycloak side

1.1 Create client

Save, then copy the Client Secret.

1.2 Optional ► add role for auto‑admin

1. Realm → Roles → Add role → grafanaadmin.

2. Users →  alice →  Role Mappings →  assign grafanaadmin.

3. Mappers → Built‑In → User Realm Role → add, set Token claim name roles.

1.3 Expose mappers Grafana needs

Verify with Client → Evaluate – token must show email, roles and stable sub.

2. Grafana side

2.1 Container run / docker‑compose

bash
docker run -d --name grafana \ 
-p 3000:3000 \ 
-e GF_SERVER_ROOT_URL=http://<grafana-host>/ \ 
-e GF_AUTH_OAUTH_ALLOW_INSECURE_EMAIL_LOOKUP=true \ 
-v grafana-storage:/var/lib/grafana \ 
grafana/grafana-oss:latest

• GF_SERVER_ROOT_URL avoids the infamous redirect_uri=localhost bug 

• GF_AUTH_OAUTH_ALLOW_INSECURE_EMAIL_LOOKUP=true lets Grafana match by e‑mail if Keycloak user IDs change 

2.2 Configure Generic OAuth provider

Administration → Authentication → Generic OAuth

Click Save & Test – you should see “Login was successful” .

3. Advanced topics

3.1 Role mapping gotchas

• Make sure roles claim appears as a String array; Grafana ignores nested realm_access if you omit roles[*].

• Each Keycloak‑login merges roles only at sign‑in, not continuously; change role → logout → login to refresh.

3.2 Single‑Logout (SLO)

If the logout URL (above) is set, Grafana hits Keycloak’s /logout endpoint. Without it, pressing Sign out only kills Grafana’s session and you’ll log straight back in due to IdP cookies.

3.3 Docker permission error

Error in logs:

ini
GF_PATHS_DATA='/var/lib/grafana' is not writable

Bind‑mounted host folder must be owned by UID 472 or use a named volume which copies correct ownership automatically.

4. Troubleshooting matrix