OAuth 2.0 For Web Server Applications - Drive and Photo Service

Note

This topic describes how to access Drive and Photo Service from a web server application by using Open Authorization (OAuth) 2.0.

1. Overview

(1) How it works

The files of a user that are stored in Drive and Photo Service are the resources of the user. A web server application is a third-party client to Drive and Photo Service. A third-party web server application must be authorized by the user before the application can access the resources of the user in Drive and Photo Service. The Drive and Photo Service authorization server is entrusted to perform authorization.

For more information, see The OAuth 2.0 Authorization Framework.

OAuth 2.0 authorization process (authorization code mode)

In the authorization code mode, the authorization process is complete and rigorous.

The following steps show the authorization process:

A. The user accesses a web server application, and the application redirects the user to the authorization server.

B. The user decides whether to grant the required permissions to the application.

C. If the user agrees to grant the permissions, the authorization server redirects the user based on the specified URI, and provides an authorization code.

D. After the authorization code is obtained, the application exchanges the authorization code for an access token from the authorization server. The redirect URI is included in the request for the access token. This step is performed on the backend server of the application and is invisible to the user.

E. After the authorization server confirms that the authorization code and the redirect URI are valid, an access token and a refresh token are sent to the application.

(2) Flowchart

2. Preparations

(1) Create a domain

Create a domain in the PDS (Drive and Photo Service) console. After a domain is created, a fourth-level API domain name in the format of https://{domainId}.api.aliyunpds.com is provided.

(2) Enable the logon page

Enable the logon page that is provided by Drive and Photo Service for authorization. After the logon page is enabled, Drive and Photo Service provides a fourth-level API domain name in the format of https://{domainId}.api.aliyunpds.com.

(3) Create an application to be used as an OAuth client in the Drive and Photo Service console

Create an application. When you create the application, set the Type parameter to WebServer (Web Server Application). Select one or more scopes for the application. The selected scopes are displayed on the consent page that is used for authorization. For more information, see Scopes. After the application is created, you can obtain the AppId and AppSecret of the application. The AppId and AppSecret are used as the ClientId and ClientSecret for OAuth authorization. Keep the ClientSecret secure.

3. Obtain an OAuth 2.0 access token

(1) Configure the parameters for the authorization request

If a user accesses your web server application by using a browser and does not complete authorization, your application must build a request for authorization. For example, the user does not log on to your web server application. The request includes the AppId of your web server application and the scope of permissions. Then, the user sends the request and the Drive and Photo Service authorization server grants the required permissions to your application.

Note

Note: You must call the OAuth 2.0 service over HTTPS. API request syntax:

GET /v2/oauth/authorize?client_id=<appId>&redirect_uri=<redirect_uri>&login_type=<login_type>&scope=<scope>&response_type=code&state=[state] HTTP/1.1
Host: {domainId}.api.aliyunpds.com

Parameter	Required	Description
client_id	Yes	The AppId of your application. If you do not have an AppId, create an application to obtain an AppId in the Drive and Photo Service console.
redirect_uri	Yes	The URI to which the Drive and Photo Service authorization server redirects the user after the authorization process is complete. Set this parameter to a URI that is provided by the web server application. Example: `https://example.com/callback`. After the authorization is complete, the Drive and Photo Service authorization server redirects the user to the redirect URI suffixed with a one-off authorization code in the format of `https://example.com/callback?code=xxxx`. You can use this authorization code in subsequent operations. Note: The redirect URI that you specify must be one of the redirect URIs that you configure for your application.
scope	No	The scopes that specify the permissions on actions required by your application. The scopes are a subset of the ones that you specify when you create an application and are displayed on the consent page. For more information, see Scopes. `Note: The permissions represented by the access token are the intersection of the permissions of the user and the permissions that the scopes specify.`
response_type	Yes	The type of the response. Set the value to `code`.
state	No, but recommended	If this parameter is specified, the Drive and Photo Service authorization server returns this value intact in the redirect URI to prevent replay attacks. Example: `https://example.com/callback?code=xxxx&state=abc`.
login_type	Yes	The logon method. Valid values: `default, phone, ding, ldap, wx, and ram`. `default`: logs on to the default logon page. The default logon page also provides links to other logon methods, such as the logon by using an SMS verification code. `phone`: logs on by using an SMS verification code. `ding`: logs on by using the DingTalk application to scan a QR code. `ldap`: logs on by using an Active Directory (AD) domain or Lightweight Directory Access Protocol (LDAP). `wx`: logs on by using WeChat. `ram`: logs on as a Resource Access Management (RAM) user.
hide_consent	No	Specifies whether to display the consent page if the user logs on for the first time. Valid values: true and false. If the value is true, the consent page is not displayed.
lang	No	The language in which the page is displayed. Valid values: `zh_CN` and `en_US`. Default value: `zh_CN`.

