Access Alibaba Cloud APIs from a web application by using OAuth - Resource Access Management

Prerequisites

You have created an OAuth 2.0 web application in the RAM console.
You have created and securely stored the client secret for your application.

Authorization flow overview

The OAuth 2.0 authorization code flow lets your application obtain an access token without handling user credentials directly.

User initiates logon: A user tries to access a protected resource in your web application.
Redirect to authorization server: Your application redirects the browser to the Alibaba Cloud authorization endpoint.
User grants consent: The user logs on to Alibaba Cloud and grants your application the requested permissions.
Receive authorization code: The authorization server redirects the browser to your redirect URL with a single-use authorization code.
Exchange code for tokens: Your backend server calls the Alibaba Cloud token endpoint to exchange the authorization code for an access token, an ID token, and an optional refresh token.
Access protected resources: Your application uses the access token to call Alibaba Cloud APIs on behalf of the user.

Step 1: Request an authorization code

To begin the flow, your web application must redirect the user's browser to the Alibaba Cloud authorization endpoint: https://signin.alibabacloud.com/oauth2/v1/auth.

Request parameters

Parameter	Required	Description
client_id	Yes	The ID of your web application.
redirect_uri	Yes	The redirect URI to which the user is sent after granting consent. Must exactly match a URI registered for your application.
response_type	Yes	Must be set to `code`.
scope	No	Space-separated list of requested OAuth scopes. If omitted, all configured scopes are requested.
access_type	No	Set to `offline` to receive a refresh token along with the access token. If omitted, only an access token is returned.
state	No	An opaque value that maintains state between the request and callback. Use a random, unguessable string to prevent CSRF attacks.
prompt	No	Set to `admin_consent` to force the consent screen even if the user previously granted permissions. If omitted, the consent screen appears only on the first authorization.

Example request

Example redirect URL:

https://signin.alibabacloud.com/oauth2/v1/auth?
client_id=123****&
redirect_uri=https://example.com/authcallback/&
response_type=code&
scope=openid /acs/ccc&
access_type=offline&
state=123456****

Example response

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

GET HTTP/1.1 302 Found
Location: https://example.com/authcallback/?code=ABAFDGDFXYZW888&state=123456****

Step 2: Exchange the authorization code for an access token

After receiving the authorization code, your backend server must POST to the Alibaba Cloud token endpoint (https://oauth.alibabacloud.com/v1/token) to exchange the code for tokens.

Request parameters (POST body)

Parameter	Required	Description
code	Yes	The authorization code from Step 1.
client_id	Yes	The ID of your web application.
redirect_uri	Yes	The same redirect URI used in the Step 1 request.
grant_type	Yes	Must be set to `authorization_code`.
client_secret	Yes	The client secret of your web application.

Example request

POST /v1/token HTTP/1.1
Host: oauth.alibabacloud.com
Content-Type: application/x-www-form-urlencoded
code=ABAFDGDFXYZW888&
client_id=123****&
client_secret=`your_client_secret`&
redirect_uri=https://example.com/authcallback/&
grant_type=authorization_code

Example response

A successful request returns a JSON object with the tokens.

{
  "access_token": "eyJraWQiOiJrMTIzNCIsImVu****",
  "token_type": "Bearer",
  "expires_in": "3600",
  "refresh_token": "Ccx63VVeTn2dxV7ovXXfLtAqLLERA****",
  "id_token": "eyJhbGciOiJIUzI1****",
  "scope": "openid /acs/ccc"
}

Step 3 (Optional): Refresh the access token

Access tokens are short-lived. If you requested offline access, 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 web application.
grant_type	Yes	Must be set to `refresh_token`.
client_secret	No	The client secret of your web application.

Example request

POST /v1/token HTTP/1.1
Host: oauth.alibabacloud.com
Content-Type: application/x-www-form-urlencoded
refresh_token=Ccx63VVeTn2dxV7ovXXfLtAqLLERAH1Bc&
client_id=123****&
client_secret=`your_client_secret`&
grant_type=refresh_token

Example response

The token endpoint returns a new access token.

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

Revoke a refresh token

When a user logs out or disconnects their account, revoke the associated refresh token. 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 web application.
client_secret	No	The client secret of your web application.

A successful request returns HTTP 200 OK.