keycloak~实现OAuth 2.0 Token Exchange

一言一诺 · 发表于 2026-4-23 10:24:00

https://datatracker.ietf.org/doc/html/rfc8693
https://www.keycloak.org/securing-apps/token-exchange

Keycloak 的令牌交换功能如下：

在同一个领域中，客户端可以将为特定客户端创建的现有 Keycloak 令牌交换为针对不同客户端的新令牌。
客户可以将现有的 Keycloak 令牌兑换为外部令牌，例如关联的 Facebook 账户令牌。
客户端可以将外部令牌兑换为 Keycloak 令牌。
客户可以冒充用户。

在Keycloak 14.0.0版本中，即使启用了-Dkeycloak.profile.feature.token_exchange=enabled预览功能，客户端配置页面中确实不会直接显示"exchange token"选项。这是因为旧版令牌交换（V1）需要额外的细粒度权限配置。

keycloak14中开启交换Token功能

Keycloak 14.0.0需要同时启用两个预览功能,需要使用下划线的名字：

-Dkeycloak.profile.feature.admin_fine_grained_authz=enabled
-Dkeycloak.profile.feature.token_exchange=enabled

重启Keycloak服务使配置生效。

为客户端开启token exchnage能力

添加一个wso2的IDP认证服务

IDP中Permission的配置

测试步骤

1 用户在keycloak平台登录

curl -X POST 'https://kc.com/auth/realms/demoo/protocol/openid-connect/token' -H 'Accept: application/json'  --data-urlencode 'grant_type=password' --data-urlencode 'username=test' --data-urlencode 'password=123456' --data-urlencode 'client_id=wso2' --data-urlencode 'client_secret=abf99c64-db24-43fb-b63b-c60213b8052f' --data-urlencode 'scope=openid'

2 用户在wso2平台通过urn:ietf:params:oauth:grant-type:jwt-bearer方式生成对应的token

curl -X POST 'https://wso2.com/oauth2/token' -H 'Content-Type: application/json' -H 'Content-Type: application/json' -u '3N5OKJnQozVc8pPKWHSf1CTLgwQa:HEj3QGF3bPxLIJbTpEmanW5mIjEa' --basic -d '{
  "grant_type": "urn:ietf:params:oauth:grant-type:jwt-bearer",
  "assertion": "kc-access-token",
  "scope": "openid apim:subscribe"
}'

3 用户在keycloak平台根据wso2的token来校验成keycloak的token，注意wso2中的客户端生成的token类型可以是jwt类型和default类型，但scope中必须包含openid的，否则无法获取oauth2/userinfo接口。

curl -X POST 'https://kc.com/auth/realms/fabao/protocol/openid-connect/token' -H 'Content-Type: application/x-www-form-urlencoded'  -u 'wso2:abf99c64-db24-43fb-b63b-c60213b8052f' --basic --data-urlencode 'grant_type=urn:ietf:params:oauth:grant-type:token-exchange' --data-urlencode 'subject_token=wso2-jwt-token' --data-urlencode 'subject_token_type=urn:ietf:params:oauth:token-type:access_token' --data-urlencode 'requested_token_type=urn:ietf:params:oauth:token-type:access_token' --data-urlencode 'scope=openid' --data-urlencode 'subject_issuer=wso2'

一点优化的空间

