---
title: "HTTPS 客户端元数据（CIMD）"
description: "CIMD 允许公开 OAuth 客户端用 HTTPS 元数据文档的完整 URL 作为 `client_id`，通过协议发现应用信息。它替代的是客户端预登记，不替代资源访问策略、用户同意或业务权限检查。"
url: "https://auth.kai.com/docs/cimd"
language: "zh-CN"
version: "Better Auth 1.7.1"
updated: "2026-10-19"
---

# HTTPS 客户端元数据（CIMD）

CIMD 允许公开 OAuth 客户端用 HTTPS 元数据文档的完整 URL 作为 `client_id`，通过协议发现应用信息。它替代的是客户端预登记，不替代资源访问策略、用户同意或业务权限检查。

## 先检查 Discovery

读取 `/.well-known/oauth-authorization-server`。仅当实际响应包含 `client_id_metadata_document_supported: true` 时，才能使用 CIMD；客户端还需确认 `token_endpoint_auth_methods_supported` 包含 `none`，且 `code_challenge_methods_supported` 包含 `S256`。不要仅根据文档推断某个部署已启用。

原有控制台登记的 public/confidential 客户端继续使用原有配置。CIMD 与 OAuth Dynamic Client Registration 是不同能力；不需要调用动态注册接口，也不需要请求管理员直接写数据库。

## 发布客户端元数据

在客户端运营方控制的公开 HTTPS 地址提供 JSON，例如 `https://client.example.com/oauth/client-metadata`：

```json
{
  "client_id": "https://client.example.com/oauth/client-metadata",
  "client_name": "Example Client",
  "redirect_uris": ["https://client.example.com/oauth/callback"],
  "token_endpoint_auth_method": "none",
  "grant_types": ["authorization_code", "refresh_token"],
  "response_types": ["code"],
  "client_uri": "https://client.example.com"
}
```

`client_id` 必须与文档 URL 精确一致；完整 URL 是客户端身份，不能在请求之间随意更换。回调必须是符合要求的明确 HTTPS 地址。元数据地址必须可以直接访问，不能依赖登录 Cookie、私有网络或 HTTP 重定向。Auth 会限制网络目标、响应大小、超时和缓存期限；内网地址、回环地址或跳转到其他地址的文档不能用于接入。

此入口支持公开客户端的授权码流程与 S256 PKCE，不签发共享 Client Secret，也不提供 `client_credentials` 或 Device Authorization。需要这些能力时使用控制台支持的应用登记流程。

## 请求授权与换取令牌

按[授权码与 PKCE](/docs/authorization-code)创建新的 `state`、`nonce` 和 S256 challenge。`client_id` 使用 URL 编码后的完整元数据地址；`redirect_uri` 使用元数据登记的准确回调。仅请求实际需要的 `openid`、`profile`、`email`、`offline_access`。`openid` 是必需项，其他项由用户选择，客户端必须处理未获准可选权限的情况。

令牌兑换提交同一个 `client_id`、`redirect_uri`、授权码和对应 `code_verifier`，不提交 Client Secret。需要持续登录时申请并获准 `offline_access`，按实际令牌响应处理轮换与刷新。刷新不能改变客户端、扩大 scope 或增加原授权之外的 resource。客户端元数据变化、平台关闭 CIMD、资源准入变化及用户撤销仍受服务端校验；缓存不意味着可以永久沿用旧配置。

授权页面显示应用名称与元数据来源域名，并明确标记主体未验证。HTTPS 文档可用于识别客户端，**不代表组织通过 KYB、不授予 KAI 项目归属，也不会让用户自动加入组织**。未登记的 CIMD 客户端不会获得虚构的组织或项目声明。

## 申请 API 资源

仅完成 OIDC 登录时可以省略 `resource`。要获得访问 API 的 JWT，资源所有者应在 **开发者控制台 → 组织 → 项目 → API 资源** 创建或编辑资源，配置其真实 identifier、允许 scope 和有效期，并自行开启 **允许通过 HTTPS 元数据发现的客户端（CIMD）**。

该选项默认关闭。开启后，任何符合 CIMD 要求的公开客户端都可以在用户同意后申请该资源允许的权限；它不是只允许某个示例客户端。原有登记应用的授权关系仍通过资源中的应用列表配置。资源不存在、停用、未开启 CIMD 或不允许请求的权限时，客户端应处理相应 `invalid_target` / `invalid_scope`，不能把 Auth issuer 当作备用 audience，也不能请求直接修改数据库绕过策略。

资源 JWT 的 issuer 保持 Auth 的发行者，audience 包含实际获准的资源。资源服务必须验证签名、issuer、audience、有效期及业务所需声明，并按实际用户和业务规则决定是否允许操作。CIMD 不定义某个业务产品的专用 scope，不把元数据、登录成功或 JWT 签发成功当作业务授权成功。

例如，业务工作台的账户查询、工具调用、订阅或成员权限由该业务服务控制；Auth 负责客户端识别、用户认证、用户同意和令牌生命周期。不要为单个接入方硬编码 client ID、resource 或业务权限。

## 排错与撤销

- 客户端发现失败：确认元数据 URL 可公开直达、返回有效 JSON，且 `client_id` 与 URL 相同。
- 回调被拒绝：确认请求与文档的完整 `redirect_uri` 精确匹配；不要使用通配符。
- `invalid_target`：资源所有者检查控制台登记、启用状态和 CIMD 开关，客户端检查 `resource` 是否为该 API 的准确标识符。
- `invalid_scope`：检查标准身份范围、实际用户同意以及资源允许范围；业务自定义权限不应通过扩大 Auth 范围绕过。
- 刷新失败：按公开错误码处理；撤销、轮换、元数据失效等结果不能统一当作密码错误。必要时重新发起完整授权。

保存响应中的 `requestId` 和可信 `flowId` 供诊断，不记录授权码、令牌或 PKCE verifier。CIMD 客户端没有可信项目归属时，诊断不会被强行归入某个 KAI 项目；参见[接入诊断](/docs/diagnostics)。关闭资源的 CIMD 开关会撤销受影响的授权。仅离线验证的 JWT 可能在到期前仍被接受，撤销时效与内省规则见[资源、scope 与访问令牌](/docs/resources-and-tokens)。

## 本期运行控制

平台通过独立 `CIMD_ENABLED` 开关控制发现入口，资源所有者通过控制台的 CIMD 选项控制自己的 API 是否接收发现客户端。用户可以在个人中心的已授权应用中撤销授权。

平台管理员可在 **平台管理 → 平台设置 → 发现的 OAuth 客户端** 查看已发现的客户端名称、完整元数据 URL 与状态，并在完成近期身份验证后停用或启用指定客户端。停用会阻止新登录并撤销已有授权及凭据；重新启用不会恢复旧授权。列表和操作不展示客户端秘密，状态变更记录管理审计。

全局关闭、停用单个客户端、关闭某个资源准入和用户撤销是不同控制范围；正式启用前按实际影响选择，避免影响其他已登记应用。