Grafana suele ser de las primeras herramientas que se montan en cualquier plataforma, y también de las primeras en llenarse de usuarios locales: el de cada persona del equipo, el de quien ya se fue y nadie dio de baja, el admin compartido… Si ya tienes Keycloak como proveedor de identidad, conectarlos te quita todo eso de encima: inicio de sesión único, altas y bajas en un solo sitio y los permisos de Grafana decididos con roles de Keycloak.
En este artículo te cuento cómo lo configuro, probado con Keycloak 26.5 y Grafana 12.3. Usaré estos nombres de ejemplo; cámbialos por los tuyos:
- Keycloak:
https://sso.example.com, con un realm llamadoejemplo. - Grafana:
https://grafana.example.com.
Cómo funciona
Grafana actúa como cliente de OpenID Connect (OIDC) con el flujo de authorization code, reforzado con PKCE:
Grafana nunca ve la contraseña del usuario: solo recibe unos tokens firmados por Keycloak en los que van, entre otras cosas, los roles que le has asignado.
1. El cliente en Keycloak
En la consola de administración, dentro del realm, ve a Clients → Create client y recorre los tres pasos del asistente:
- General settings
- Client type:
OpenID Connect - Client ID:
grafana
- Client type:
- Capability config
- Client authentication: On. Grafana es una aplicación de servidor y puede guardar un secreto, así que el cliente es confidencial.
- Authentication flow: solo Standard flow. Deja desmarcado Direct access grants: permite pedir tokens enviando la contraseña del usuario directamente, y no lo necesitas (luego lo activaremos un momento para una prueba).
- PKCE Method: S256. Así Keycloak exige PKCE y rechaza a cualquiera que no lo use.
- Login settings
- Root URL:
https://grafana.example.com - Valid redirect URIs:
https://grafana.example.com/login/generic_oauth - Valid post logout redirect URIs:
https://grafana.example.com/login - Web origins:
https://grafana.example.com
- Root URL:
Guarda y, en la pestaña Credentials del cliente, copia el Client secret. Lo necesitarás en Grafana.
2. Los roles
Grafana tiene tres roles básicos por organización: Viewer, Editor y Admin. Vamos a crear su equivalente en Keycloak como roles del cliente grafana (no del realm: así quedan agrupados con la aplicación a la que pertenecen).
En el cliente, pestaña Roles → Create role, crea tres: admin, editor y viewer.
Para asignarlos a una persona: Users → el usuario → Role mapping → Assign role, filtra por roles de cliente y elige el que toque. Mejor todavía, asígnalos a grupos (por ejemplo, grafana-admins, grafana-editores y grafana-lectores) y luego mete a las personas en el grupo: es mucho más fácil de mantener cuando el equipo crece.
Crear también el rol viewer, en lugar de dar acceso de lectura a todo el realm, es una decisión deliberada: solo entra en Grafana quien tenga algún rol de Grafana. En una organización con muchos usuarios en Keycloak, no todo el mundo tiene por qué ver tus paneles.
No hace falta ningún mapper
En los tutoriales antiguos verás que hay que crear un mapper para que los roles lleguen en el token. Ya no es necesario: Keycloak incluye por defecto los roles de cada cliente en el access token, en resource_access.<cliente>.roles, y Grafana 12 lo lee de ahí.
Ojo con un detalle: esos roles van en el access token, pero no en el ID token ni en la respuesta de userinfo. Si usas una versión antigua de Grafana que no los encuentra, ve a Client scopes → roles → Mappers → client roles y activa Add to ID token.
3. Comprobar el token (opcional)
Antes de tocar Grafana, me gusta ver con mis propios ojos qué lleva el token. Para esta prueba, activa un momento Direct access grants en el cliente y pide un token con un usuario de prueba:
read -s KEYCLOAK_PASSWORD # la contraseña del usuario, sin que quede en el historial
curl -s \
-d client_id=grafana \
-d client_secret="$KEYCLOAK_CLIENT_SECRET" \
-d grant_type=password \
-d username=ana \
-d password="$KEYCLOAK_PASSWORD" \
https://sso.example.com/realms/ejemplo/protocol/openid-connect/token \
| jq -r .access_token \
| jq -R 'split(".")[1] | gsub("-";"+") | gsub("_";"/") | @base64d | fromjson
| {preferred_username, resource_access}'
El último jq descodifica la parte central del token (un JWT) en tu propia máquina. Deberías ver algo así:
{
"preferred_username": "ana",
"resource_access": {
"grafana": {
"roles": ["admin"]
}
}
}
Hay webs muy populares para descodificar tokens, pero un token válido es una credencial: no lo pegues en ninguna web. Y cuando termines, vuelve a desactivar Direct access grants.
4. La configuración de Grafana
Todo va en la sección [auth.generic_oauth] del grafana.ini:
[server]
root_url = https://grafana.example.com
[auth]
oauth_auto_login = true
signout_redirect_url = https://sso.example.com/realms/ejemplo/protocol/openid-connect/logout?client_id=grafana&post_logout_redirect_uri=https%3A%2F%2Fgrafana.example.com%2Flogin
[auth.generic_oauth]
enabled = true
name = Keycloak
allow_sign_up = true
client_id = grafana
client_secret = $__file{/run/secrets/grafana-oauth-secret}
scopes = openid email profile
auth_url = https://sso.example.com/realms/ejemplo/protocol/openid-connect/auth
token_url = https://sso.example.com/realms/ejemplo/protocol/openid-connect/token
api_url = https://sso.example.com/realms/ejemplo/protocol/openid-connect/userinfo
use_pkce = true
login_attribute_path = preferred_username
email_attribute_path = email
name_attribute_path = name
role_attribute_path = contains(resource_access.grafana.roles[*], 'admin') && 'Admin' || contains(resource_access.grafana.roles[*], 'editor') && 'Editor' || contains(resource_access.grafana.roles[*], 'viewer') && 'Viewer'
role_attribute_strict = true
Lo importante, línea a línea:
client_secret = $__file{...}: Grafana lee el secreto de un fichero, así no queda escrito en elgrafana.inini en el repositorio. Si lo despliegas en contenedores, cualquier opción se puede pasar también como variable de entorno:GF_más la sección y la clave en mayúsculas, comoGF_AUTH_GENERIC_OAUTH_CLIENT_ID.use_pkce = true: obligatorio, porque en Keycloak hemos exigido PKCE. Sin esto, Keycloak rechaza el inicio de sesión.role_attribute_path: una expresión JMESPath que se evalúa sobre los datos del usuario y devuelve el rol de Grafana. Se lee de izquierda a derecha: si tieneadmin,Admin; si no, si tieneeditor,Editor; si no, si tieneviewer,Viewer.role_attribute_strict = true: si la expresión no devuelve un rol válido, no se entra. Junto con la expresión anterior, es lo que hace que solo accedan quienes tengan algún rol de Grafana. Quien no lo tenga verá el mensaje «IdP did not return a role attribute, please contact your administrator».oauth_auto_login = true: quien entra en Grafana va directo a Keycloak, sin pasar por la pantalla de inicio de sesión de Grafana.signout_redirect_url: al salir de Grafana también se cierra la sesión en Keycloak. Si no, al volver a entrar Keycloak te dejaría pasar sin pedir nada.
Los roles se sincronizan en cada inicio de sesión: si cambias el rol de alguien en Keycloak, Grafana lo aplica la próxima vez que esa persona entre. Y no hace falta crear a nadie en Grafana: el usuario se da de alta solo la primera vez (allow_sign_up).
La puerta de emergencia
Con oauth_auto_login, la pantalla de inicio de sesión de Grafana desaparece. Pero si un día Keycloak se cae, necesitas poder entrar con el administrador local. Para eso está:
https://grafana.example.com/login?disableAutoLogin=true
Esa dirección muestra el formulario de usuario y contraseña de siempre. Guarda la contraseña del admin local en tu gestor de secretos y no la uses para nada más.
5. Probarlo
Con tres usuarios de prueba, cada uno con un rol distinto, el resultado es este:
| Usuario | Rol del cliente grafana en Keycloak | Rol en Grafana |
|---|---|---|
| ana | admin | Admin |
| eva | editor | Editor |
| luis | viewer | Viewer |
luis, antes de asignarle viewer | ninguno | No puede entrar |
Si algo no cuadra, el registro de Grafana es bastante claro. Busca las líneas de oauth.generic_oauth: ahí verás, por ejemplo, el aviso de que no se pudo extraer el rol.
Conclusión
Con un cliente en Keycloak, tres roles y una docena de líneas en el grafana.ini tienes inicio de sesión único en Grafana, permisos gestionados desde un único sitio y ningún usuario local que mantener (salvo el de emergencia). Y lo mismo vale para el resto de herramientas que hablen OpenID Connect: una vez tienes Keycloak, cada aplicación nueva es un cliente más.




