配置动态客户端注册（DCR）
动态客户端注册（DCR）允许开发者通过开发者门户以编程方式注册 OAuth 2.0 客户端，无需在身份提供商中手动创建客户端。当开发者创建 OAuth 凭证时，门户会自动向已配置的 DCR 提供商注册客户端，并返回客户端 ID 和密钥。
前置条件
按照从控制台获取令牌中的步骤创建令牌，并将其导出为环境变量：
export API_KEY="a7ee-xxxxxxxxxxxxx"
DCR 提供商类型
API7 支持两种类型的 DCR 提供商：
OIDC
OIDC 提供商类型使用标准 RFC 7591 和 RFC 7592 协议。门户通过身份提供商的 .well-known/openid-configuration 端点发现注册端点。
支持的操作：
| 操作 | 协议 | 描述 |
|---|---|---|
| 注册客户端 | RFC 7591 | 向注册端点发送 POST 请求。 |
| 更新客户端 | RFC 7592 | 使用 registration_access_token 向 registration_client_uri 发送 PUT 请求。 |
| 删除客户端 | RFC 7592 | 向 registration_client_uri 发送 DELETE 请求。 |
| 轮换密钥 | 不支持 | OIDC 提供商不支持密钥轮换。 |
HTTP 桥
HTTP 桥接提供商类型使用自定义 API 与不支持标准 DCR 协议的身份提供商通信。你需要部署 HTTP 桥接服务，在门户 API 和身份提供商之间转换请求。
支持的操作：
| 操作 | 方法 | 端点 |
|---|---|---|
| 注册客户端 | POST | {base_url}/clients |
| 更新客户端 | PUT | {base_url}/clients/{client_id} |
| 删除客户端 | DELETE | {base_url}/clients/{client_id} |
| 轮换密钥 | POST | {base_url}/clients/{client_id}/rotate-secret |
创建 DCR 提供商
OIDC 提供商
curl -k "https://localhost:7443/api/dcr_providers" \
-H "X-API-KEY: ${API_KEY}" \
-H "Content-Type: application/json" \
-d '{
"name": "Keycloak Production",
"provider_type": "oidc",
"issuer": "https://keycloak.example.com/realms/my-realm",
"headers": {
"Authorization": "Bearer <initial-access-token>"
},
"desc": "Production Keycloak instance for OAuth client registration"
}'
如果不在本地运行，请将 localhost 替换为控制台主机。如果控制台使用自签名 TLS 证书，则需要 -k 参数。
❶ name 是 DCR 提供商在 Provider Portal 中显示的名称。
❷ provider_type 选择集成类型。使用 oidc 进行标准 OpenID Connect 动态客户端注册。
❸ OIDC 提供商必须配置 issuer。API7 从发行者的 /.well-known/openid-configuration 文档中发现注册端点。
❹ headers 允许你随每个 DCR 请求发送自定义请求头，例如 Keycloak 的初始访问令牌。
❺ desc 是可选的，可帮助运维人员了解该提供商的用途。
HTTP 桥接提供商
curl -k "https://localhost:7443/api/dcr_providers" \
-H "X-API-KEY: ${API_KEY}" \
-H "Content-Type: application/json" \
-d '{
"name": "Custom OAuth Bridge",
"provider_type": "http_bridge",
"issuer": "https://issuer.example.com",
"provider_config": {
"base_url": "https://oauth-bridge.internal.example.com"
},
"headers": {
"X-API-Key": "<bridge-api-key>"
}
}'
❶ name 是 DCR 提供商 在 Provider Portal 中显示的名称。
❷ provider_type: "http_bridge" 指示 API7 使用桥接服务，而不是标准 OIDC DCR 发现。
❸ issuer 标识桥接服务所代表的 OAuth 发行者。
❹ provider_config.base_url 是 HTTP 桥接提供商所必需的，并指向你的桥接服务。
❺ headers 允许你将身份认证信息（例如 API Key（API 密钥））发送到桥接服务。
使用 DCR 配置 API 产品
创建 DCR 提供商后，在 API 产品的身份认证配置中引用它：
curl -k -X PATCH "https://localhost:7443/api/api_products/{product_id}?portal_id={portal_id}" \
-H "X-API-KEY: ${API_KEY}" \
-H "Content-Type: application/json" \
-d '[
{
"op": "replace",
"path": "/auth",
"value": {
"dcr": {
"dcr_provider_id": "<dcr-provider-id>"
}
}
}
]'
你可以同时启用 DCR 和其他身份认证类型（API Key 身份认证、基本身份认证）。
示例：Keycloak 集成
以下步骤演示了将 Keycloak 集成为 DCR 提供商：
-
在 Keycloak 中创建初始访问令牌：
- 登录 Keycloak Admin Console。
- 转到当前 realm 的 Clients > Initial Access Tokens。
- 创建具有所需到期时间和最大客户端数量的令牌。
-
在 API7 中创建 DCR 提供商：
curl -k "https://localhost:7443/api/dcr_providers" \-H "X-API-KEY: ${API_KEY}" \-H "Content-Type: application/json" \-d '{"name": "Keycloak","provider_type": "oidc","issuer": "https://keycloak.example.com/realms/my-realm","headers": {"Authorization": "Bearer <keycloak-initial-access-token>"}}' -
创建启用 DCR 身份认证的 API 产品并发布。
-
开发者在开发者门户中创建 OAuth 凭证。每个凭证创建都会在 Keycloak 中注册一个新客户端。
-
开发者使用客户端 ID 和密钥向 Keycloak 请求访问令牌，然后使用令牌通过网关调用 API。
删除保护
在以下情况下，无法删除 DCR 提供商：
- 任何 API 产品在身份认证配置中引用该提供商。
- 任何开发者凭证都与其关联。
删除 DCR 提供商前，请先移除所有引用。
OIDC 发现缓存
对于 OIDC 提供商，门户会缓存 OpenID Connect 发现文档（其中包含注册端点 URL）。缓存采用 LRU 策略，TTL 为 24 小时，最多保留 128 个条目，以减少发送到身份提供商的发现请求数量。