How mobile client and desktop client connect to PDS via OAuth 2.0 - Drive and Photo Service

Note

This topic describes how mobile applications and desktop applications access Photo and Drive Service (PDS) by using OAuth 2.0.

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 flow: Basically the same as the authorization code flow for web service application integration, except that the step to obtain a token does not require a secret parameter (because there is no server side, and the secret cannot be stored on the client side).

(2) Flowchart

2. Preparations

(1) Create a domain

First, you need to create a domain https://pds.console.alibabacloud.com in the PDS official console. After creation, a third-level API domain name https://{domainId}.api.aliyunpds.com will be provided.

(2) Enable user authentication

PDS provides several common user authentication methods. Developers can go directly to the PDS console to enable the integration. For details, see Account access.

(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>://<path>?<params>=<value>.

Use a custom loopback 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>&login_type=<login_type>&state=[state]&prompt=[prompt] 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 PDS console.
redirect_uri	Yes	Redirect URI: Tells the authentication service where to redirect after the authorization flow is complete. This is typically a custom URL scheme or loopback IP address provided by your client application. For example: `pdshz001://callback/`, after authorization is complete, the authentication service will redirect to this address and include a one-time code: `pdshz001://callback/?code=xxxx`. You then need to use this code to complete the subsequent flow. Note: This `redirect_uri` must match the `redirect_uri` you entered when creating the application.
scope	Yes	The scope list describes the access permissions required by your web service application, and will be displayed on the user consent page. See: Scopes.
response_type	Yes	Fixed as "`code`" here.
state	No, but recommended	If this parameter is specified, the PDS authorization server returns this value intact in the redirect URI to prevent replay attacks. Example: `pdshz001://callback/?code=xxxx&state=abc`.
login_type	Yes	Login options. Optional values: `['default','phone','ding','ldap','wx','ram']`. `default` indicates the default login page (which includes phone number login and other login links), `phone` indicates phone number login, `ding` indicates DingTalk QR code login, `ldap` indicates LDAP/AD domain login, `wx` indicates WeCom login, and `ram` indicates Alibaba Cloud RAM sub-account login.
hide_consent	No	Whether to show the consent page after the user logs in for the first time. Optional values: `true`, `false`. If set to `true`, the consent page is not shown and is skipped directly.
lang	No	The language displayed in the UI. Currently supported: `zh_CN`, `en_US`. Default: `zh_CN`.

After sending this request, the PDS Auth service will guide the user to log in. After the user logs in, if it is the first login and the parameter hide_consent=true was not passed in, the user will be redirected to the consent page; otherwise, the user will be redirected directly to the redirect_uri in the request parameters, for example: pdshz001://callback/?code=xxxx&state=abc.

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

In this step, the user can decide whether to grant authorization to the web service application. If authorization is denied, the flow is terminated. If authorization is granted, the user will be redirected to the redirect_uri specified in the first-step request, for 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

Parameter	Required	Description
code	Yes	The one-off authorization code.
client_id	Yes	AppId
redirect_uri	Yes	This 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:

Parameter	Location	Type	Required	Description
access_token	body	String	Yes	The generated access_token, valid for 2 hours.
expires_time	body	String	Yes	The expiration time of the access_token.
expire_in	body	string	Yes	The validity period of the access_token, in seconds.
token_type	body	String	Yes	The value is Bearer.

Sample success response:

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

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

Note

The response of this request is consistent with the response for exchanging an authorization code for an access token, but does not include the refresh_token.

Note

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 details about how to make calls, see Calling 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\
&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	No	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",
  "expires_in":3920,
  "expire_time":"2019-11-11T10:10:10.009Z",
  "token_type":"Bearer"
}

Response parameters

Same response structure as (3) Exchange the authorization code for an access token.