This topic describes how to use the OAuth 2.0 authorization code flow to enable a web application to securely access Alibaba Cloud APIs on behalf of a user.
Prerequisites
You have created an OAuth 2.0 web application in the Resource Access Management (RAM) console.
You have created and securely stored the client secret for your application.
Authorization flow overview
The OAuth 2.0 authorization code flow allows a web application to obtain an access token without ever handling the user's credentials directly. The process is as follows:
User initiates logon: A user in a browser tries to access a protected resource in your web application.
Redirect to authorization server: Your application redirects the user's browser to the Alibaba Cloud authorization endpoint to request permission.
User grants consent: The user logs on to their Alibaba Cloud account (if not already logged on) and grants your application the requested permissions.
Receive authorization code: The authorization server redirects the user's browser back to your application's specified redirect URL with a single-use authorization code.
Exchange code for tokens: Your application's backend makes a secure, server-to-server call to the Alibaba Cloud token endpoint, exchanging 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 make authorized API calls to Alibaba Cloud services 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 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 |
scope | No | A space-separated list of the OAuth scopes your application is requesting. If omitted, all scopes configured for the application are requested. |
access_type | No | Set to |
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. |
prompt | No | Set this parameter to |
Example request
The following is an example of the URL your application would construct for the redirect:
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 user's browser to your redirect_uri with the authorization code and state appended 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 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 code for tokens.
Request parameters (POST body)
Parameter | Required | Description |
code | Yes | The authorization code received 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 |
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_codeExample response
If the request is successful, the token endpoint returns a JSON object containing 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 and received a refresh token, you can use it 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 |
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_tokenExample 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 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 web application. |
client_secret | No | The client secret of your web application. |
A successful request will return an HTTP 200 OK status.