应用数据结构

本文档描述 Code Bird Cloud 中应用的类型定义、OIDC 客户端元数据字段以及 Client Secret 管理方式。在创建或配置应用时，请参考以下内容。

应用类型

Code Bird Cloud 支持四种应用类型，对应不同的 OAuth 2.1 使用场景：

类型	说明	典型场景	是否需要 Client Secret
Traditional	传统 Web 应用	具有服务端的 Web 应用，可安全存储 Client Secret	是
SPA	单页应用	前端渲染的单页应用（如 React、Vue），无法安全存储 Secret，使用 PKCE 流程	否
Native	原生应用	移动端或桌面端原生应用（iOS、Android、Electron 等）	否
MachineToMachine	机器对机器	服务间通信，无用户交互，使用 Client Credentials 授权	是

应用类型在创建时选定，创建后不可更改。请根据你的应用场景选择正确的类型。

各类型对应的授权流程

应用类型	推荐授权流程	参考文档
Traditional	Authorization Code Flow	传统 Web 应用集成
SPA	Authorization Code + PKCE	SPA 单页应用集成
Native	Authorization Code + PKCE	原生应用集成（待开发）
MachineToMachine	Client Credentials	M2M 认证指南

OIDC 客户端元数据

以下是应用的标准 OIDC 客户端元数据字段：

字段	类型	说明
redirect_uris	string[]	OAuth 重定向 URI 列表。用户认证成功后，Code Bird Cloud 会将用户重定向到这些地址之一。必须与授权请求中的 redirect_uri 完全匹配
post_logout_redirect_uris	string[]	登出后重定向 URI 列表。用户登出后的跳转地址
cors_allowed_origins	string[]	CORS 允许的源列表。SPA 应用需要配置此字段以允许跨域请求
grant_types	string[]	授权类型。可选值：authorization_code、refresh_token、client_credentials
response_types	string[]	响应类型。通常为 code（授权码流程）
token_endpoint_auth_method	string	令牌端点认证方式。可选值：client_secret_basic、client_secret_post、none
logo_uri	string	应用 Logo URL，用于在登录页面展示

各应用类型的默认配置

字段	Traditional	SPA	Native	MachineToMachine
grant_types	authorization_code, refresh_token	authorization_code, refresh_token	authorization_code, refresh_token	client_credentials
response_types	code	code	code	--
token_endpoint_auth_method	client_secret_basic	none	none	client_secret_basic

自定义客户端元数据

除了标准 OIDC 字段外，Code Bird Cloud 还提供以下自定义元数据字段：

字段	类型	说明
always_issue_refresh_token	boolean	是否始终发放 Refresh Token。默认情况下，只有当 scope 包含 offline_access 时才会发放
rotate_refresh_token	boolean	是否在刷新时轮换 Refresh Token。启用后，每次使用 Refresh Token 获取新令牌时，旧的 Refresh Token 会失效
refresh_token_ttl_in_days	number	Refresh Token 有效期，单位为天
access_token_ttl_in_seconds	number	Access Token 有效期，单位为秒
id_token_ttl	number	ID Token 有效期，单位为秒

配置示例

{
  "name": "My Web App",
  "type": "Traditional",
  "oidc_client_metadata": {
    "redirect_uris": ["https://app.example.com/callback"],
    "post_logout_redirect_uris": ["https://app.example.com"],
    "grant_types": ["authorization_code", "refresh_token"]
  },
  "custom_client_metadata": {
    "access_token_ttl_in_seconds": 3600,
    "refresh_token_ttl_in_days": 14,
    "always_issue_refresh_token": true,
    "rotate_refresh_token": true
  }
}

Client ID 和 Client Secret

Client ID

Client ID 是应用的唯一标识符，由系统在创建应用时自动生成。Client ID 是公开信息，可以安全地嵌入在前端代码中。

Client Secret

Client Secret 是应用的密钥，仅在创建时完整展示。请在创建后立即妥善保存。

安全要求：

• 绝不能将 Client Secret 硬编码在源代码中
• 绝不能提交到版本控制系统
• 使用环境变量或密钥管理服务（如 HashiCorp Vault、AWS Secrets Manager）存储
• SPA 和 Native 类型的应用不需要 Client Secret（使用 PKCE 替代）

Secret 轮换

当 Client Secret 可能泄露或需要定期更换时，可以在管理后台执行密钥轮换操作。

API 调用：

POST /api/v1/applications/:id/secret

响应示例：

{
  "client_id": "app_xxxxxxxxxxxx",
  "client_secret": "new_secret_xxxxxxxxxx"
}

注意： 轮换密钥后，旧的 Client Secret 将立即失效。请在执行轮换前，确保所有使用该应用凭证的服务已准备好切换到新的 Secret。

推荐的轮换流程

1. 在管理后台或通过 API 生成新的 Client Secret
2. 更新所有使用该应用的服务配置
3. 验证所有服务正常工作
4. 旧 Secret 在轮换时即已失效，无需额外操作

相关文档

• 集成概览 -- 所有集成方式的总览
• 传统 Web 应用集成 -- Traditional 类型应用的集成指南
• SPA 单页应用集成 -- SPA 类型应用的集成指南
• M2M 认证指南 -- MachineToMachine 类型应用的集成指南