基于Keycloak的Google身份验证：如何使用Google凭据调用Keycloak API

核心原理 #

已在Keycloak完成Google身份提供商配置的前提下，无需自行实现鉴权逻辑，只需通过Keycloak原生的令牌交换能力，将用户持有的Google有效令牌兑换为Keycloak官方签发的访问令牌，即可用该令牌调用对应权限范围的Keycloak API、以及受Keycloak保护的微服务/REST接口。

前置准备 #

操作前需确认Keycloak侧已完成两项基础配置：

• 对应领域下的Google身份提供商存储令牌开关已开启，路径为「身份提供商」→「Google」→「设置」页签
• 客户端已开启令牌交换权限，路径为「客户端」→「对应客户端」→「权限」页签，找到token-exchange权限并开启

具体操作步骤 #

1. 先从客户端侧获取用户授权后拿到的有效Google访问令牌/ID令牌
2. 调用Keycloak令牌端点发起令牌交换请求，请求示例如下：

curl --location --request POST 'https://<你的Keycloak服务域名>/realms/<你的领域名>/protocol/openid-connect/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'client_id=<你的客户端ID>' \
--data-urlencode 'client_secret=<你的客户端密钥>' \
--data-urlencode 'grant_type=urn:ietf:params:oauth:grant-type:token-exchange' \
--data-urlencode 'subject_token=<用户的Google有效令牌>' \
--data-urlencode 'subject_issuer=<Google身份提供商在Keycloak中的别名，默认是google>' \
--data-urlencode 'subject_token_type=urn:ietf:params:oauth:token-type:access_token'

3. 请求成功后即可获取Keycloak返回的access_token字段，后续请求Keycloak API时在请求头带上Authorization: Bearer <获取到的access_token>即可正常鉴权。

常见异常排查 #

• 提示「无效的subject_issuer」：检查传入的subject_issuer参数值和Keycloak中Google身份提供商的别名是否完全一致，大小写敏感
• 提示「权限不足」：确认客户端已开启令牌交换权限，同时传入的Google令牌未过期、签发受众和Google身份提供商配置的客户端ID一致
• 调用Keycloak管理接口返回403：需要在Keycloak侧给对应用户绑定对应级别的管理角色（如realm-admin），普通用户默认无管理类API的访问权限

内容的提问来源于stack exchange，提问作者Skaros Ilias