Keycloak、OIDC、OAuth 2.0 与 LDAP 单点登录生产实践
Keycloak 可为 Web、移动、API 和内部系统提供 OIDC、OAuth 2.0、SAML、LDAP 联邦、MFA 和统一会话。身份系统一旦故障会影响所有应用登录，一旦配置错误又可能造成越权。生产运维必须同时理解协议、Realm/Client、Token、反向代理、集群缓存、数据库、密钥轮换和灾难恢复。
OAuth 2.0 主要解决授权，OIDC 在其上增加身份层。不要把 Access Token 当作长期会话，也不要关闭签名、Issuer、Audience 或 Redirect URI 校验来解决集成问题。
一、角色与流程
Resource Owner（用户）
Client（应用）
Authorization Server（Keycloak）
Resource Server（API）
Identity Provider / LDAP（可选）
浏览器应用通常使用 Authorization Code + PKCE。机器间调用使用 Client Credentials。Implicit 与 Resource Owner Password 等旧模式不应作为新系统默认选择。
二、Realm 规划
Realm 是用户、Client、角色、身份源和策略的隔离边界。按公司、环境或强隔离租户规划，不要为每个小应用创建 Realm，也不要让开发和生产共享 Realm。
Master Realm 只用于管理，日常应用不应注册其中。管理员权限采用专用账号、MFA 和审计。
三、Client 类型
- Public Client：无法安全保存 Secret，如 SPA/移动端；
- Confidential Client：后端可保存 Secret；
- Bearer-only/资源服务概念需按当前版本配置方式理解。
每个 Client 精确配置 Redirect URI、Web Origin、Root URL、Logout URI 和授权流程。避免 * 通配生产域名。
四、Authorization Code + PKCE
流程：应用生成 Verifier/Challenge，浏览器跳转登录，回调收到 Code，后端或客户端用 Verifier 换 Token。
安全要求：
- HTTPS；
- State 防 CSRF；
- Nonce 防重放；
- PKCE S256；
- 精确 Redirect URI；
- Code 短时有效且一次性；
- 不在 URL/日志记录 Token。
五、Token
Access Token 用于访问 API，ID Token 表示认证信息，Refresh Token 用于换新 Token。API 必须校验：签名、Issuer、Audience、过期、Not Before、算法和必要 Scope/Role。
不要只因为签名正确就信任所有 Token；Token 可能签给其他 Client。
六、Token 生命周期
短 Access Token 降低泄露风险，Refresh Token 和会话决定用户体验。需要平衡：
- SSO Session Idle/Max；
- Client Session；
- Access Token Lifespan；
- Refresh Token Rotation；
- Offline Token；
- Remember Me。
修改生命周期前测试长表单、移动端、后台任务和断网恢复。
七、角色与权限
Realm Role 跨 Client，Client Role 属于特定应用。使用 Group 聚合用户，Role 表达权限，避免为每个用户单独配置大量 Mapping。
细粒度业务权限通常仍由应用维护，Keycloak 提供身份与粗粒度角色。不要把所有业务数据权限塞入 Token，导致 Token 巨大且难以即时撤销。
八、Protocol Mapper 与 Claim
Mapper 将用户属性、角色或组加入 Token。治理：
- Claim 名称和类型版本化；
- 只发送应用所需数据；
- 不放密码、身份证或敏感后台属性；
- 控制 Group/Role 数量；
- 避免 Token 超过代理/Header 限制；
- API 对缺失 Claim 有明确行为。
九、LDAP/AD 联邦
Keycloak 可连接 LDAP/Active Directory，导入或按需查询用户，并映射属性、组与角色。
生产需确认：
- 连接池、TLS 与证书；
- Bind 账号最小权限；
- User DN、Filter 与唯一属性；
- Read-only/Writeable/Unsynced 模式；
- 导入、周期同步和删除行为；
- AD 密码策略；
- LDAP 不可用时登录与缓存行为。
同步任务应监控新增、更新、失败和耗时。
十、外部身份提供商
接入企业微信、Azure AD、其他 OIDC/SAML IdP 时，Keycloak 作为 Broker。必须校验外部 Issuer、签名、Claim 映射和账号关联策略。
仅按 Email 自动关联存在账号接管风险，应结合已验证邮箱、域、人工绑定或首次登录流程。
十一、MFA 与 WebAuthn
支持 TOTP、WebAuthn/Passkey 等。管理员和高风险操作强制 MFA；普通用户可按风险和组织策略逐步启用。
同时准备恢复码、丢失设备流程、Helpdesk 身份核验和审计。MFA 重置本身是高风险操作。
十二、认证流程
Authentication Flow 可组合 Cookie、用户名密码、OTP、条件和自定义 Authenticator。生产修改前复制 Flow 并灰度，避免直接破坏 Browser Flow 导致全员无法登录。
每个 Flow 变更需准备管理员后台访问和数据库级恢复路径。
十三、反向代理与 Hostname
Keycloak 常在 LB/代理后运行。必须正确配置外部 Hostname、Proxy Header、HTTPS 和管理地址。
bin/kc.sh start \
--hostname https://sso.example.com \
--proxy-headers xforwarded \
--http-enabled true
代理必须覆盖而不是信任客户端传入的 Forwarded/X-Forwarded Header，否则可能产生安全漏洞和错误回调地址。
十四、生产数据库
生产使用受支持的外部数据库，并配置高可用、连接池、备份、PITR、监控和维护。数据库是 Keycloak 可靠性的核心。
不要把开发默认数据库用于生产。升级前备份数据库和 Realm 配置，并明确数据库迁移是否可逆。
十五、集群与缓存
多个 Keycloak 实例通过 Infinispan/JGroups 等实现集群缓存与会话协调。生产：
- 至少两个实例；
- 跨故障域但保持低延迟；
- 节点发现稳定；
- 集群通信 TLS；
- LB 健康检查；
- 优雅停机和连接排空；
- 监控缓存与远程会话。
粘性会话可提升缓存效率，但不能代替集群状态一致性。
十六、健康检查与启动
区分 Liveness、Readiness 和外部 LB 检查。实例启动和缓存预热期间不应过早接流量。数据库短暂故障时避免所有实例被同时重启形成风暴。
十七、密钥与证书轮换
Realm 签名密钥用于 Token。轮换应保留旧公钥一段时间，让已签 Token 可验证，同时新 Token 使用新密钥。
客户端 Secret、LDAP Bind 密码、数据库密码和 TLS 证书也需轮换。建立依赖清单和双密钥过渡，避免一次替换导致全部应用失败。
十八、登出与会话撤销
浏览器退出、Keycloak 会话、应用本地会话和 Refresh Token 是不同层次。实现 RP-Initiated Logout、Backchannel/Frontchannel Logout 时测试多应用、浏览器拦截第三方 Cookie 和失败重试。
JWT Access Token 通常在过期前无法被所有离线 API 即时撤销，因此高风险操作可使用短 Token、Introspection 或额外会话检查。
十九、审计与事件
启用登录/管理员事件并发送到安全日志平台。记录用户、Client、来源、结果、错误、MFA、管理员变更，但不要记录密码、完整 Token 和 Secret。
告警：暴力破解、管理员登录、MFA 重置、Client Secret 变更、Redirect URI 扩大、身份源失败和异常 Token 签发。
二十、备份与恢复
备份：数据库、Realm/Client 配置、密钥材料、主题、自定义 Provider、证书、反向代理、构建镜像和版本信息。
Realm Export 可辅助迁移和审计，但不能简单替代数据库一致备份。恢复在隔离环境验证用户、Client、角色、LDAP、Token 签名、登录和退出。
二十一、升级
- 阅读迁移指南与弃用项；
- 备份数据库与配置；
- 测试自定义主题/Provider；
- 在预生产回放主要登录流程；
- 灰度或按支持策略升级；
- 验证数据库迁移、缓存、Token 和代理；
- 观察登录失败和响应延迟。
二十二、常见故障
Invalid Redirect URI
检查 Scheme、Host、Port、Path、代理 Hostname 和 Client 精确 URI，不要用全局通配解决。
401 但 Token 有效
检查 Audience、Issuer、算法、时钟、Role/Scope 和 API 使用的 JWKS 缓存。
登录循环
检查 Proxy Header、HTTPS、Cookie Domain/SameSite、会话缓存和 LB 粘性。
LDAP 用户无法登录
检查连接、证书、Bind、User DN/Filter、Mapper、同步和密码策略。
集群节点切换后掉线
检查会话缓存、节点发现、代理、Cookie、数据库和优雅停机。
二十三、上线清单
- OAuth/OIDC Flow 按客户端类型选择；
- Redirect URI 与 Web Origin 精确；
- API 校验签名、Issuer、Audience 与过期；
- LDAP/IdP 使用 TLS、最小权限和账号关联保护；
- 管理员强制 MFA，重置流程有审计；
- Hostname/Proxy Header 不信任客户端输入；
- 数据库和缓存集群高可用；
- 密钥轮换和旧 Token 过渡完成演练；
- 数据库、Realm、密钥和自定义扩展可恢复；
- 登录、刷新、退出、故障切换和升级均有自动测试。
参考资料
- Keycloak Documentation：
https://www.keycloak.org/documentation - Production Configuration：
https://www.keycloak.org/server/configuration-production - Hostname and Reverse Proxy：
https://www.keycloak.org/server/hostname