OAuth Client 生命周期

每个业务 App 的每个环境必须使用独立 OAuth Client。dev、staging 和 prod 的 Client ID、Client Secret 与回调地址不得复用。

创建

在 Auth 管理后台的“应用管理”中选择 App，创建对应环境的 OAuth Client，并填写至少一个精确回调地址。

创建成功后只展示一次明文 Client Secret。立即将其写入目标环境的服务端 Secret 管理，不得写入浏览器、日志、回执文件或 Git。

环境隔离

Auth API Worker 只接受与自身 ENVIRONMENT 相同的 OAuth Client：

• dev Worker 只接受 dev Client。
• staging Worker 只接受 staging Client。
• prod Worker 只接受 prod Client。

环境不匹配必须拒绝授权码创建、授权码交换和 App Session 创建。

回调地址

• 只允许精确匹配，不支持通配符。
• 必须使用业务 App 服务端回调路由。
• 生产环境必须使用 HTTPS。
• 删除时必须至少保留一个有效回调地址。

Secret 轮换

轮换后：

1. 新 Secret 只展示一次。
2. 数据库只保存新 Secret 的哈希。
3. 旧 Secret 立即失效。
4. 该 Client 的未消费授权码和活跃 App Session 立即撤销。

业务 App 应先准备新 Secret 的安全发布窗口，再执行轮换并重新登录验收。

停用与恢复

停用 Client 会阻止新授权，并立即撤销未消费授权码和活跃 App Session。恢复只允许创建新会话，不会恢复旧授权码或旧 Session。

账号、组织、组织成员、全局 App 或组织级 App 被停用，账号进入强制密码重置，以及飞书员工离职、冻结或同步为不可用时，也会在同一数据库事务中撤销受影响的授权码和 App Session。

管理 API

• GET /v1/admin/apps/{appId}/sso-clients
• POST /v1/admin/apps/{appId}/sso-clients
• POST /v1/admin/sso-clients/{clientId}/rotate-secret
• PATCH /v1/admin/sso-clients/{clientId}/disable
• PATCH /v1/admin/sso-clients/{clientId}/restore
• POST /v1/admin/sso-clients/{clientId}/redirect-uris
• DELETE /v1/admin/sso-clients/{clientId}/redirect-uris

所有生命周期操作都必须写入审计日志。