手把手教你：用Keycloak为Grafana配置单点登录（SSO）
在现代企业IT架构里，统一身份认证（SSO）早已不是“锦上添花”，而是保障安全、提升效率的“标配”。作为监控可视化的核心平台，Grafana在这方面做得相当开放，支持与多种身份提供商（IdP）无缝对接。今天，我们就来聊聊如何用开源的Keycloak，为Grafana搭起一座安全便捷的SSO桥梁，实现用户的集中管理与一键登录。
1. Keycloak配置：打好地基
万事开头难，但第一步很明确：在Keycloak中创建一个客户端（Client）。
创建客户端：
(1) 进入Keycloak管理后台，依次点击 Manage -> Clients -> Create client。
(2) General settings（通用设置）：这是基础信息页。
- Client type：选择 OpenID Connect。
- Client ID：自定义一个ID，比如
grafana-oauth，后续在Grafana配置中会用到。
(3) Capability config（能力配置）：几个关键开关在这里。
- Client authentication：这个开关决定了OIDC客户端的类型，务必开启。
- Authorization：为客户端启用/禁用细粒度授权支持，建议开启。
- Direct access grants：启用后，客户端可以直接用用户名/密码向Keycloak换取令牌。根据安全策略决定是否开启。
(4) Login settings（登录设置）：配置回调地址，确保通信畅通。
- Root URL：填写你的Grafana基础访问地址。
- Valid redirect URIs：填写Keycloak在认证成功后需要回调的Grafana地址，通常格式为
https://。/* - Web origins：允许的CORS来源，可以填写Grafana的地址以解决跨域问题。
(5) 点击 Sa ve 保存配置。
(6) 获取Client Secret：保存后，在客户端的 Credentials 标签页中，你会找到 Client Secret。把它复制下来，下一步配置Grafana时必不可少。
2. Grafana配置：建立连接
Keycloak这边准备就绪，接下来轮到Grafana了。核心是通过环境变量告诉Grafana去哪里认证。
(1) 修改Grafana配置文件：以下是一组关键的OAuth配置示例。
GF_AUTH_GENERIC_OAUTH_ENABLED: true
GF_AUTH_GENERIC_OAUTH_NAME: Keycloak(SSO)
GF_AUTH_GENERIC_OAUTH_ALLOW_SIGN_UP: true
GF_AUTH_GENERIC_OAUTH_CLIENT_ID: grafana-oauth
GF_AUTH_GENERIC_OAUTH_CLIENT_SECRET: xxxxxxxsV07BfumZdYd6KAmljGJRHk
GF_AUTH_GENERIC_OAUTH_SCOPES: "openid email profile offline_access roles"
GF_AUTH_GENERIC_OAUTH_EMAIL_ATTRIBUTE_NAME: preferred_username
GF_AUTH_GENERIC_OAUTH_EMAIL_ATTRIBUTE_PATH: email
GF_AUTH_GENERIC_OAUTH_LOGIN_ATTRIBUTE_PATH: preferred_username
GF_AUTH_GENERIC_OAUTH_AUTH_URL: https://172.139.20.xxx:8443/realms/master/protocol/openid-connect/auth
GF_AUTH_GENERIC_OAUTH_TOKEN_URL: https://172.139.20.xxx:8443/realms/master/protocol/openid-connect/token
GF_AUTH_GENERIC_OAUTH_API_URL: https://172.139.20.xxx:8443/realms/master/protocol/openid-connect/userinfo
GF_AUTH_GENERIC_OAUTH_SKIP_ORG_ROLE_SYNC: true
GF_AUTH_GENERIC_OAUTH_ROLE_ATTRIBUTE_PATH: grafana_role小提示：这里以Helm部署为例，所以采用环境变量配置。其中 auth_url, token_url 和 api_url 的地址如果不确定，可以直接访问Keycloak的发现端点来确认：https://。
(2) 【可选】处理自签名证书：如果Keycloak使用了自签名证书，需要让Grafana信任它。可以通过添加Init Container来更新证书库。
extraInitContainers:
- name: add-custom-ca-cert
image: 填写grafana镜像
command:
- update-ca-certificates
volumeMounts:
- mountPath: /etc/ssl/certs
name: etc-ssl-certs
- mountPath: /usr/local/share/ca-certificates
name: custom-ca-certificates
readOnly: true
extraVolumeMounts:
- mountPath: /etc/ssl/certs/
name: etc-ssl-certs
extraVolumes:
- name: etc-ssl-certs
emptyDir: {}
- name: custom-ca-certificates
configMap:
name: custom-ca-certificates(3) 重启Grafana服务：配置完成后，应用更改。
$ helm -n obs-system upgrade grafana -f grafana-values.yaml grafana3. Grafana验证单点登录
配置完成后，激动人心的验证时刻到了。
(1) 登录页面：访问Grafana，你会发现登录页多了一个“Sign in with Keycloak(SSO)”的按钮。
(2) 点击Sign in with Keycloak(SSO)：系统会跳转到Keycloak的登录页面。
这里有两点需要特别注意：
- 不要使用
admin用户名尝试登录，因为Grafana本地已经存在一个admin用户。 - 在Keycloak中创建的用户，必须配置邮箱地址，否则Grafana可能无法正确识别用户。
(3) Sign in：使用Keycloak中的用户凭证登录，成功后会自动跳转回Grafana，并完成登录。
4. 结语
走完这套流程，Grafana和Keycloak的SSO集成就算大功告成了。这不仅仅是多了一个登录选项，更是为后续实施更精细的RBAC（基于角色的访问控制）、集中审计日志等企业级功能铺平了道路。这种身份认证与业务应用解耦的架构，让运维管理更灵活，安全边界也更清晰可控。
