Keycloak Realm配置必须启用Authorization Code Flow，否则登录跳转失败或code为空；需设Client Protocol为openid-connect、Access Type为confidential，Valid Redirect URIs须精确匹配Go回调地址，禁用Implicit Flow，并从.well-known/openid-configuration动态获取AuthURL/TokenURL。
Keycloak Realm配置必须启用Authorization Code Flow
如果登录后跳转失败或code参数为空，大概率是Realm里没开标准授权码流程。进Admin Console → 进入对应Realm → Clients → 选中你的client → 确保Client Protocol为openid-connect，且Access Type设为confidential（否则无法安全交换code换token）。
关键检查项：
-
Valid Redirect URIs必须精确匹配Go服务接收回调的地址，比如http://localhost:8080/auth/callback（末尾斜杠不能少，也不能多） -
Web Origins若前端同域调用，填*；若分离部署，需明确列出前端域名（如https://app.example.com） - 务必关闭
Standard Flow Enabled（即Authorization Code Flow），同时关闭Implicit Flow——后者已弃用且不返回code
Go端用golang.org/x/oauth2构造正确Config
Keycloak不是通用OAuth2提供方，它的AuthURL和TokenURL必须从Realm的OpenID Connect Endpoint获取，不能硬编码为https://keycloak/auth/realms/xxx/protocol/openid-connect/auth这类路径——它可能含代理路径或自定义上下文根。
实操建议：
- 访问
https://<your-keycloak>/auth/realms/<realm-name>/.well-known/openid-configuration</realm-name></your-keycloak>，取authorization_endpoint和token_endpoint字段值 -
ClientID和ClientSecret来自Keycloak Client的Credentials页（Client ID是字符串，Client Secret是长UUID） -
RedirectURL必须与Realm中Valid Redirect URIs完全一致，包括协议、端口、路径，且Go HTTP handler要监听同一路径 - scope至少包含
openid，推荐加profile email，否则userinfo接口可能返回空字段
回调Handler里必须用oauth2.Config.Exchange换Token
收到code后直接调http.Post发到Token端点是错的——会因缺少PKCE验证或签名失败被拒绝（尤其Keycloak 20+默认开启PKCE）。必须用oauth2.Config.Exchange，它自动处理code verifier/challenge、form编码、basic auth头等细节。
常见错误现象：
- 返回
{"error":"invalid_grant","error_description":"Code not valid"}→ 通常RedirectURL不一致或code已过期（默认10分钟） - 返回
401 Unauthorized→ClientSecret错、client设为public却用了secret、或Realm禁用了client credentials flow - 拿到
id_token但access_token为空 → 检查scope是否漏了openid，Keycloak要求该scope才签发JWT格式的access token
解析id_token时别手动验签，用golang-jwt/jwt/v5 + Keycloak JWKS
Keycloak的id_token是JWT，但公钥不在配置里明文给出，必须动态从jwks_uri（在.well-known/openid-configuration中）加载。自己拼rsa.PublicKey或硬编码PEM会失败——Keycloak轮换密钥后签名立刻失效。
安全做法：
- 用
github.com/golang-jwt/jwt/v5（非老版jwt-go，后者有严重漏洞） - 初始化
jwt.WithKeySet配合github.com/lestrrat-go/jwx/jwk远程加载JWKS - 验证时必须校验
iss（应为https://<keycloak>/auth/realms/<realm></realm></keycloak>）、aud（client_id）、exp、iat，Keycloak默认不校验nonce，但建议保留
复杂点在于JWKS缓存——频繁请求影响性能，又不能永久缓存。实际项目里建议加内存缓存（TTL 1小时），并监听Keycloak密钥轮换事件（通过Admin API或定期刷新）。这个环节最容易被跳过，导致上线后某天突然大量用户登录失败。
