---
url: /zh/oauth/developer.md
---
本文旨在为第三方开发者提供标准化的 OAuth 2.0 应用接入流程，支持应用的登记上架、用户授权（个人/资源级）、临时票据发放及 API 访问控制。

## 准备工作 - 申请注册 OAuth 应用

### 应用信息登记

当前需要 CNB 运营管理员审核后上架应用。请将申请信息提交给管理员，我们会与您沟通详细的 OAuth 应用创建方案。

### 应用基本信息

| 应用信息     | 是否必须 | 字段说明 |
| :--------   | ---- |  :----- |
| 应用名称   | 必须  |在授权时与用户授权管理页给用户展示，不超过 50 字 |
| 应用 Logo  | 必须  | 图片大小不超过 1MB |
| 应用简介   | 非必须 | 不超过 350 字 |
| 应用官网   | 必须  | 最多 128 字符 |
| 回调地址   | 必须  | Redirect URI，用于 OAuth 授权后跳转  |
| 支持的授权范围   | 必须  | 在应用创建方案中沟通，如 `repo-code:r`、`account-profile:r` 等，需预定义。应用仅申请必要的权限范围，CNB 平台审核时将评估授权范围合理性。 |
| 授权资源范围   | 必须  | 当前账号所有权限/当前账号所有公开资源/指定资源  |

## 授权流程

应用程序内用户的授权流程是：

1. 用户在应用程序内发起授权请求；
2. 引导用户跳转至 CNB 的授权页面，携带对应参数，以请求他们的 CNB 身份；
3. 用户同意后，CNB 生成授权码；
4. 用户被 CNB 重定向回您的站点；
5. 应用程序使用用户的访问令牌访问 CNB API

### 1. 获取用户授权

在第三方应用内操作，发起授权请求。引导用户跳转至平台的授权页面，携带参数：

* `client_id`：应用唯一标识（上架后分配）
* `redirect_uri`：回调地址（需与登记信息一致）
* `response_type`：固定为`code`（授权码模式）
* `scope`：申请的权限范围（如`repo-code:r、account-profile:r`等）
* `target`：指定授权范围，`a/b` 表示指定a/b资源
* `state`：防 CSRF 令牌（由应用生成，回调时原样返回）

### 2. 展示与确认授权

#### 授权页

用户跳转至平台的授权页面，显示以下信息：

* 应用基本信息（名称、Logo、开发者、官网）
* 申请的权限详情（按作用域拆解，例如：
  * 个人权限：查看您的昵称、头像（`account-profile:r`）
  * 资源权限：读取仓库的代码（`repo-code:r`）
* 目标资源（若申请资源级权限，列出具体资源列表供用户选择/确认）

### 3. 用户确认授权

用户同意后，平台生成授权码（Authorization Code），并通过`redirect_uri`回调至第三方App，附带参数：

* `code`：临时授权码（有效期5分钟）
* `state`：原样返回用户提交的防CSRF令牌

### 4. 第三方App换取访问凭证

第三方App使用code向平台的Token端点发起请求，换取临时票据（Access Token）：

* 请求参数：
  * `grant_type`：固定为`authorization_code`
  * `code`：授权码
  * `redirect_uri`：与申请时一致的回调地址
  * `client_id` & `client_secret`：应用的唯一标识与密钥（由平台分配，需保密）
* 平台验证通过后，返回：
  * `access_token`：临时票据（有效期2小时，用于调用API）
  * `token_type`：固定为`Bearer`
  * `expires_in`：有效期（秒）
  * `refresh_token`（可选）：刷新令牌（用于延长会话，有效期7天）
  * `scope`：实际授予的权限范围

## 可授权范围

| 可操作权限     | 权限类型 | 说明 |
| :--------   | ---- |  :----- |
| repo-code   | 只读/读写  |通过 Git 命令访问代码仓库|
| repo-pr  | 只读/读写  |访问合并请求|
| repo-issue  | 只读/读写  |访问 ISSUE |
| repo-notes |  只读/读写 | 访问提交记录、ISSUE 及合并请求中的评论|
| repo-contents | 只读/读写|访问文件、分支、提交记录、标签、版本|
| repo-commit-status | 只读/读写 |访问流水线执行状态、徽章、commit 元数据|
| repo-cnb-trigger | 只读/读写 |查询、删除、触发、执行云原生构建，启动云原生开发|
| repo-cnb-history | 只读 |查询流水线构建历史|
| repo-cnb-detail | 只读/读写 |查询或删除云原生开发空间|
| repo-basic-info | 只读 |访问仓库基础信息，如：仓库名称、描述、语言、license 等|
| repo-cnb-detail | 只读/读写 |查询或删除云原生开发空间|
| repo-cnb-detail | 只读/读写 |查询或删除云原生开发空间|
| repo-manage | 只读/读写 |访问仓库成员、仓库设置|
| repo-delete | 读写 |删除仓库|
| repo-security | 只读 |访问仓库安全模块数据|
| registry-package | 只读/读写 |访问制品|
| registry-package-delete | 读写 |删除制品|
| registry-manage | 只读/读写 |访问制品库成员、制品库设置|
| registry-delete | 读写 |删除制品库|
| account-profile | 只读/读写 |访问用户个人资料|
| account-email | 只读/读写 |查询用户认证邮箱|
| account-engage | 只读/读写 |访问用户关注的仓库、关注者、粉丝、云原生开发环境等|
| group-resource | 只读/读写 |访问子组织、仓库|
| group-manage | 只读/读写 |访问组织成员、仓库墙、组织设置|
| group-delete | 只读/读写 |删除组织|
| mission-delete | 只读/读写 |删除任务集|
| mission-manage | 只读/读写 |访问任务集|