After a user sends this request, the Drive and Photo Service authorization server instructs the user to log on. If the user logs on for the first time and the hide_consent parameter is not set to true in the request, the Drive and Photo Service authorization server redirects the user to the consent page. Otherwise, the Drive and Photo Service authorization server redirects the user to the redirect URI that is specified by the redirect_uri parameter. Example: https://example.com/callback?code=xxxx&state=abc.

(2) Grant permissions to the application on the consent page

On the consent page, the user can decide whether to grant the permissions to the application. If the user refuses to grant the permissions, the process ends. If the user agrees to grant the permissions, the Drive and Photo Service authorization server redirects the user to the redirect URI that is specified in Step (1). Example: https://example.com/callback?code=xxxx&state=abc.

(3) Exchange the authorization code for an access token

A web server application contains a frontend server and a backend server. The redirect URI that you configure in Step (1) should be provided by the frontend server: https://example.com/callback. After the frontend server receives the URI that includes ?code=xxx, the authorization code is resolved from the URI and is passed to the backend server. The backend server calls the following operation to exchange the authorization code for an access token, and returns the access token to the frontend server.

Note

API request syntax:

POST /v2/oauth/token HTTP/1.1
Host: {domainId}.api.aliyunpds.com
Content-Type: application/x-www-form-urlencoded

code=xxx\
&client_id=your_app_id\
&client_secret=your_app_secret\
&redirect_uri=https://example.com/callback\
&grant_type=authorization_code

Parameter	Required	Description
code	Yes	The one-off authorization code.
client_id	Yes	The AppId of the application.
client_secret	Yes	The AppSecret of the application. The AppSecret is generated after the application is created.
redirect_uri	Yes	The redirect URI that you configure for your application.
grant_type	Yes	Set the value to authorization_code based on the OAuth 2.0 specifications.

Response parameters

Parameter	Position	Type	Required	Description
access_token	body	string	Yes	The generated `access token`, which is valid for two hours.
refresh_token	body	string	Yes	The refresh token that is used to refresh the `access token`. In most cases, the validity period of a refresh token is seven days.
expires_time	body	string	Yes	The validity period of the `access token`.
expire_in	body	long	Yes	The remaining validity period of the access token. Default value: 7200. Unit: seconds.
token_type	body	string	Yes	The type of the access token. The value is `Bearer`.

Example:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "access_token":"Aiasd76YSo23...LSdyssd2",
  "expires_time":"2019-11-11T10:10:10.009Z",
  "expire_in": 7200,
  "token_type":"Bearer",
  "refresh_token":"LSLKdklksd...li3ew6"
}

Ignore the optional parameters in the response.

4. Call the API operations of Drive and Photo Service

The web frontend server can use the access token to call the API operations of Drive and Photo Service. The access token must be included in the Authorization header of API requests.

For more information, see Invoking Methods.

5. Refresh the access token

(1) API request syntax

Note

API request syntax:

POST /v2/oauth/token HTTP/1.1
Host: {domainId}.api.aliyunpds.com
Content-Type: application/x-www-form-urlencoded

refresh_token=xxx\
&client_id=xxx\
&client_secret=xxx\
&grant_type=refresh_token

Request parameters

Parameter	Required	Description
refresh_token	Yes	The refresh token that is returned when you exchange the authorization code for the access token.
client_id	Yes	The AppId of your application.
grant_type	Yes	Set the value to `refresh_token` based on the OAuth 2.0 specifications.
client_secret	Yes	The AppSecret of your application. The AppSecret is used to authenticate the application.

(2) Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "access_token":"xxxxxxxxx",
  "refresh_token": "xxxxx",
  "expires_in":7200,
  "expire_time":"2019-11-11T10:10:10.009Z",
  "token_type":"Bearer"
}

Response parameters

The structure of the response to a request for refreshing an access token is the same as that to a request for Exchanging an authorization code for an access token.