All Products
Search

This Product

    Drive and Photo Service:OAuth 2.0 access process for mobile applications and desktop applications

    Document Center

    Drive and Photo Service:OAuth 2.0 access process for mobile applications and desktop applications

    Last Updated:May 09, 2024

    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

    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

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

    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

    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

    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.