Note
This topic describes how mobile applications and desktop applications access Drive and Photo Service 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 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.
(2) Flowchart
![image](https://help-static-aliyun-doc.aliyuncs.com/assets/img/en-US/2464325171/p577131.png)
2. Preparations
(1) Create a domain
Create a domain in the 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 user system logon feature
Drive and Photo Service provides several common user systems for logon authentication. Developers can enable the user system logon feature in the Drive and Photo Service console. For more information, see PDS user systems.
(3) Create an application to be used as an OAuth client in the Drive and Photo Service 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. The AppKey and AppSecret are credentials for authorization and authentication. You must keep the AppSecret confidential.
(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>&login_type=<login_type>&state=[state]&prompt=[prompt] HTTP/1.1
Host: {domainId}.api.aliyunpds.com
Parameter | Required | Description |
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 users after the authorization process is complete. Set this parameter to the URL scheme or lookback IP address provided by the application. Example: pdshz001://callback/ . After the authorization is complete, the Drive and Photo Service authorization server redirects users to the redirect URI suffixed with a one-off authorization code in the format of pdshz001://callback/?code=xxxx . You can exchange this authorization code for an access token. Note: The redirect URI that you specify must be the same as that you configure for your application. |
scope | Yes | The scopes that specify the permissions required by your application. The scopes will be displayed on the consent page. For more information, see Authorize. |
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: pdshz001://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 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 does not set the hide_consent
parameter to true, 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 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 Drive and Photo Service 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:
&grant_type=authorization_code
Parameter | Required | Description |
Parameter | Required | Description |
code | Yes | The one-off authorization code. |
client_id | Yes | The AppId of your application. |
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 parameters
Parameter | Location | Type | Required | Description |
Parameter | Location | Type | Required | Description |
access_token | body | STRING | Yes | The generated access token, which is valid for two hours. |
expires_time | body | STRING | Yes | The validity period of the access token. |
expire_in | body | STRING | Yes | The remaining validity period of the access token. Unit: seconds. |
token_type | body | STRING | Yes | The value is fixed to Bearer. |
Sample success response:
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"
}
Note
The response to this request is the same as that returned when you obtain the access token by using the authorization code, except that the refresh_token parameter is not included.
Note
Ignore the optional parameters in the response.
4. Call Drive and Photo Service API operations
The application can use the access token to call Drive and Photo Service API operations. The access token must be included in the Authorization header of API requests.
For more information, see Call method.
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 |
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 | The type of the grant method. 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
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.