跳到主要内容
版本：3.10.x

使用 Keycloak 配置动态客户端注册（DCR）

动态客户端注册（Dynamic Client Registration, DCR）是一种 OAuth 2.0 机制，允许客户端应用程序以编程方式向授权服务器进行注册，而无需在身份提供商（IdP）中进行手动配置。应用程序无需预先创建凭证，而是在运行时根据定义的注册策略接收 Client ID 和 Client Secret，从而实现可扩展的自动化接入。

在 API7 门户中，动态客户端注册（DCR）可以自动执行 OAuth 客户端注册流程：

  • 管理员向 API7 提供来自 Keycloak 的初始 Access Token，该 Token 允许 API7 调用 Keycloak 的注册 API。
  • 开发者直接在开发者门户中添加 OAuth 客户端，无需在 Keycloak 中手动创建客户端。
  • API7 使用初始 Access Token 在 Keycloak 中动态创建 OAuth 客户端。

本指南将介绍如何使用 DCR 将 API7 企业版开发者门户与 Keycloak（作为身份提供商 IdP）集成。你将在提供方门户中发布 API，为 DCR 配置 Keycloak，然后使用开发者门户创建应用程序、订阅 API 并获取 OAuth 2.0 Access 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. 为路由添加标签（Label），例如 portal:dcr:require_any_scopes: phone。请求 Access Token 时，请求中指定的 scope 必须与路由标签中设置的值匹配。

Add a label for the route

配置 DCR 提供方​

  1. 在你的 Keycloak 领域（Realm，例如 master）中，创建一个 初始 Access Token。
  2. 在提供方门户中，导航到 DCR 提供方（DCR Providers） 并点击 添加 DCR 提供方（Add DCR Provider）。
  3. 填写 DCR 提供方详情：
    • 名称（Name）：输入提供方的描述性名称。
    • Issuer：输入 Keycloak Issuer URL。
    • Auth Headers：输入 Authorization 作为 Header 名称，值为 Bearer ${ACCESS_TOKEN}。请将你的 Keycloak 初始 Access Token 替换进去。

Add DCR provider

创建 API 产品​

  1. 导航到 API 产品（API Products） 并点击 添加 API 产品（Add API Product）。选择 从 API7 网关（From API7 Gateway） 创建产品。

  2. 配置 API 产品：

    • 名称（Name）：输入 API 产品的描述性名称。
    • 身份验证类型（Authentication Type）：选择 DCR。
    • DCR 提供方（DCR Provider）：选择先前配置的 Keycloak 提供方。
    • 添加关联的网关服务（Add Linked Gateway Service）：选择网关组和先前发布的服务（例如 httpbin）。

    Add API Product

    配置完成后，点击 添加（Add）。

  3. 新创建的 API 产品默认处于 草稿（draft） 状态，在开发者门户中不可见。若要发布产品，请点击右上角的 操作（Actions），然后选择 发布（Publish），使 API 产品在开发者门户中可见。

    Publish Product

开发者门户操作​

以下说明假定你的开发者门户是基于 API7 开发者门户脚手架构建的。如果你的开发者门户已进行自定义，请相应调整步骤。

订阅 API 产品​

作为 API 开发者：

  1. 注册一个新用户和组织。
  2. 使用开发者账户登录到开发者门户。
  3. 导航到 My Applications 并点击 Add Application 以创建应用程序。
  4. 从顶部导航栏选择 API Hub。
  5. 选择一个 API 产品（例如 httpbin）。浏览 API 详情以确保其满足你的需求。
  6. 点击 Subscriptions，然后点击 Subscribe to Application，并选择先前创建的应用程序。
  7. 等待订阅请求获得批准。

批准订阅请求​

仅当在创建 API 产品时禁用了 订阅自动批准（Subscription Auto Approval） 才需要批准。如果开发者的订阅会自动批准，请跳过此部分。

作为 API 提供方：

  1. 在提供方门户中，从顶部导航栏选择 组织（Organization），然后点击 审批（Approvals）。
  2. 找到对应的请求并点击 接受（Accept）。

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

作为 API 开发者：

  1. 导航到 My Applications 并选择之前创建的应用程序。
  2. 转到 Authentication Type 选项卡并点击 OAuth。
  3. 点击 Add OAuth Client 以创建新的 OAuth 客户端。
  4. 填写 OAuth 客户端详情：
    • Identity Provider：选择 Keycloak 作为 OAuth 提供商。
    • Redirect URIs：输入回调 URL。这些重定向 URI 将通过 DCR 自动配置在 Keycloak 客户端中。
  5. 复制 Client ID 和 Client Secret 以供后续验证。
信息

在开发者门户中创建的每个 OAuth 客户端映射到 Keycloak 中的单个客户端。一个应用程序可以包含多个 OAuth 客户端，每个客户端都有其对应的 Keycloak 客户端。

验证 API 访问​

作为 API 开发者：

  1. 请求 Access 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"

    # Request the access 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. 使用获取的 Access Token 调用 API：

    # Update with your gateway address
    curl "http://127.0.0.1:9080/ip" -H "Host: httpbin.org" -H "Authorization: Bearer $ACCESS_TOKEN"

    你应该会看到以下响应：

    {
      "origin": "127.0.0.1"
    }