使用 Keycloak 配置动态客户端注册
动态客户端注册(DCR)是 OAuth 2.0 的一种机制,允许客户端应用程序通过程序在授权服务器上注册,无需在身份提供商(IdP)中手动配置。应用程序无需预先创建凭证,而是根据已定义的注册策略在运行时取得客户端 ID 和客户端密钥,从而实现可扩展的自动接入。
在 API7 门户中,动态客户端注册(DCR)可自动完成 OAuth 客户端的注册流程。
- 管理员向 API7 提供来自 Keycloak 的初始访问 Token,供 API7 调用 Keycloak 的注册 API。
- 开发者直接在开发者门户中添加 OAuth 客户端,无需在 Keycloak 中手动创建。
- API7 使用初始访问 Token 在 Keycloak 中动态创建 OAuth 客户端。
本指南介绍如何通过 DCR 将 API7 企业版开发者门户与身份提供商 Keycloak 集成。你将在提供者门户中发布 API,配置 Keycloak 的 DCR,然后在开发者门户中创建应用程序、订阅 API 并获取 OAuth 2.0 访问 Token,以安全地调用 API。
前置条件
- 已安装 API7 企业版 v3.9.0 或更高版本,并使用启用了门户的许可证激活。试用许可证默认启用门户。参阅安装 API7 企业版。
- 已部署并配置开发者门户。
- 已部署 Keycloak 且可以访问。本指南使用
quay.io/keycloak/keycloak:21.1.1镜像进行测试。不同 Keycloak 版本的行为可能不同。如果你使用的是其他版本,请按需调整步骤。
配置提供者门户
本节介绍如何在 API7 提供者门户中配置 DCR 提供商并创建 API 产品。
发布服务
- 按照发布第一个 API中的步骤创建服务和路由。
- 为路由添加标签,例如
portal:dcr:require_any_scopes: phone。请求访问 Token 时,请求中的scope必须匹配路由标签中设置的值。

配置 DCR 提供商
- 在 Keycloak 的 Realm(例如
master)中创建初始访问 Token。 - 在提供者门户中,打开 DCR 提供商,点击 添加 DCR 提供商。
- 填写 DCR 提供商配置。
- 名称:输入能标识此提供商的名称。
- 签发者:输入 Keycloak 签发者 URL。
- 认证请求头:将请求头名称设为
Authorization,值设为Bearer ${ACCESS_TOKEN},用 Keycloak 的初始访问 Token 替换占位符。

创建 API 产品
-
打开 API 产品,点击 添加 API 产品。选择 从 API7 网关创建。
-
配置 API 产品。
- 名称:输入能标识此 API 产品的名称。
- 认证类型:选择 DCR。
- DCR 提供商:选择之前配置的 Keycloak 提供商。
- 添加关联的网关服务:选择网关组和之前发布的服务,例如
httpbin。

配置完成后,点击 添加。
-
新创建的 API 产品默认为
draft状态,在开发者门户中不可见。要发布产品,请点击右上角的 操作,然后选择 发布。发布后,开发者门户会显示该产品。
在开发者门户中的操作
以下步骤假设你的开发者门户基于 API7 开发者门户模板。如果定制了门户,请相应调整步骤。
订阅 API 产品
以 API 开发者身份执行以下操作。
- 注册新用户并创建组织。
- 使用开发者账户登录开发者门户。
- 打开 我的应用,点击 添加应用 以创建应用程序。
- 在顶部导航栏选择 API 中心。
- 选择 API 产品,例如
httpbin。查看 API 详情,确认它符合你的需求。 - 点击 订阅,再点击 订阅到应用,选择之前创建的应用程序。
- 等待订阅申请获批。
审批订阅申请
只有在创建 API 产品时禁用了 订阅自动审批,才需要执行审批。如果开发者订阅已自动获批,请跳过本节。
以 API 提供者身份执行以下操作。
- 在提供者门户的顶部导航栏选择 组织,点击 审批。
- 找到相应的申请,点击 接受。
创建应用程序和 OAuth 客户端
以 API 开发者身份执行以下操作。
- 打开 我的应用,选择之前创建的应用程序。
- 在 认证类型 选项卡中,点击 OAuth。
- 点击 添加 OAuth 客户端,创建新的 OAuth 客户端。
- 填写 OAuth 客户端配置。
- 身份提供商:选择 Keycloak 作为 OAuth 提供商。
- 重定向 URI:输入回调 URL。DCR 会自动在 Keycloak 客户端中配置这些重定向 URI。
- 复制 客户端 ID 和 客户端密钥,供后续验证使用。
在开发者门户中创建的每个 OAuth 客户端都对应 Keycloak 中的一个客户端。一个应用程序可以包含多个 OAuth 客户端,每个 OAuth 客户端都对应各自的 Keycloak 客户端。
验证 API 访问
以 API 开发者身份执行以下操作。
-
请求访问 Token。此处请求的
scope必须与路由标签中设置的值一致,本例为phone,否则验证会失败。# Define variablesexport KEYCLOAK_HOST="your_keycloak_host"export ADMIN_USERNAME="your_admin_username"export ADMIN_PASSWORD="your_admin_password"export CLIENT_ID="your_client_id"export CLIENT_SECRET="your_client_secret"export DP_HOST="your_dp_host"export KEYCLOAK_REALM="your_realm"# 请求访问 Tokenexport ACCESS_TOKEN="$(curl --location --request POST "http://${KEYCLOAK_HOST}:8080/realms/${KEYCLOAK_REALM}/protocol/openid-connect/token" \--header 'Content-Type: application/x-www-form-urlencoded' \--data-urlencode 'grant_type=password' \--data-urlencode "client_id=${CLIENT_ID}" \--data-urlencode "client_secret=${CLIENT_SECRET}" \--data-urlencode "username=${ADMIN_USERNAME}" \--data-urlencode "password=${ADMIN_PASSWORD}" \--data-urlencode 'scope=phone' | jq -r '.access_token')" -
使用获取的访问 Token 调用 API。
# 替换为你的网关地址curl "http://127.0.0.1:9080/ip" -H "Host: httpbin.org" -H "Authorization: Bearer $ACCESS_TOKEN"你应看到以下响应。
{"origin": "127.0.0.1"}