keycloak~实现OAuth 2.0 Token Exchange

• 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类型

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'

交换token配置步骤详解

1. 创建令牌交换策略

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

1. 创建策略：

   • 点击Create Policy按钮
   • 选择策略类型为Client
   • 策略名称：例如wso2-token-exchange-policy

2. 配置策略：

   • 在策略配置页面，找到Clients选项
   • 添加允许进行令牌交换的客户端（即WSO2 APIM的客户端ID）
   • 保存策略

3. 绑定策略：

   • 返回到token-exchange权限页面
   • 将刚创建的策略绑定到该权限
   • 确保权限状态为Enabled

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

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

1. 进入Identity Providers菜单
2. 点击Add provider ，选择OpenID Connect v1.0
3. 配置信息：
   • 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格式）
• subject_issuer : 必须与WSO2 APIM令牌中的iss声明完全一致
• audience: keycloak目标客户端ID（您希望获得的Keycloak令牌的受众）,可以省略
• scope: 请求的权限范围

常见问题处理

1. "Client not allowed to exchange"：

   • 确认客户端已添加到token-exchange策略中
   • 检查客户端是否为Confidential类型

2. "Invalid subject token"：

   • 验证WSO2 APIM令牌格式
   • 确认subject_issuer参数与令牌中的iss一致
   • 检查令牌是否过期

3. "Subject token issuer not trusted"：

   • 确认Identity Provider配置正确
   • 检查颁发者URL是否完全匹配

注意事项

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

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

错误总结

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"
}