Keycloak 实战配置与排错指南 — 解决方案 | IDaaS Book
这部分是「带着问题来，拿着方案走」的实战指南。每篇文章聚焦一个具体的集成场景：出问题怎么办、最小配置怎么写、怎么验证配对了、配错了什么症状、怎么回滚。
与前面章节的理论和架构介绍不同，这里的文章结构统一为：场景描述 → 适用/不适用 → 最小配置 → 验证 → 常见错误表 → 回滚方式。
已覆盖主题：
| 主题 | 关键词 |
|---|---|
| Keycloak 社交登录配置：Google / GitHub / Apple / Microsoft | Google OAuth, GitHub OAuth, Apple Sign In, Microsoft Entra ID, JIT Provisioning, 属性映射, 回调 URI 排错 |
| Keycloak 26.7 新特性深度解读 | |
| Keycloak 审计日志配置与 IAM 合规实践 | 登录审计、管理员事件、Syslog/ELK 导出、等保 2.0 对齐、事件数据库维护 |
| Keycloak + oauth2-proxy 集成指南 | OIDC, audience, CSRF, redirect loop, Nginx Ingress, ForwardAuth |
| oauth2-proxy 常见错误排错速查表 | csrf cookie not found, expected audience, invalid_token, redirect loop, cookie too large, missing state, 401 排错, 503 诊断 |
| Keycloak 重定向循环与 401 排错指南 | ERR_TOO_MANY_REDIRECTS, 401 Unauthorized, Cookie, TLS 终结, SameSite |
| oauth2-proxy 深度介绍 | 架构原理、Provider 选型、Cookie/Session、安全加固、与 Pomerium/Traefik/Nginx 对比 |
| Keycloak LDAP / AD 用户联邦 | LDAPS 连接、用户搜索与同步策略、属性映射、组导入、AD 与 OpenLDAP 差异、常见错误排错 |
| Keycloak Adapter 弃用迁移指南 | 从 Keycloak Adapter 迁移到标准 OIDC 库（Spring Security、openid-client、authlib），逐语言迁移路径、角色映射、Token Refresh、常见踩坑与回滚 |
| Keycloak Prometheus 监控指标详解 | metrics 端点启用、ServiceMonitor 采集、Grafana Dashboard 21997、关键告警规则与常见排错 |
| Keycloak 生产巡检与运维清单 | 日常健康检查、监控告警阈值、证书管理、IAM 运维应急响应、月度审计与性能基线 |
| Keycloak 高可用集群部署与灾难恢复 | 多节点集群、JGroups 发现、InfiniSpan 缓存一致性、数据库备份恢复流程与故障演练 |
| Keycloak 细粒度权限与授权策略实战 | Groups vs Roles、Composite Roles、Authorization Services、Policy Evaluation、资源级权限控制 |
| Traefik ForwardAuth + Keycloak + oauth2-proxy | Traefik ForwardAuth 中间件、Middleware CRD、IngressRoute TLS、多中间件链式调用、与 Nginx auth-url 对比 |
| Dex + Keycloak 联合身份：Kubernetes 集群 OIDC 认证 | Keycloak 上游 OIDC 源、Dex OIDC connector、Kubernetes API Server 集成、groups claim 传递、kubelogin、RBAC 绑定 |
| Keycloak 集成企业微信 / 飞书 / 钉钉 OIDC 统一登录 | 企业微信 OAuth、飞书 OIDC、钉钉 OIDC、Identity Provider Broker、回调地址配置、属性映射与 JIT Provisioning |
| Keycloak 生产数据库配置 — PostgreSQL 实战 | H2 迁移 PostgreSQL、Kubernetes Secret 凭据管理、连接池调优、Liquibase 自动建表、常见数据库错误排错 |
| Keycloak 直连 K8s OIDC — API Server 认证与 RBAC | kube-apiserver OIDC 参数、groups claim 映射、kubelogin 接入、RBAC 绑定、与 Dex 方案对比 |
| Keycloak SMTP 邮件配置与密码重置 | SMTP 配置（Gmail/企业微信/AWS SES）、忘记密码流程、邮箱验证、网络层排错、生产检查清单 |
| Keycloak 集群缓存调优与排错指南 | |
| Keycloak Redis 外部会话缓存配置 | |
| Supabase Auth 与 Keycloak 对比及集成 | Supabase GoTrue、Row Level Security、Keycloak 作为外部 OIDC 源、JWT 自定义 Claims、社交登录互通 |
| Dex 身份联邦指南：从原理到 K8s 集成 | Dex OIDC Connector、Kubernetes OIDC 认证、多上游 IDP 联邦、groups claim 映射 |
| IAM 最小权限原则落地指南 | Least Privilege、权限反模式、JIT 提权、角色粒度分层、Keycloak 权限审计、等保最小权限要求 |
| Keycloak 条件认证与 Step-Up 实战 | Authentication Flow、条件 OTP、角色分级 MFA、IP 位置条件、Step-Up 二次认证、LoA 认证级别 |
| Passkey / WebAuthn / FIDO2 IAM 企业落地指南 | FIDO2 注册认证 Mermaid 流程图解、Keycloak Passkey 配置、Conditional UI 自动填充、CTAP 认证器管理、企业恢复策略与常见踩坑 |
| IAM SCIM 用户自动配置实战 | IAM 自动化供应、Joiner-Mover-Leaver、HR→IDP→应用全链路同步、Keycloak SCIM 插件、Azure AD SCIM、常见排错 |
| Keycloak 生产环境完整部署路线图 | |