Create OAuth Application

About 1186 wordsAbout 4 min

This document describes the standard OAuth 2.0 application integration process, covering application registration, user authorization, 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 creation plan.

Basic Application Information

Application Info	Required	Description
Application Name	Yes	Displayed during authorization; max 50 characters
Application Logo	Yes	Image size must not exceed 1 MB
Application Description	No	Max 350 characters
Official Website	Yes	Max 128 characters
Redirect URL	Yes	Redirect URI, used for redirection after OAuth auth
Authorization Scopes	Yes	Only request necessary permissions; reviewed by platform
Authorization Resource Scope	Yes	All resources / All public resources / Specified resources

Authorization Process

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

The user initiates a CNB authorization request within the application
Redirect the user to CNB's authorization page with the corresponding parameters
After the user agrees, CNB redirects to the application's callback URL with the authorization code code
Exchange for an access_token via API using code, ClientID, and ClientSecret
Use the access_token to call APIs for retrieving user data or performing 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 "This link cannot be accessed", please check if the parameters are correct, e.g., whether the domain of redirect_uri matches the authorized domain submitted during review.

The following parameters are required:

response_type: Authorization type, required, fixed value code
client_id: Client ID, required
redirect_uri: Redirect URI, optional
state: Current state of the client; can be any value and will be returned unchanged by the authentication server

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 returns a URI containing the following parameters:

code: Authorization code, required. Usually valid for 10 minutes and can only be used once. Has a one-to-one correspondence with the Client ID and Redirect URI.
state: If the client request included this parameter, the response must include the same value.

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

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

2. Get access_token via code

The client requests a token from the authentication server with the following parameters:

grant_type: Authorization mode, required, fixed value authorization_code
code: Authorization code obtained in the previous step, required
redirect_uri: Redirect URI, optional, must match the value from the first step

client_id/client_secret can also be sent in the Authorization header via HTTP Basic Authentication in Base64 encoding.

POST /oauth2/token HTTP/1.1
Host: cnb.cool
Authorization: Basic <Base64(client_id:client_secret)>
Content-Type: application/x-www-form-urlencoded

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

The authentication server returns the following parameters:

access_token: Access token, 8-hour validity, required
token_type: Token type, case-insensitive, required, can be bearer or mac
expires_in: Expiration time in seconds. If omitted, expiration must be set via other means
refresh_token: Refresh token, used to obtain the next access token, optional
scope: Permission scope; can be omitted if consistent with the requested 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. Update Token via refresh_token

The access_token has a short validity period (8 hours). When it expires, use the refresh_token to refresh it. A new token pair is returned after each refresh, and old tokens remain usable during a grace period (5 minutes).

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

Request parameters:

grant_type: Authorization mode, required, fixed value refresh_token
refresh_token: The refresh token received earlier, required

POST /oauth2/token HTTP/1.1
Host: cnb.cool
Authorization: Basic <Base64(client_id:client_secret)>
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token&refresh_token=tGzv3JOkF0XG5Qx2TlKWIA

The return format is the same as for access_token.

4. Revoke Token

When a user logs out or the application needs to invalidate a token, call the revoke endpoint to revoke an access_token or refresh_token. The token becomes invalid immediately.

Request parameters:

token: The token to be revoked (access_token or refresh_token), required
client_id: Client ID, optional; can also be passed via HTTP Basic Authentication
client_secret: Client secret, optional; can also be passed via HTTP Basic Authentication

client_id/client_secret can also be sent in the Authorization header via HTTP Basic Authentication in Base64 encoding.

POST /oauth2/revoke HTTP/1.1
Host: cnb.cool
Authorization: Basic <Base64(client_id:client_secret)>
Content-Type: application/x-www-form-urlencoded

token=2YotnFZFEjr1zCsicMWpAA

The authentication server response:

Successful revocation: HTTP 200
Invalid or expired token: Also returns HTTP 200 (compliant with RFC 7009)
client_id/client_secret authentication failure: HTTP 401 with error details in the response body

HTTP/1.1 200 OK

Example response on authentication failure:

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)."
}

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 on issues and pull requests
repo-release	Read-only / Read-write	Access tags, releases
repo-commit-status	Read-only / Read-write	Access pipeline status, badges, commit metadata
repo-cnb-trigger	Read-only / Read-write	Query, trigger, execute Cloud Native Build / Dev
repo-cnb-history	Read-only	Query pipeline build history
repo-cnb-detail	Read-only / Read-write	Query or delete Cloud Native Dev spaces
repo-basic-info	Read-only	Basic repo info (name, description, language, etc.)
repo-manage	Read-only / Read-write	Repo members and settings
repo-delete	Read-write	Delete repository
repo-security	Read-only	Repo security module data
registry-package	Read-only / Read-write	Access artifacts
registry-package-delete	Read-write	Delete artifacts
registry-security	Read-only	Package security, license, and SBOM data
registry-manage	Read-only / Read-write	Registry members and settings
registry-delete	Read-write	Delete artifact registry
account-profile	Read-only / Read-write	User profile
account-email	Read-only / Read-write	User verified email
account-engage	Read-only / Read-write	Followed repos, followers, CND environments, etc.
group-resource	Read-only / Read-write	Sub-organizations and repositories
group-manage	Read-only / Read-write	Org members, repo wall, and org settings
group-delete	Read-write	Delete organization
mission-delete	Read-write	Delete mission set
mission-manage	Read-only / Read-write	Access mission set