目前wso2中，api接口使用的token是用户的应用的token，它是一种客户端认证
目前客户端认证不支持scope的openid，导致无法获取当前应用对应的用户/oauth2/userinfo接口，导致这个token不支持token exchange
但是，如果你手动向idn_oauth2_access_token_scope表添加openid的scope，它就可以调用/oauth2/userinfo接口了，有几秒缓存。
![](

优化已经找到方法

为sp应用添加openid的scope，在acp的deployment.toml中，添加相关配置，以开启openid的功能

[oauth]
allowed_scopes = ["openid", "default", "am_application_scope"]

[oauth.grant_type.client_credentials]
enable_openid_scope = true

重启服务后，进行sp的客户端认证，返回值会有openid和default，并有id_token的内容

{
  "access_token": "3baba7f7-3437-345e-89e3-ee9ea9ae6c05",
  "scope": "default openid",
  "id_token": "eyJ4NXQiOiJNekF6TVRGak9EUTFNRE5qT1RVMVpEQTROR1E1TURrell6RTNNV0k0TW1SbFpHVTNZelpqWWprNFpHUmtNMlJoTW1Jd01qQXhZekpsTUdKak5qZG1OdyIsImtpZCI6Ik16QXpNVEZqT0RRMU1ETmpPVFUxWkRBNE5HUTVNRGt6WXpFM01XSTRNbVJsWkdVM1l6WmpZams0WkdSa00yUmhNbUl3TWpBeFl6SmxNR0pqTmpkbU53X1JTMjU2IiwiYWxnIjoiUlMyNTYifQ.eyJhdF9oYXNoIjoiWEIwUWxaWTZ0TVZTWC05U2VrYmpyUSIsImF1ZCI6InNIaXN4ajIzc0JxN2ZZMDcwd2hWTzdwd1VCd2EiLCJzdWIiOiJiMzk4MjcyYi0zYTZjLTQ0MGYtOTQ5NS04OGMzYzE3NThhMzkiLCJuYmYiOjE3NzcyODA0MzksImF6cCI6InNIaXN4ajIzc0JxN2ZZMDcwd2hWTzdwd1VCd2EiLCJhbXIiOlsiY2xpZW50X2NyZWRlbnRpYWxzIl0sImlzcyI6Imh0dHBzOi8vdGVzdC1hcGltLnBrdWxhdy5jb20vb2F1dGgyL3Rva2VuIiwiZXhwIjoxNzgwODgwNDM5LCJpYXQiOjE3NzcyODA0MzksImp0aSI6IjdiYzYyY2U1LTFjODktNDliOS1iNGVmLTY2YmY5NzUxMTEzZSJ9.fPlMbjUvSw9Y59RHe-cIW1MA0DHTnOJ_0-S5Bxoc6yqF6VBa8xZAyjjFtaKxXULMqpcH0f-qKsxoT9X7LnEwGgUWhBHVKmuxK0WHDwsHIyEo1yscVc-Ap6HpfRf_cu8nX0taW0wPdeAdUCgPVGUas2d8YDnz5bKVSlydk9xVxwqvvyJvA_GcpOJ2W14Zk34bjlqOWN6jcaXkUfwrAZbheZudnKVWdI_hYOq0bd94pkRF7-af0b_h7rk4BuAatu_Z8qPhClvWZLpg1hMFRWwobOvBbuijmjMPkcsy0-JSLhc-i5_YXQ7q-U_uuDi1AiEijVlfHb7Uij5zQ98S_jF1Mw",
  "token_type": "Bearer",
  "expires_in": 3600000
}

交换token配置步骤详解

1. 创建令牌交换策略

在客户端的Permissions页面中，找到token-exchange权限，点击进入配置：

创建策略：
- 点击Create Policy按钮
- 选择策略类型为Client
- 策略名称：例如wso2-token-exchange-policy
配置策略：
- 在策略配置页面，找到Clients选项
- 添加允许进行令牌交换的客户端（即WSO2 APIM的客户端ID）
- 保存策略
绑定策略：
- 返回到token-exchange权限页面
- 将刚创建的策略绑定到该权限
- 确保权限状态为Enabled

2. 配置身份提供者（关键步骤）

由于WSO2 APIM是外部令牌颁发者，需要在Keycloak中将其配置为受信任的Identity Provider：

进入Identity Providers菜单
点击Add provider，选择OpenID Connect v1.0
配置信息：
- Alias: wso2-apim（自定义名称）
- Display Name: WSO2 APIM
- Authorization URL: https://test-apim.pkulaw.com/oauth2/authorize
- Token URL: https://test-apim.pkulaw.com/oauth2/token
- Client ID: WSO2 APIM的客户端ID
- Client Secret: WSO2 APIM的客户端密钥
- Issuer: https://test-apim.pkulaw.com（WSO2 APIM的颁发者URL）

3. 配置客户端映射

在WSO2 APIM的客户端配置中，确保：

客户端类型为Confidential
启用了Service Accounts Enabled
配置了正确的重定向URI

发送令牌交换请求

配置完成后，使用以下请求格式交换令牌：

curl -X POST 'https://your-keycloak-host/auth/realms/{realm}/protocol/openid-connect/token' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -H 'Authorization: Basic {base64 kc_client_id:kc_client_secret)}' \
  -d 'grant_type=urn:ietf:params:oauth:grant-type:token-exchange&
      subject_token={WSO2_APIM_TOKEN}&
      subject_token_type=urn:ietf:params:oauth:token-type:access_token&
      requested_token_type=urn:ietf:params:oauth:token-type:access_token&
      subject_issuer=wso2&
      scope=openid profile email'

关键参数说明

subject_token: WSO2 APIM的访问令牌（经过我的测试，使用jwt和default方式的token都是可以的）
subject_issuer: 这是keycloak中定义的idp的Alias
audience: keycloak目标客户端ID（您希望获得的Keycloak令牌的受众）,可以省略
scope: 请求的权限范围,必须包含openid，否则无法获取用户信息

常见问题处理

"Client not allowed to exchange"：
- 确认客户端已添加到token-exchange策略中
- 检查客户端是否为Confidential类型
"Invalid subject token"：
- 验证WSO2 APIM令牌格式
- 确认subject_issuer参数与令牌中的iss一致
- 检查令牌是否过期
"Subject token issuer not trusted"：
- 确认Identity Provider配置正确
- 检查颁发者URL是否完全匹配
** “User already exists”**：
- 请通过wso2生成的token来访问wso2的用户端点是否正常，一般地址为oauth2/userinfo

注意事项

性能考虑：令牌交换涉及额外的网络调用和验证，可能影响性能
安全性：确保只在受信任的客户端间进行令牌交换
版本限制：Keycloak 14.0.0的令牌交换功能可能不如新版本完善

如果配置后仍遇到问题，建议提供具体的错误信息以便进一步排查。

未解决的问题2026-04-24

当keycloak中的本地用户，它的用户名与wso2的token中sub(类型于uuid)同名时，你的wso2交换token将无法完成，因为在交换token时，它会将wso2中sub作为用户名写到keycloak本地用户表，当写时有重复时，会出现错误，如下

{
  "error": "invalid_token",
  "error_description": "User already exists"
}

由于交换token是后端完成的，所以是无交互的动作，这时你在idp中定义的first login flow是没有执行的,如果找一个方法解决让它执行，我们就可以把它和kc本地用户做映射了，问题也就解决了。

解决方法

问题原因
外部 token exchange（TokenEndpoint.importUserFromExternalIdentity / exchangeExternalToken）在 getUserByFederatedIdentity 查不到 (IdP, sub) 时，会按 email 或 username 去建用户；若本地已有同名用户，就直接抛 invalid_token + "User already exists"。
浏览器里的 first broker login 则会让用户确认后把 IdP 绑到已有账号，而 token exchange 没有这条路径，所以会出现你描述的行为。

实现说明
在 TokenEndpoint.java 中做了这些事：

新增 autolinkLocalUserForExternalTokenExchange

在本地已存在用户ID或者 email（在不允许重复 email 的 realm 下）或 username 冲突的用户时，不再抛 “User already exists”。
为该用户 addFederatedIdentity，把当前 token 的 sub 与 IdP 关联起来（等价于“静默完成首次绑定”的一次性效果）。
若该用户已经绑了同一 IdP，但联邦里的 userId（即 sub）与当前 token 不一致，则仍拒绝，并返回更明确的
"User already linked to this identity provider with a different account"，避免把两个不同 IdP 身份错误绑到同一账号。

重构 importUserFromExternalIdentity

用 registerNew 区分新注册与已存在（含通过 lookup 或 autolink 得到）。
非新注册时统一走 updateBrokeredUser + mapper 的 delegateUpdateBrokeredUser（与原来“已按联邦找到用户”的分支一致），保证属性、token、mapper 与登录 broker 后更新一致。

这样：当 IdP 的 sub 在 Keycloak 里还没有对应联邦记录，但计算出的 username（或 email）与本地用户冲突时，会复用该本地用户并建立关联，而不再报 "User already exists"。

子类如需定制策略，可 override autolinkLocalUserForExternalTokenExchange。

错误总结

1 认证类型不支持，这是没开启预览版的token exchange

-Dkeycloak.profile.feature.token_exchange=enabled 
-Dkeycloak.profile.feature.admin_fine_grained_authz=enabled

2 客户端配置了token exchange，但在IDP中没有配置

Client not allowed to exchange

3 wso2-idp用户endpoint错误，这是生成token时，scope中缺少openid

user info call failure

4 获取token时，audience的值写成了wso2客户端ID，这个应该省略，或者用keycloak的client_id，但一般这个值是在basic认证中写的

{
  "error": "invalid_client",
  "error_description": "Audience not found"
}

5 交换token时，没有使用basic认证，将kc的client_id:clientsecret进行传递

{
  "error": "invalid_client",
  "error_description": "Invalid client credentials"
}