Use OAuth 2.0 and PKCE to access Alibaba Cloud APIs from a native application - Resource Access Management

This topic describes how to use the OAuth 2.0 authorization code flow with Proof Key for Code Exchange (PKCE) to enable a native application (such as a desktop or mobile app) to securely access Alibaba Cloud APIs on behalf of a user.

Prerequisites

You have created an OAuth 2.0 native application in the Resource Access Management (RAM) console and specified a redirect URI.
You have securely stored the ID for your application. Native applications do not use a client secret.

Authorization flow overview

The authorization code flow with PKCE is the recommended and most secure method for native applications. It adds a security layer that prevents authorization code interception attacks.

Generate code_verifier and code_challenge: Your native application generates a high-entropy random string (the code_verifier) and a transformed version of it (the code_challenge).
User initiates logon: The application opens a browser to the Alibaba Cloud authorization endpoint, passing the code_challenge and its transformation method.
User grants consent: The user logs on to their Alibaba Cloud account and grants the application the requested permissions.
Receive authorization code: The authorization server redirects the user back to the application's specified redirect URL with a single-use authorization code.
Exchange code for tokens: Your application makes a request to the Alibaba Cloud token endpoint, exchanging the authorization code and the original code_verifier for an access token and a refresh token. The server validates the code_verifier against the code_challenge from the first step.
Access protected resources: Your application uses the access token to make authorized API calls to Alibaba Cloud services.

Step 1: Request an authorization code with PKCE

To begin the flow, your application must first generate the PKCE parameters and then direct the user to the authorization endpoint.

1. Generate PKCE parameters

First, your application creates and records a code_verifier, which is a high-entropy cryptographic random string between 43 and 128 characters long.

Next, it creates a code_challenge by transforming the code_verifier using one of the following methods:

Transformation method	Description
`plain`	The `code_challenge` is the same as the `code_verifier`. This method is not recommended for production environments.
`S256`	(Recommended) The `code_challenge` is a Base64-URL-encoded SHA-256 hash of the ASCII `code_verifier` string. `code_challenge = BASE64URL-ENCODE(SHA256(ASCII(code_verifier)))`

Example using S256:

If code_verifier = dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk
Then code_challenge = E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM

2. Redirect to the authorization endpoint

Your application opens a system browser to the Alibaba Cloud authorization endpoint (https://signin.alibabacloud.com/oauth2/v1/auth) with the following parameters.

Parameter	Required	Description
client_id	Yes	The ID of your native application.
redirect_uri	Yes	The redirect URI where the user will be sent after granting consent. This must exactly match one of the URIs registered for your application.
response_type	Yes	Must be set to `code`.
scope	No	A space-separated list of the OAuth scopes your application is requesting. If omitted, all scopes configured for the application are requested.
state	No	An opaque value used to maintain state between the request and callback. It is highly recommended to use a random, unguessable string to prevent Cross-Site Request Forgery (CSRF) attacks.
code_challenge_method	No	The transformation method used. Valid values: `plain` and `S256`. Default value: `plain`.
code_challenge	No	The `code_challenge` string you generated. Note If you omit this parameter, PKCE is not used, and the flow is vulnerable to authorization code interception attacks. In this case, an attacker who intercepts the authorization code can exchange it for an access token.
prompt	No	Set this parameter to `admin_consent` to force the authorization server to display the consent screen to the user, even if they have previously granted the requested permissions. If omitted, the consent screen is only shown the first time a user grants permission to the application.

Example request

https://signin.alibabacloud.com/oauth2/v1/auth?
client_id=98989****
&redirect_uri=meeting%3A%2F%2Fauthorize%2F
&response_type=code
&scope=openid%20%2Fworksuite%2Fuseraccess
&state=123456****
&code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSst****
&code_challenge_method=S256

Example response

If the user grants consent, the authorization server redirects the user's browser to your redirect_uri with the authorization code and state appended as query parameters.

GET HTTP/1.1 302 Found
Location: meeting://authorize/?code=ABAFDGDFXYZW888&state=123456****

Step 2: Exchange the authorization code for an access token

After your application receives the authorization code, it must make a POST request from its backend server to the Alibaba Cloud token endpoint (https://oauth.alibabacloud.com/v1/token) to exchange the authorization code for tokens.

Request parameters (POST body)

Parameter	Required	Description
code	Yes	The authorization code received in Step 1.
client_id	Yes	The ID of your native application.
redirect_uri	Yes	The same redirect URI used in the Step 1 request.
grant_type	Yes	Must be set to `authorization_code`.
code_verifier	No	The original `code_verifier` string generated in Step 1.

Example request

POST /v1/token HTTP/1.1 
Host: oauth.alibabacloud.com 
Content-Type: application/x-www-form-urlencoded
code=ABAFDGDFXYZW888&
client_id=98989****
redirect_uri=meeting://authorize/&
grant_type=authorization_code&
code_verifier=dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk

Example response

If the request is successful, the token endpoint returns a JSON object containing the tokens.

{
  "access_token": "eyJraWQiOiJrMTIzNCIsImVuYyI6****",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "Ccx63VVeTn2dxV7ovXXfLtAqLLERA****",
  "id_token": "eyJhbGciOiJIUzI1****"
}

Step 3 (Optional): Refresh the access token

You can use the refresh token to obtain a new access token without requiring the user to log on again. Endpoint: https://oauth.alibabacloud.com/v1/token

Request parameters (POST body)

Parameter	Required	Description
refresh_token	Yes	The refresh token you received previously.
client_id	Yes	The ID of your native application.
grant_type	Yes	Must be set to `refresh_token`.

Example request

POST /v1/token HTTP/1.1 
Host: oauth.alibabacloud.com 
Content-Type: application/x-www-form-urlencoded
refresh_token=Ccx63VVeTn2dxV7ovXXfLtAqLLERAH****
client_id=98989****
grant_type=refresh_token

Example response

The token endpoint returns a new access token.

{
  "access_token": "eyJraWQiOiJrMTIzNCIsImVuYyI6****",
  "token_type": "Bearer",
  "expires_in": 3600,
}

Revoke a refresh token

When a user logs out of your application or disconnects their account, you should revoke the associated refresh token to invalidate it.

Endpoint: https://oauth.alibabacloud.com/v1/revoke

Request parameters (POST body)

Parameter	Required	Description
token	Yes	The refresh token you want to revoke.
client_id	Yes	The ID of your native application.

A successful request will return an HTTP 200 OK status.