Drive and Photo Service:OAuth 2.0 For Mobile & Desktop Applications

1. Overview

Mobile applications and desktop applications are native applications. It is not secure to store confidential information such as AppSecrets in these applications.

A mobile application for Android or iOS can wake up an authorization application by using a URL scheme.

A desktop application for macOS, Linux, or Windows can wake up an authorization application by using a loopback IP address or a URL scheme.

Alternatively, your application can use WebView to send an authorization request to a web application.

(1) How it works

Authorization code mode: The access process by using an authorization code for a mobile application or desktop application is similar to that for a web application. The only difference is that you do not need to provide an AppSecret to obtain an access token. This is because no web server exists and it is not secure to store an AppSecret in a mobile application or desktop application. However, you can use a code_challenge to enhance security.

(2) Flowchart

(3) Proof Key mechanism

Native applications allow you to use the Proof Key mechanism to obtain an authorization code and exchange the authorization code for an access token.

1. A native application generates and saves a code_verifier. The code verifier is a random string.

2. The native application generates a code_challenge based on the transform method. The native application submits both the code_challenge and the transform method to request an authorization code.

code_challenge = transform(code_verifier, [Plain|S256])

code_challenge=BASE64URL-Encode(SHA256(ASCII(code_verifier)))

For example, if the S256 method is used and the code_verifier is dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk, the code_challenge is E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM.

3. After an authorization code is obtained, the native application exchanges the authorization code for an access token. The PDS authorization server verifies the code_challenge and issues the access token.

The authorization code must include the code_verifier. The PDS authorization server calculates a code_challenge by using the code_verifier and transform method provided by the application and compares the result with the code_challenge provided by the native application. The PDS authorization server issues an access token only if the calculated result is the same as the code_challenge provided by the native application.

2. Preparations

(1) Create a domain

Create a domain in the PDS console. After a domain is created, a third-level API domain name in the format of https://{domainId}.api.aliyunpds.com is provided.

(2) Apply for an AppId and an AppSecret on a third-party platform that provides a user system

PDS provides several commonly used user authentication methods, which developers can directly enable by accessing the PDS console. For more details, please refer to the introduction of User system configuration.

(3) Create an application to be used as an OAuth client in the PDS console

Create a native application. Specify the scopes of the application. The scopes will be displayed on the consent page. 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.

(4) Plan a redirect URI

Use a custom URL scheme that is applicable to an Android or iOS application

Register a URL scheme for an application to uniquely identify the application. The scheme is in the following format: <scheme domain name>://<path>?<params>=<value>.

Use a custom lookback IP address that is applicable to a desktop application

You can start a local web service to listen on a port. Example: http://127.0.0.1:3000/callback or http://[::1]:3000.

3. Obtain an OAuth 2.0 access token

(1) Call the Authorize operation

API request syntax:

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

After a user sends this request, the PDS authorization server instructs the user to log on. If the user logs on for the first time and prompt=consent is specified in the request, the PDS authorization server redirects the user to the consent page. Otherwise, the PDS authorization server redirects the user to the redirect URI specified by the redirect_uri parameter. Example: pdshz001://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 specified 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 redirects the user to the redirect URI specified by the redirect_uri parameter. Example: pdshz001://callback/?code=xxxx&state=abc.

(3) Exchange the authorization code for an access token

After the authorization code is obtained, you can call the Token operation to exchange the authorization code for an access token.

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\
&redirect_uri=pdshz001://callback\
&grant_type=authorization_code\
&code_verifier=xxxx

Response parameters

Sample success response:

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

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

• Ignore the optional parameters in the response.

4. Call PDS API operations

The application can use the access token to call PDS API operations. 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

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

(2) Response

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

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

Response parameters