Keycloak OIDC 配置必须严格匹配 Go 客户端 redirect_uri，Valid Redirect URIs 需精确到协议、域名、端口和路径；客户端类型应选 confidential，Web Origins 生产环境须明确指定；Go 侧推荐组合使用 golang.org/x/oauth2 和 gocloak.ValidateToken 校验 token；透传 token 时需原样携带 Authorization Header；refresh token 需自行缓存并按需刷新，失败时清空缓存并强制重新登录。
Keycloak OIDC 配置必须匹配 Go 客户端的 redirect_uri
Keycloak 后台创建客户端时，Valid Redirect URIs 必须精确到协议、域名、端口和路径层级。比如你的 Go 服务运行在 http://localhost:8080，且登录回调路由是 /auth/callback，那这里只能填 http://localhost:8080/auth/callback —— 多一个斜杠、少一个端口、写成 http://127.0.0.1:8080/... 都会导致 Keycloak 拒绝回调，返回 invalid_redirect_uri 错误。
常见踩坑点：
-
Web Origins字段填*仅适用于开发，生产环境必须明确列出前端地址（如https://app.example.com），否则 CORS 会拦截 token 响应 - 客户端类型选
confidential（而非public），否则 Go 服务无法安全持有client_secret - 确保 Keycloak realm 的
Access Token Lifespan足够长（比如 5m），避免 Go 服务还没来得及校验 token 就已过期
用 golang.org/x/oauth2 + go-keycloak-client 实现登录与 token 校验
Go 侧不建议手写 OIDC 流程，优先组合使用 golang.org/x/oauth2（处理授权码交换）和 github.com/Nerzal/gocloak/v13（解析和校验 JWT）。前者负责标准 OAuth2 授权码流程，后者提供 ValidateToken 方法验证 signature、issuer、audience 和时间窗口。
关键实操注意：
立即学习“go语言免费学习笔记（深入）”；
Go 配置库，使用 spf13/viper — 分层优先级（flag > env >file > KV > default），提供 BindPFlag/BindPFlags、SetEnvPrefix + SetEnvKeyReplace 等功能。
-
oauth2.Config.RedirectURL必须和 Keycloak 中配置的完全一致，且需是完整 URL（不能是相对路径） - 调用
gocloak.ValidateToken前，要先用gocloak.RestyClient().SetTLSClientConfig(&tls.Config{InsecureSkipVerify: true})绕过自签名证书（仅限开发）；生产必须配可信 CA - token 中的
aud字段默认是 client_id，校验时必须传入相同值，否则ValidateToken返回token is not valid for this audience - 不要直接解析 JWT payload 判断权限 —— 必须调用
ValidateToken，它会检查 signature、exp、iat、nbf 等全部 OIDC 规范要求项
微服务间透传 token 时，Authorization Header 格式不能出错
Go 微服务 A 调用服务 B 时，若需透传用户身份，必须把原始 Authorization: Bearer <access_token> 原样带上。任何修改（比如 base64 重编码、拼接前缀失败、混用 IdToken）都会导致下游服务校验失败。
容易忽略的细节：
- 从 HTTP header 取 token 时，用
r.Header.Get("Authorization")，然后手动切掉"Bearer "前缀 —— 注意空格数量，别写成"Bearer"或"bearer " - 下游服务校验 token 时，
gocloak.ValidateToken的opts参数里，Realm和ClientID必须和 Keycloak 控制台中对应 realm 和 client 设置严格一致 - 如果服务 B 是用 Gin 或 Echo，中间件里提取 token 后应立刻存入
context.Context，避免后续逻辑重复解析
refresh token 自动续期需单独管理生命周期
OIDC 的 refresh_token 默认只在首次授权响应中返回一次，且 Keycloak 默认关闭了 Refresh Token Max Reuse 限制。但 Go 服务若想自动续期，不能依赖每次请求都去换新 token —— 必须自己缓存并按需刷新。
实际做法：
- 在用户首次登录成功后，把
refresh_token和过期时间（expires_in减去 60 秒缓冲）一起存入内存 map 或 Redis，key 为用户唯一标识（如sub字段） - 每次收到请求时，检查 token 是否将在 2 分钟内过期；若是，用缓存的
refresh_token调用 Keycloak 的/realms/{realm}/protocol/openid-connect/token换新 - Keycloak 的
Refresh Token Max Reuse默认为 0（禁用复用），若开启需设为 ≥1，否则第二次 refresh 就会失败并返回invalid_grant - refresh 失败时（比如 token 已被撤销），必须清空本地缓存，并引导用户重新登录 —— 不要静默 fallback 到无认证状态
token 解析和刷新逻辑耦合度高，建议封装成独立结构体，避免每个 handler 重复写校验+续期逻辑。
