跳到主要内容
版本:3.9.x

使用 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。

前置条件​

  1. 已安装 API7 企业版 v3.9.0 或更高版本,并使用启用了门户的许可证激活。试用许可证默认启用门户。参阅安装 API7 企业版。
  2. 已部署并配置开发者门户。
  3. 已部署 Keycloak 且可以访问。本指南使用 quay.io/keycloak/keycloak:21.1.1 镜像进行测试。不同 Keycloak 版本的行为可能不同。如果你使用的是其他版本,请按需调整步骤。

配置提供者门户​

本节介绍如何在 API7 提供者门户中配置 DCR 提供商并创建 API 产品。

发布服务​

  1. 按照发布第一个 API中的步骤创建服务和路由。
  2. 为路由添加标签,例如 portal:dcr:require_any_scopes: phone。请求访问 Token 时,请求中的 scope 必须匹配路由标签中设置的值。

为路由添加标签

配置 DCR 提供商​

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

添加 DCR 提供方

创建 API 产品​

  1. 打开 API 产品,点击 添加 API 产品。选择 从 API7 网关创建。

  2. 配置 API 产品。

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

    添加 API 产品

    配置完成后,点击 添加。

  3. 新创建的 API 产品默认为 draft 状态,在开发者门户中不可见。要发布产品,请点击右上角的 操作,然后选择 发布。发布后,开发者门户会显示该产品。

    发布 API 产品

在开发者门户中的操作​

以下步骤假设你的开发者门户基于 API7 开发者门户模板。如果定制了门户,请相应调整步骤。

订阅 API 产品​

以 API 开发者身份执行以下操作。

  1. 注册新用户并创建组织。
  2. 使用开发者账户登录开发者门户。
  3. 打开 我的应用,点击 添加应用 以创建应用程序。
  4. 在顶部导航栏选择 API 中心。
  5. 选择 API 产品,例如 httpbin。查看 API 详情,确认它符合你的需求。
  6. 点击 订阅,再点击 订阅到应用,选择之前创建的应用程序。
  7. 等待订阅申请获批。

审批订阅申请​

只有在创建 API 产品时禁用了 订阅自动审批,才需要执行审批。如果开发者订阅已自动获批,请跳过本节。

以 API 提供者身份执行以下操作。

  1. 在提供者门户的顶部导航栏选择 组织,点击 审批。
  2. 找到相应的申请,点击 接受。

创建应用程序和 OAuth 客户端​

以 API 开发者身份执行以下操作。

  1. 打开 我的应用,选择之前创建的应用程序。
  2. 在 认证类型 选项卡中,点击 OAuth。
  3. 点击 添加 OAuth 客户端,创建新的 OAuth 客户端。
  4. 填写 OAuth 客户端配置。
    • 身份提供商:选择 Keycloak 作为 OAuth 提供商。
    • 重定向 URI:输入回调 URL。DCR 会自动在 Keycloak 客户端中配置这些重定向 URI。
  5. 复制 客户端 ID 和 客户端密钥,供后续验证使用。
信息

在开发者门户中创建的每个 OAuth 客户端都对应 Keycloak 中的一个客户端。一个应用程序可以包含多个 OAuth 客户端,每个 OAuth 客户端都对应各自的 Keycloak 客户端。

验证 API 访问​

以 API 开发者身份执行以下操作。

  1. 请求访问 Token。此处请求的 scope 必须与路由标签中设置的值一致,本例为 phone,否则验证会失败。

    # Define variables
    export 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"

    # 请求访问 Token
    export 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')"
  2. 使用获取的访问 Token 调用 API。

    # 替换为你的网关地址
    curl "http://127.0.0.1:9080/ip" -H "Host: httpbin.org" -H "Authorization: Bearer $ACCESS_TOKEN"

    你应看到以下响应。

    {
    "origin": "127.0.0.1"
    }