用 Keycloak 搭建统一单点登录

适用场景

多个内部系统需要统一账号、OIDC/SAML 登录、LDAP 对接和集中授权。Keycloak 适合自建 SSO，尤其是需要细粒度角色和客户端级权限的场景。

前置条件

• 一个域名和 TLS 证书。
• PostgreSQL/MySQL 等外部数据库；生产不要使用内置 H2。
• 反向代理或 Ingress，正确传递 X-Forwarded-* 头。
• 明确 realm 划分：按环境还是按租户隔离。

步骤

1. 使用 Helm 安装生产实例：

helm repo add codecentric https://codecentric.github.io/helm-charts
helm install keycloak codecentric/keycloakx \
  --namespace keycloak --create-namespace \
  --set replicas=2 \
  --set ingress.enabled=true \
  --set ingress.hostname=sso.example.com \
  --set postgresql.enabled=true

2. 等待 Pod 就绪并创建管理员：

kubectl -n keycloak get pods
kubectl -n keycloak exec -it deploy/keycloak -- \
  /opt/keycloak/bin/kcadm.sh config credentials \
  --server http://localhost:8080 --realm master \
  --user admin --password "$KEYCLOAK_ADMIN_PASSWORD"

3. 创建 realm 和客户端：

kcadm.sh create realms -s realm=corp -s enabled=true
kcadm.sh create clients -r corp \
  -s clientId=wiki -s enabled=true \
  -s protocol=openid-connect \
  -s 'redirectUris=["https://wiki.example.com/*"]' \
  -s publicClient=false -s secret="$WIKI_CLIENT_SECRET"

4. 对接 LDAP 或 Active Directory：

kcadm.sh create components -r corp \
  -s name=ldap -s providerId=ldap \
  -s providerType=org.keycloak.storage.UserStorageProvider \
  -s 'config.connectionUrl=["ldap://ldap.example.com:389"]' \
  -s 'config.usersDn=["ou=people,dc=example,dc=com"]' \
  -s 'config.bindDn=["cn=svc,ou=services,dc=example,dc=com"]' \
  -s 'config.bindCredential=["***"]'

5. 配置角色和组映射，按最小权限授予客户端角色。

6. 应用侧使用 OIDC 授权码模式接入，校验 issuer、audience 和签名。Spring Security、oauth2-proxy、Nginx auth_request 都可以作为客户端。

7. 开启登录审计和暴力破解防护：

kcadm.sh update realms/corp \
  -s bruteForceProtected=true \
  -s failureFactor=5 \
  -s waitIncrementSeconds=60

验证

• 访问受保护应用会跳转到 Keycloak 登录页。
• 登录后回调成功，应用能拿到 sub、email、groups 等声明。
• 退出登录后，应用侧会话和 Keycloak SSO 会话都失效。
• LDAP 用户首次登录能同步，禁用用户无法登录。
• 多副本部署时，任一 Pod 故障不影响登录。

回滚

• 保留旧认证方式（本地账号或另一个 IdP）作为应急入口。
• 客户端配置变更前导出 realm：kcadm.sh get realms/corp > corp.json。
• 数据库升级前做完整备份，并确认 Keycloak 版本支持的回滚路径。
• 切换 DNS 前用 hosts 验证新实例，确认后再切流量。

常见坑

• 生产使用 dev 模式或 H2，重启后数据丢失。
• hostname、proxy 和 X-Forwarded-* 配置不一致，重定向到错误的 http 地址。
• redirect URI 少了尾部斜杠或通配符不匹配，报 Invalid parameter: redirect_uri。
• 客户端误设为 public，secret 泄露后任何人可冒充。
• LDAP 的 bind DN、用户 DN 或 UUID 属性配置错误，用户无法同步。
• 多副本没有共享数据库和缓存，会话不一致。

相关命令

• kcadm.sh — realm、client、LDAP 和策略管理
• kubectl — 查看 Keycloak 与数据库状态
• curl — 检查 OIDC discovery 和 token 端点
• oauth2-proxy — 为无 OIDC 支持的应用加登录代理