优先选gocloak用于需调用Keycloak管理API（如查用户、绑角色），选标准oauth2包用于纯前端跳转+后端校验token的Web应用；前者功能全但重，后者轻量可控。
直接结论：用 gocloak 还是标准 oauth2 包，取决于你是否需要调 Keycloak 管理 API；不是“集成 Keycloak”这件事本身难，而是混淆了「前端登录跳转」和「后端管理操作」两种场景，结果引入一堆没用的依赖和超时风险。
该用 gocloak 还是 golang.org/x/oauth2？看你的使用场景
如果你的 Go 服务要查用户列表、批量绑角色、刷新管理员令牌、或在 CLI 工具里删测试账号 —— 选 gocloak。它封装了 /admin/realms/{realm}/users、/realms/{realm}/protocol/openid-connect/token 等全部 REST 路径，client.GetUsers() 一行就能拿到带属性的用户数组。
如果你只是写一个 Web 后端，用户点登录 → 跳 Keycloak → 回来校验 id_token → 写 session 或 JWT 返回给前端 —— 别碰 gocloak。用 golang.org/x/oauth2 配 oauth2.Config 就够了，三步走：AuthCodeURL → Exchange → oidc.IDTokenVerifier 校验，逻辑干净，中间件也容易套。
常见错误现象：
立即学习“go语言免费学习笔记（深入）”；
-
gocloak.Login()成功但后续GetUsers()返回空或 403 —— 没传管理员 token，或 token scope 不含view-users - 用
gocloak做纯登录却卡在context.Background()—— 它默认不设 timeout，生产环境必须显式传context.WithTimeout(ctx, 5*time.Second) -
oauth2.Config.RedirectURL和 Keycloak 后台填的Valid Redirect URIs差一个斜杠（比如/callbackvs/callback/）→ 直接报invalid_request
Keycloak OAuth2 参数对不齐，90% 的跳转失败都出在这儿
Keycloak 对参数名、大小写、末尾斜杠、scope 组合极其敏感，不是服务挂了，是你配错了。
必须严格对齐的几项：
-
RedirectURL必须和 Keycloak 后台 Clients → Settings → Valid Redirect URIs 完全一致，包括协议、端口、路径、末尾斜杠 -
Scopes至少含"openid"；要解析name或email，得加"profile"和"email" - Client 的
Access Type设为confidential时，Exchange必须传client_secret；设为public（如 Vue SPA）就不能传，否则 Keycloak 直接拒掉请求 -
AuthURL和TokenURL中的 realm 名必须小写且完全匹配，MyRealm和myrealm是两个 realm
示例（正确）：
cfg := &oauth2.Config{
ClientID: "myapp",
ClientSecret: "xxx", // confidential 才填
RedirectURL: "http://localhost:8080/callback/",
Endpoint: oauth2.Endpoint{
AuthURL: "https://keycloak.example.com/auth/realms/myrealm/protocol/openid-connect/auth",
TokenURL: "https://keycloak.example.com/auth/realms/myrealm/protocol/openid-connect/token",
},
Scopes: []string{"openid", "profile", "email"},
}
token 校验不能只靠 jwt.Parse()，issuer/audience/signature 缺一不可
很多人用 jwt.Parse() 解出 map 就以为 token 有效，结果伪造的 token 也能过 —— 因为没设 keyfunc，也没验 issuer 和 aud。
Keycloak 发的 ID Token 是标准 OIDC token，必须同时验证三项：
-
issuer：必须等于 Keycloak realm 的 issuer URL，例如"https://keycloak.example.com/auth/realms/myrealm" -
audience：必须包含你的ClientID，不能只 check 是否非空 -
signature：要用 Keycloak 提供的公钥（从/.well-known/openid-configuration拿）验签，别硬编码密钥
推荐用 github.com/coreos/go-oidc/v3/oidc 的 Verifier，它自动拉取 jwks_uri 并缓存 key：
provider, _ := oidc.NewProvider(ctx, "https://keycloak.example.com/auth/realms/myrealm")
verifier := provider.Verifier(&oidc.Config{ClientID: "myapp"})
idToken, err := verifier.Verify(ctx, rawIDToken)
gocloak 的 context 和 error 处理容易被忽略
gocloak 默认所有 HTTP 请求都用 context.Background()，没有 timeout 控制。生产环境一旦 Keycloak 响应慢或网络抖动，goroutine 就卡死，连接池耗尽。
必须显式传带 timeout 的 context：
- 所有
client.Xxx()方法第一个参数都是ctx context.Context - 别用
context.Background()，改用context.WithTimeout(context.Background(), 5*time.Second) - 错误类型不是统一
error，而是*gocloak.APIError，含Code（HTTP 状态码）、Message、Response字段，方便做重试或日志归类
容易踩的坑：
- 没检查
APIError.Code == 401就直接重试 → 可能是 token 过期，该先刷新再重试 - 用
gocloak.Login()获取用户 token 时，传的username和password是明文，别在日志里打出来 -
gocloak的 struct 字段全是指针（如*string），为区分未设置和零值；但 JSON unmarshal 时若字段缺失会留 nil，访问前得判空
