CNB 文档

简体中文

English

简体中文

English

外观

创建 OAuth 应用

复制页面

2151 字约 7 分钟

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

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

应用信息登记

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

应用基本信息

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

授权流程

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

  1. 用户在应用程序内发起 CNB 授权请求；
  2. 引导用户跳转至 CNB 的授权页面，携带对应参数，以请求他们的 CNB 身份；
  3. 用户同意后，，CNB 会拉起应用或重定向到第三方网站，并且带上授权临时票据 code 参数；
  4. 通过 code 参数加上 ClientID 和 ClientSecret 等，通过 API 换取 access_token;
  5. 通过 access_token 进行接口调用，获取用户基本数据资源或帮助用户实现基本操作。

1. 发起授权请求

第三方使用网站应用授权登录可以通过在浏览器打开以下链接：

https://cnb.cool/oauth2/auth?client_id=CLIENTID&redirect_uri=REDIRECT_URI&response_type=code&state=STATE

若提示"该链接无法访问"，请检查参数是否填写错误，如 redirect_uri 的域名与审核时填写的授权域名不一致。


下面是上面这些步骤所需要的参数:
  • response_type：表示授权类型，必选项，此处的值固定为code。
  • client_id：表示客户端的 ID，必选项。
  • redirect_uri：表示重定向 URI，可选项。
  • state：表示客户端的当前状态，可以指定任意值，认证服务器会原封不动地返回这个值.

举例如下： 
    GET /oauth2/auth?response_type=code&client_id=s6BhdRkqt3&state=xyz
    &redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb HTTP/1.1
    Host: cnb.cool

服务器回应客户端的URI，包含以下参数：
  • code：表示授权码，必选项。该码的有效期应该很短，通常设为 10 分钟，客户端只能使用该码一次，否则会被授权服务器拒绝。该码与客户端 ID 和重定向 URI ，是一一对应关系。
  • state：如果客户端的请求中包含这个参数，认证服务器的回应也必须一模一样包含这个参数。

用户允许授权后，将会重定向到redirect_uri的网址上，并且带上code和state参数。举例如下

HTTP/1.1 302 Found
Location: https://client.example.com/cb?code=SplxlOBeZQQYbYS6WxSbIA&state=xyz

2. 通过 code 获取 access_token

客户端向认证服务器申请令牌的 HTTP 请求，包含以下参数：

  • grant_type：表示使用的授权模式，必选项，此处的值固定为authorization_code。
  • code：表示上一步获得的授权码，必选项。
  • redirect_uri：表示重定向URI，可选项，必须与第一步请求 code 中的该参数值保持一致。

client_id/client_secret 还可以通过 HTTP 基本认证（ HTTP Basic Authentication ），以 Base64 编码的形式包含在请求头的 Authorization 字段中发送给服务器


以下为示例。 
POST /oauth2/token HTTP/1.1
Host: cnb.cool
Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&code=SplxlOBeZQQYbYS6WxSbIA
&redirect_uri=https%3A%2F%2Fclient%2Eexample%2Ecom%2Fcb

认证服务器发送的 HTTP 回复，包含以下参数：
  • access_token：表示访问令牌，8 小时有效期，必选项。
  • token_type：表示令牌类型，该值大小写不敏感，必选项，可以是 bearer 类型或 mac 类型。
  • expires_in：表示过期时间，单位为秒。如果省略该参数，必须其他方式设置过期时间。
  • refresh_token：表示更新令牌，用来获取下一次的访问令牌，可选项。
  • scope：表示权限范围，如果与客户端申请的范围一致，此项可省略。

以下为示例。 
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache

{
    "access_token":"2YotnFZFEjr1zCsicMWpAA",
    "token_type":"bearer",
    "expires_in":3600,
    "refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA"
}

3. 通过 refresh_token 更新令牌

access_token是调用授权关系接口的调用凭证，由于access_token有效期（ 8 小时）较短，当access_token超时后，可以使用refresh_token进行刷新。每次使用刷新令牌后，会返回新的令牌和刷新令牌，旧的令牌与刷新令牌在宽限期（ 5 分钟）内还可继续使用，请妥善保存用户的相关令牌。

refresh_token拥有较长的有效期（ 180 天），当refresh_token失效的后，需要用户重新授权。

客户端发出更新令牌的 HTTP 请求，包含以下参数：

  • grant_type：表示使用的授权模式，此处的值固定为refresh_token，必选项。
  • refresh_token：表示早前收到的更新令牌，必选项。

以下为示例。 
POST /oauth2/token HTTP/1.1
Host: cnb.cool
Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token&refresh_token=tGzv3JOkF0XG5Qx2TlKWIA

返回示例同access_token

4. 撤销令牌

当用户退出登录或应用需要主动使令牌失效时，可调用撤销接口吊销 access_token 或 refresh_token。令牌撤销后立即失效，无法再用于 API 调用。

客户端发出撤销令牌的 HTTP 请求，包含以下参数：

  • token：表示需要撤销的令牌（access_token 或 refresh_token），必选项。
  • client_id：表示客户端 ID，可选项，也可通过 HTTP Basic Authentication 传递。
  • client_secret：表示客户端密钥，可选项，也可通过 HTTP Basic Authentication 传递。

client_id/client_secret 可以通过 HTTP 基本认证（HTTP Basic Authentication），以 Base64 编码的形式包含在请求头的 Authorization 字段中发送给服务器。


以下为示例。 
POST /oauth2/revoke HTTP/1.1
Host: cnb.cool
Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW
Content-Type: application/x-www-form-urlencoded

token=2YotnFZFEjr1zCsicMWpAA

认证服务器发送的 HTTP 回复：
  • 撤销成功时，返回 HTTP 200。
  • 若传入的令牌无效或已过期，服务器同样返回 HTTP 200（符合 RFC 7009 规范）。
  • 若 client_id/client_secret 认证失败，服务器返回 HTTP 401，响应体包含错误详情。
HTTP/1.1 200 OK

认证失败时的响应示例：

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
    "error": "invalid_client",
    "error_description": "Client authentication failed (e.g., unknown client, no client authentication included, or unsupported authentication method)."
}

可授权范围

可操作权限权限类型说明
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-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只读/读写访问任务集
© 2026 cnb.cool