Resource Access Management:Access Alibaba Cloud APIs from a web application

Process

1. A user logs on to a web application by using a browser.

2. The web application redirects the user to the Alibaba Cloud OAuth 2.0 service and sends the URL of the application to the browser.

   Note

   If the user is not logged on to Alibaba Cloud, the web application redirects the user to the Alibaba Cloud logon page.

3. The user logs on to the Alibaba Cloud OAuth 2.0 service by using the browser and requests an authorization code.

4. The Alibaba Cloud OAuth 2.0 service redirects the user to the web application and returns an authorization code to the browser.

5. The web application requests an access token that corresponds to the user from the Alibaba Cloud OAuth 2.0 service. The authorization code is required in the request.

   • For more information about how to obtain an access token, see Obtain an access token.

   • For more information about how to obtain a new access token, see Obtain a new access token.

   • For more information about how to revoke a refresh token, see Revoke a refresh token.

6. The Alibaba Cloud OAuth 2.0 service sends the obtained access token to the web application.

7. The web application uses the access token to access an API of Alibaba Cloud.

   Note

   The access token contains the identity information about the user and can be used by the web application to access the resources of the user.

Obtain an access token

1. The web application redirects the user to the Alibaba Cloud OAuth 2.0 service to obtain an authorization code.

   The endpoint that is used to obtain an authorization code is https://signin.alibabacloud.com/oauth2/v1/auth.

   Table 1. Request parameters

   Parameter	Required	Description
   client_id	Yes	The ID of the web application.
   redirect_uri	Yes	The redirect Uniform Resource Identifier (URI) of the web application.
   response_type	Yes	The type of the response. Set the value to code.
   scope	No	The space-separated list of OAuth scopes. If you leave this parameter empty, the web application requests access to all scopes.
   access_type	No	The access type of the web application. Valid values: online: The web application requests only an access token. offline: The web application requests an access token and a refresh token. The refresh token can be used to obtain new access tokens multiple times based on the business requirements. Default value: online.
   state	No	A value that is used in both the request and response. You can configure the state parameter as a nonce to prevent cross-site request forgery (CSRF) attacks or hold the state between the web application and the Alibaba Cloud OAuth 2.0 service. If you set this parameter to a random string, the Alibaba Cloud OAuth 2.0 service returns the value of state in the response for subsequent use.
   prompt	No	Specifies whether the server needs to prompt the user to grant the required permissions to the web application. If you specify this parameter, the user is required to grant the required permissions to the web application. The user must grant the required permissions to the web application even if the Alibaba Cloud account already granted the required permissions to the web application. If you leave this parameter empty, only the Alibaba Cloud account is required to grant the required permissions to the web application the first time the Alibaba Cloud account uses the web application. Set the value to admin_consent. This value specifies that the server displays the authorization page before the server returns the requested authorization code to the client.

   Sample request

   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****

   Sample response

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

2. The web application uses the authorization code to request an access token that corresponds to the user from the Alibaba Cloud OAuth 2.0 service.

   The endpoint that is used to request an access token is https://oauth.alibabacloud.com/v1/token.

   Table 2. Request parameters

   Parameter	Required	Description
   code	Yes	The authorization code that is obtained by the web application.
   client_id	Yes	The ID of the web application.
   redirect_uri	Yes	The URI that is used to obtain the authorization code.
   grant_type	Yes	Set the value to authorization_code.
   client_secret	No	The application secret that is used to authenticate the web application when the web application requests an access token.

   Sample 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

   Table 3. Response parameters

   Parameter	Description
   access_token	The access token that is returned. The web application can use this token to access Alibaba Cloud APIs.
   expires_in	The remaining validity period of the access token. Unit: seconds.
   token_type	The type of the access token. Valid value: Bearer.
   id_token	The ID token. The value is a JSON Web Token (JWT). If openid is included in the value of the scope parameter in the request that is initiated to obtain the authorization code, an ID token is returned.
   refresh_token	The refresh token. If the access_type parameter is set to offline in the request that is initiated to obtain the authorization code, a refresh token is returned.
   scope	The actual authorization scopes of the obtained authorization code. If the authorization scopes that are required by the web application are not limited to the openid scope, check whether the required scopes are included in the value of the scope parameter. If the web application cannot access the scopes that are specified by the scope parameter, re-grant the permissions. To re-grant the permissions, set the prompt parameter to admin_consent when you request an authorization code by using https://signin.alibabacloud.com/oauth2/v1/auth.

   Sample response

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

Obtain a new access token

The endpoint that is used to request an access token is https://oauth.alibabacloud.com/v1/token.

Sample 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

Sample response

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

Revoke a refresh token

When a user logs out of a web application or removes its account from the web application, you must revoke the refresh token of the application.

The endpoint that is used to revoke a refresh token is https://oauth.alibabacloud.com/v1/revoke.