---
title: 动态注册 API
description: 使用 IAT 注册 OIDC 客户端、读取元数据和移除注册。
editUrl: true
head: []
template: doc
sidebar:
  order: 2
  hidden: false
  attrs: {}
pagefind: true
draft: false
---

当 RP 需要在组织批准的权限下创建客户端时，可以使用动态注册。先获取 [Initial Access Token（IAT）](/zh-cn/oidc/registration-access/)，再从 discovery 读取 `registration_endpoint`。

## 注册授权码客户端

以下示例使用 `client_secret_basic`。IAT 必须允许 `code`、`authorization_code`、`refresh_token` 和所有请求的 scope。回调主机必须已获批准，归属组织的 Sector。

将以下内容保存为 `registration.json`：

```json
{
  "client_name": "Example RP",
  "redirect_uris": ["https://app.example.com/oidc/callback"],
  "post_logout_redirect_uris": ["https://app.example.com/"],
  "response_types": ["code"],
  "grant_types": ["authorization_code", "refresh_token"],
  "application_type": "web",
  "scope": "openid email profile offline_access",
  "token_endpoint_auth_method": "client_secret_basic",
  "subject_type": "pairwise",
  "id_token_signed_response_alg": "RS256"
}
```

从后端发送 JSON，并携带 Bearer IAT：

```bash
curl -X POST "$REGISTRATION_ENDPOINT" \
  -H "Authorization: Bearer $IAT" \
  -H "Content-Type: application/json" \
  --data-binary @registration.json
```

成功返回 HTTP 201。以下节选展示需要保存的凭据和元数据；响应还包含其他当前注册元数据。

```json
{
  "client_id": "example-rp",
  "registration_client_uri": "https://oidc.sudomimus.com/register/example-rp",
  "registration_access_token": "<RAT>",
  "client_secret": "<client secret>",
  "client_secret_expires_at": 0,
  "redirect_uris": ["https://app.example.com/oidc/callback"],
  "response_types": ["code"],
  "grant_types": ["authorization_code", "refresh_token"],
  "application_type": "web",
  "scope": "openid email profile offline_access",
  "token_endpoint_auth_method": "client_secret_basic"
}
```

将 RAT 和客户端密钥保存为后端机密。`client_secret_expires_at` 为 `0` 表示没有预定到期时间；轮换或撤销仍可使密钥失效。授权请求使用返回的 `client_id`。注册会消耗一个 IAT 配额，并按所选模板创建已启用的应用。

## 元数据规则

| 字段 | 规则 |
|---|---|
| `redirect_uris` | 必填的非空数组。授权时精确匹配 URI。 |
| `response_types` | 默认 `["code"]`。每种请求的类型都必须在 IAT 允许范围内。 |
| `grant_types` | 默认 `["authorization_code"]`。含授权码的类型要求 `authorization_code`；其他响应类型还要求 `implicit`。 |
| `scope` | 以空格分隔，必须在 IAT 允许范围内。省略时，使用与 grant 兼容的允许 scope。必须包含 `openid`；`offline_access` 要求 `refresh_token`。 |
| `application_type` | 默认 `web`。native 客户端使用自定义 scheme 或精确的 HTTP 回环 URI，不接受 HTTPS。web Implicit/Hybrid 必须使用 HTTPS，且不能使用 localhost 或回环主机。 |
| `token_endpoint_auth_method` | 默认 `client_secret_basic`。还支持 `client_secret_post`、`private_key_jwt` 和 `none`。含授权码的公开客户端必须使用 PKCE S256。 |
| `jwks` / `jwks_uri` | 选择一种 RP 公钥来源。动态注册使用 `private_key_jwt` 时必填。见 [RP 密钥](/zh-cn/oidc/relying-party-keys/)。 |
| `sector_identifier_uri` | 多个回调主机要求 HTTPS JSON 数组，包含每个精确回调 URI。文档主机必须已获批准，归属组织的 Sector。 |
| `post_logout_redirect_uris` | 已注册的精确退出回调地址。 |
| `initiate_login_uri` | 可选的 HTTPS RP 端点，不含 fragment，用于第三方发起登录。 |
| 签名偏好 | 适用时，`id_token_signed_response_alg`、`userinfo_signed_response_alg`、`token_endpoint_auth_signing_alg` 和 `request_object_signing_alg` 支持 RS256。不支持加密。 |
| 认证偏好 | `default_max_age`、`require_auth_time`、`default_acr_values` 和 `request_uris`。见 [OIDC 高级接入](/zh-cn/oidc/advanced/)。 |
| 展示信息 | `client_name`、`client_uri`、`policy_uri`、`tos_uri`、`logo_uri`、带语言标签的对应字段，以及 `contacts`。名称须符合命名策略，链接使用 HTTPS。 |

注册 JSON 上限为 65,536 字节。列表最多 32 项；公钥 JWKS 最多 16 把密钥。Logo 必须是 PNG、JPEG、GIF 或 WebP，每张不超过 64 KiB。不要提交 JWK 私钥字段。

## 读取注册

使用返回的 `registration_client_uri` 和该客户端的 RAT：

```bash
curl "$REGISTRATION_CLIENT_URI" \
  -H "Authorization: Bearer $RAT"
```

成功返回 HTTP 200，包含当前元数据；共享密钥客户端还会收到当前客户端密钥。响应不会返回替换 RAT。读取经过审计，响应不得缓存。

RAT 不允许更新元数据。规则和 RP 公钥应通过 With 修改。不支持 `PUT` 注册更新。要修改已启用客户端的 `initiate_login_uri`，请联系 Sudomimus 支持。

## 移除注册

```bash
curl -X DELETE "$REGISTRATION_CLIENT_URI" \
  -H "Authorization: Bearer $RAT"
```

成功返回 HTTP 204，无响应体。此操作停用动态注册的应用、移除 OIDC 注册并撤销 RAT。应用作为管理资源保留。移除后，客户端不能再授权、兑换令牌或读取该注册。

## 处理失败

元数据错误返回 HTTP 400，错误为 `invalid_client_metadata` 或 `invalid_redirect_uri`。IAT 不可用时返回 HTTP 401 和 `invalid_token`。读取或删除注册时，使用另一客户端的有效 RAT 会返回 HTTP 403。见 [OIDC 排错](/zh-cn/oidc/troubleshooting/)。

重复调用 `POST /register` 可能创建另一个客户端并再次消耗配额。如果网络失败导致结果未知，请让 OWNER 在 With 检查注册结果，再决定是否重新提交。

## 相关文档

- [IAT 与 RAT 管理](/zh-cn/oidc/registration-access/)
- [组织应用模板](/zh-cn/with-portal/application-templates/)
- [OIDC 流程](/zh-cn/oidc/flow/)