Drive and Photo Service:OAuth 2.0 access for web server applications

Step 1: Obtain the ID and secret of an application

1. Log on to the PDS console. In the left-side navigation pane, choose Drive and Photo Service (Developer Edition) > Domains.

2. Find the domain that you want to use and click Details in the Actions column.

3. Create an application.

   Note

   If no application is available, create an application before you perform subsequent operations.

   1. On the domain details page, click the Applications tab and then click Create Application.

   2. In the panel that appears, specify the parameters and click OK.

      For the Type parameter, select WebServer (Web Server Application).

      

4. In the application list, view the ID (client_id) and Secret (client_secret) of the application that you created.

   Important

   You must keep the secret confidential.

Step 2: Authorize OAuth 2.0-based logon

1. Configure the authorization parameters

   If a user who has not completed authorization accesses your web server application by using a browser, your application must build a request for authorization. The request includes the client_id of your application and the scopes of permissions. The request is sent from the user to the PDS authorization server, which lets the user grant the required permissions to your application.

   Sample request:

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

   The following table describes the request parameters:

   Parameter	Required	Description
   client_id	Yes	The application ID. For information about how to obtain the ID, see Obtain the ID and secret of an application.
   redirect_uri	Yes	The callback URL, which is the URL to which the request is redirected upon authorization. Example: https://example.com/callback. After the authorization is successful, the user request is redirected to the URL. The URL carries a one-off verification code, such as https://example.com/callback?code=xxxx. Note Make sure that the callback URL matches the OAuth 2.0 callback URL that you specified when you created the 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 specified when you created the 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 response type. Set the value to code.
   state	No, but recommended	The state. If the request carries this parameter, the authentication server sends the request back in the same state to prevent Cross Site Request Forgery (CSRF) attacks. Example: https://example.com/callback?code=xxxx&state=abc.
   login_type	Yes	The logon option. Valid values: default: provides a comprehensive logon page that supports mobile number logon and other logon methods. phone: mobile number logon. ding: logon with DingTalk. ldap: logon based on lightweight directory access protocol (LDAP) or Active Directory (AD). wx: logon with a WeChat account. ram: logon as a Resource Access Management (RAM) user. lark: logon with Lark. saml: logon with a third-party account based on a Security Assertion Markup Language (SAML) protocol.
   hide_consent	No	Specifies whether to skip the user authorization page for subsequent logon attempts after the first successful logon. Valid values: true (default): The authorization page is not displayed. Users proceed right to the next step. false: The authorization page is displayed.
   lang	No	The language in which the page is displayed. Valid values: zh_CN (default): Simplified Chinese en_US: English

2. 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 PDS authorization server redirects the user request to the redirection URI that is specified in Step 2.1. Example: https://example.com/callback?code=xxxx&state=abc.

3. Exchange the authorization code for an access token

   A web server application contains two parts: frontend and backend. You must configure the redirection URI, such as https://example.com/callback, on the frontend. After receiving the parameter ?code=xxx, the frontend parses the code and pass it to the backend. The backend uses the following method to obtain an access token and returns it to the frontend.

   Sample request:

   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 application ID. For information about how to obtain the ID, see Obtain the ID and secret of an application.
   client_secret	Yes	The secret that was generated when you created the application.
   redirect_uri	Yes	The callback URL, which is the URL to which the request is redirected upon authorization. Example: https://example.com/callback. Note Make sure that the callback URL matches the OAuth 2.0 callback URL that you specified when you created the application.
   grant_type	Yes	The grant type. Set the value to authorization_code, which indicates the Authorization Code method.

   Sample response:

   HTTP/1.1 200 OK
   Content-Type: application/json
   
   {
     "access_token":"Aiasd76*****",
     "expires_time":"2019-11-11T10:10:10.009Z",
     "expire_in": 7200,
     "token_type":"Bearer",
     "refresh_token":"LSLKdk*******"
   }

   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 expiration time of the access token.
   expire_in	body	long	Yes	The validity period of the access token. Unit: seconds. Default value: 7200.
   token_type	body	string	Yes	The token type. The value is Bearer.

4. Call the PDS API

   The web frontend can use the access token to call the API operations of PDS. The access token must be included in the Authorization header of API requests.

   For more information, see Calling methods.

Refresh the access token

Sample request:

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

The following table describes the request parameters:

Sample 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"
}