动态客户端注册（DCR）¶

什么是动态客户端注册？ ¶

通常情况下，每一个与您的 Authany 项目通信的应用都是由管理员在管理台中创建的。动态客户端注册（DCR，RFC 7591）省去了这一手动步骤：启用后，您的项目会在 /oauth2/register 暴露一个注册端点，客户端可以在运行时通过发送自己的元数据来完成自我注册。

以这种方式注册的客户端都是公共客户端（public client）：它们使用带 PKCE 的授权码流程对用户进行身份验证，并且永远不会获得客户端密钥。

何时使用 DCR ¶

MCP 服务器与 AI 代理： MCP 授权规范要求授权服务器支持 DCR：每个用户的 MCP 客户端（AI 助手、IDE 代理）会在首次使用时向您的项目自行注册，无需管理员逐一介入。这是启用 DCR 的主要原因；完整流程请参阅MCP 身份验证。
第三方开发者生态： 允许基于您的 API 构建集成的合作伙伴和外部开发者注册自己的 OAuth 客户端。您只需给每位开发者一个初始访问令牌，而不必替他们创建客户端；他们的用户在授权前会看到授权同意页。
临时和自动化环境： CI 流水线可以为每次预览部署注册一个短生命周期的客户端，让每个环境都拥有自己的客户端 ID，而无需任何人操作管理台。

不适合使用 DCR 的情况： 如果是您自己固定的一组应用，仍按惯例在管理台的应用页面创建；如果是使用自己凭据调用您 API 的后端服务，请使用机器对机器（M2M）应用。

关键概念 ¶

注册端点： https://<your-project>.authgear.cloud/oauth2/register。启用 DCR 后，该端点也会在您项目的 OpenID Connect 发现文档中以 registration_endpoint 的形式公布。
初始访问令牌（IAT）： 默认情况下，调用方必须携带有效的 IAT 作为 Bearer 令牌才能完成注册。您可以在管理台中创建 IAT，并通过控制谁持有令牌来控制谁可以注册。
令牌类型（第三方 vs 第一方）： 第三方 IAT 注册的客户端会向用户展示授权同意页，可以放心交给外部开发者。第一方 IAT 注册的客户端会跳过授权同意页，应像对待 Admin API 密钥一样谨慎处理。
开放注册： 关闭 IAT 要求后，任何人都可以向您的项目注册客户端。这正是 MCP 流程所期望的方式。

在管理台中启用 DCR ¶

1. 开启注册¶

在管理台中进入应用，打开 动态客户端（DCR） 标签页。开启 启用动态客户端注册，然后点击保存。该标签页随后会显示您项目的注册端点。

2. 决定如何保护注册¶

在 注册安全性 下，要求初始访问令牌 开关默认是开启的：

保持开启状态，点击 创建令牌 生成一个 IAT。选择令牌类型（第三方 或 第一方）和有效期。令牌值只会显示一次，同时会附带一个可直接运行的示例请求；请复制该令牌并妥善保存。
或者关闭该要求以允许 开放注册（例如用于 MCP）。由于此后任何人都能向您的项目注册客户端，管理台会要求您先进行确认。

注意

第一方初始访问令牌注册的客户端会跳过授权同意页。请仅将其用于您完全掌控的自动化场景，并像保护 Admin API 私钥一样保护它。

3. 可选：默认客户端配置¶

默认客户端配置 卡片用于设置应用到每个动态注册客户端的令牌有效期（访问令牌、刷新令牌、刷新令牌空闲超时），以便在这些客户端需要比您自己的应用更严格的设置时使用。

4. 授予对您 API 的访问权限¶

动态 第三方 客户端只能调用您明确向其开放的 API 资源：

在某个 API 资源的详情页（API 资源 部分），开启 允许动态第三方客户端。
在该资源的每个权限范围上，勾选 允许动态第三方客户端请求此权限范围。

所有动态第三方客户端共享这一访问权限；您的第一方客户端不受影响。

注册客户端 ¶

使用初始访问令牌开放注册

curl https://<your-project>.authgear.cloud/oauth2/register \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <your-initial-access-token>' \
  -d '{
    "client_name": "My integration",
    "redirect_uris": ["https://myintegration.example.com/callback"],
    "application_type": "web"
  }'

curl https://<your-project>.authgear.cloud/oauth2/register \
  -H 'Content-Type: application/json' \
  -d '{
    "redirect_uris": ["https://mcp-client.example.com/callback"]
  }'

注册成功会返回 201 Created，并附带新客户端的元数据：

{
  "client_id": "dcrc_AbCdEfGhIjKlMnOpQr",
  "client_id_issued_at": 1700000000,
  "client_name": "My integration",
  "redirect_uris": ["https://myintegration.example.com/callback"],
  "grant_types": ["authorization_code", "refresh_token"],
  "response_types": ["code"],
  "application_type": "web"
}

需要注意的规则：

application_type 的取值为 web（默认）或 native。web 客户端的重定向 URI 必须使用 https；native 客户端可以使用自定义 scheme（例如 myapp://callback）或 http://localhost。
系统永远不会签发客户端密钥：token_endpoint_auth_method 始终为 none，任何要求其他取值的请求都会被拒绝。
客户端是第一方还是第三方，由用于注册它的 IAT 决定；开放注册始终会注册为第三方客户端。

使用已注册的客户端 ¶

随后客户端会执行标准的带 PKCE 授权码流程，并通过 resource 参数指定要调用的 API：

GET /oauth2/authorize
  ?client_id=dcrc_AbCdEfGhIjKlMnOpQr
  &response_type=code
  &scope=openid+read:tools
  &redirect_uri=https://mcp-client.example.com/callback
  &code_challenge=<challenge>
  &code_challenge_method=S256
  &resource=https://mcp-server.example.com

用户完成登录；对于第三方客户端，还需要在授权同意页批准所请求的作用域。客户端随后在 /oauth2/token 处兑换授权码（需带上相同的 code_verifier、redirect_uri 和 resource），签发的访问令牌会在其 aud 声明中携带该资源 URI，供您的 API 验证。

管理已注册的客户端 ¶

动态客户端（DCR） 标签页会显示已注册的客户端数量；点击 查看全部 可打开完整列表，您可以在其中查看每个客户端的元数据并删除它。
客户端数量上限： 您的套餐可能会限制动态客户端的数量。一旦达到上限，后续注册都会返回 403 access_denied 失败，直到管理员删除部分客户端为止。
删除客户端 会立即阻止新的授权；已经签发的访问令牌和刷新令牌会继续有效，直到过期为止。
吊销 IAT 会阻止它注册新客户端；已经用它注册过的客户端不受影响。
之后禁用 DCR 只会关闭注册端点；已注册的客户端仍会正常工作。如果想收回它们的访问权限，需要将其删除。