This document aims to provide third-party developers with a standardized OAuth 2.0 application integration process, supporting application registration, user authorization (personal/resource level), temporary ticket issuance, and API access control.

Preparation - Apply for OAuth Application Registration

App Information Registration

Currently, applications require approval from CNB administrators before they can be published. Please submit your application details to an administrator, and we will contact you to discuss the specific plan for creating your OAuth application.

Basic Application Information

Application Info	Required	Field Description
Application Name	Yes	Displayed to users during authorization and on the user authorization management page; max 50 characters.
Application Logo	Yes	Image size must not exceed 1MB.
Application Description	No	Max 350 characters.
Official Website	Yes	Max 128 characters.
Redirect URL	Yes	Redirect URI, used for redirection after OAuth authorization.
Supported Authorization Scopes	Yes	Communicated during the application creation plan, e.g., repo-code:r, account-profile:r, etc. Must be predefined. Applications should only request necessary permission scopes, and the CNB platform will evaluate the reasonableness of the authorization scope during review.
Authorization Resource Scope	Yes	All permissions of the current account / All public resources of the current account / Specified resources.

Authorization Process

The authorization process for users within the application is as follows:

1. The user initiates a CNB authorization request within the application.
2. Redirect the user to CNB's authorization page, carrying the corresponding parameters, to request their CNB identity.
3. After the user agrees, CNB will launch the application or redirect to the third-party website, carrying the authorization temporary ticket code parameter.
4. Exchange for an access_token via API using the code parameter plus ClientID and ClientSecret, etc.
5. Invoke interfaces using the access_token to obtain basic user data resources or help users perform basic operations.

1. Initiate Authorization Request

Third-party websites/apps can initiate authorized login by opening the following link in a browser:

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

If prompted "The link cannot be accessed", please check if parameters are filled incorrectly, such as the domain of redirect_uri not matching the authorization domain filled during review.

The following are the parameters required for the above steps:

• response_type: Indicates the authorization type, required, fixed value is code.
• client_id: Indicates the client ID, required.
• redirect_uri: Indicates the redirect URI, optional.
• state: Indicates the current state of the client, can be any value; the authentication server will return this value unchanged.

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

The server responds to the client with a URI containing the following parameters:

• code: Indicates the authorization code, required. The validity period should be short, usually set to 10 minutes. The client can only use this code once; otherwise, it will be rejected by the authorization server. This code has a one-to-one correspondence with the Client_ID and Redirect URI.
• state: If the client request included this parameter, the authentication server response must include this parameter exactly as is.

After the user grants authorization, they will be redirected to the redirect_uri URL, carrying the code and state parameters. Example below:

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

2. Get access_token via code

The HTTP request from the client to the authentication server to apply for a token contains the following parameters:

• grant_type: Indicates the authorization mode, required, fixed value is authorization_code.
• code: The authorization code obtained in the previous step, required.
• redirect_uri: Redirect URI, optional, must match the value in the first step's code request.

client_id/client_secret can also be sent to the server in the Authorization field of the request header in the form of Base64 encoding via HTTP Basic Authentication.

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

The HTTP response sent by the authentication server includes the following parameters:

• access_token: Indicates the access token, 8-hour validity, required.
• token_type: Indicates the token type, case-insensitive, required, can be bearer type or mac type.
• expires_in: Indicates expiration time in seconds. If omitted, the expiration must be set via other means.
• refresh_token: Indicates the update token, used to get the next access token, optional.
• scope: Indicates permission scope; if consistent with the client's requested scope, this can be omitted.

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. Update Token via refresh_token

The access_token is the credential for calling authorization interfaces. Since the validity period of the access_token is short (8 hours), the refresh_token can be used to refresh it when the access_token times out. Every time a refresh token is used, a new token and refresh token will be returned. The old token and refresh token can still be used within a grace period (5 minutes). Please keep the user's relevant tokens securely.

The refresh_token has a longer validity period (180 days). When the refresh_token expires, the user needs to re-authorize.

The client issues an HTTP request to update the token, containing the following parameters:

• grant_type: Indicates the authorization mode, fixed value is refresh_token, required.
• refresh_token: The refresh token received earlier, required.

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

The return example is the same as access_token.

Authorization Scopes

Action Permission	Permission Type	Description
repo-code	Read-only / Read-write	Access code repository via Git commands
repo-pr	Read-only / Read-write	Access pull requests
repo-issue	Read-only / Read-write	Access ISSUEs
repo-notes	Read-only / Read-write	Access comments in ISSUEs, and pull requests
repo-contents	Read-only / Read-write	Access files, branches, commit records, tags, versions
repo-commit-status	Read-only / Read-write	Access pipeline execution status, badges, commit metadata
repo-cnb-trigger	Read-only / Read-write	Query, delete, trigger, execute Cloud Native Build, start Cloud Native Development
repo-cnb-history	Read-only	Query pipeline build history
repo-cnb-detail	Read-only / Read-write	Query or delete Cloud Native Development space
repo-basic-info	Read-only	Access basic repository information, such as repository name, description, language, license, etc.
repo-manage	Read-only / Read-write	Access repository members, repository settings
repo-delete	Read-write	Delete repository
repo-security	Read-only	Access repository security module data
registry-package	Read-only / Read-write	Access artifacts
registry-package-delete	Read-write	Delete artifacts
registry-manage	Read-only / Read-write	Access artifact registry members, artifact registry settings
registry-delete	Read-write	Delete artifact registry
account-profile	Read-only / Read-write	Access user profile
account-email	Read-only / Read-write	Query user verified email
account-engage	Read-only / Read-write	Access repositories followed by the user, followers, following, Cloud Native Development environments, etc.
group-resource	Read-only / Read-write	Access sub-organizations, repositories
group-manage	Read-only / Read-write	Access organization members, repository wall, organization settings
group-delete	Read-only / Read-write	Delete organization
mission-delete	Read-only / Read-write	Delete mission set
mission-manage	Read-only / Read-write	Access mission set