This topic describes how to access Drive and Photo Service from a web server application by using Open Authorization (OAuth) 2.0.
1. Overview
(1) How it works
The files of a user that are stored in Drive and Photo Service are the resources of the user. A web server application is a third-party client to Drive and Photo Service. A third-party web server application must be authorized by the user before the application can access the resources of the user in Drive and Photo Service. The Drive and Photo Service authorization server is entrusted to perform authorization.
For more information, see The OAuth 2.0 Authorization Framework.
OAuth 2.0 authorization process (authorization code mode)
In the authorization code mode, the authorization process is complete and rigorous.
The following steps show the authorization process:
A. The user accesses a web server application, and the application redirects the user to the authorization server.
B. The user decides whether to grant the required permissions to the application.
C. If the user agrees to grant the permissions, the authorization server redirects the user based on the specified URI, and provides an authorization code.
D. After the authorization code is obtained, the application exchanges the authorization code for an access token from the authorization server. The redirect URI is included in the request for the access token. This step is performed on the backend server of the application and is invisible to the user.
E. After the authorization server confirms that the authorization code and the redirect URI are valid, an access token and a refresh token are sent to the application.
(2) Flowchart
2. Preparations
(1) Create a domain
Create a domain in the PDS (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 logon page
Enable the logon page that is provided by Drive and Photo Service for authorization. After the logon page is enabled, Drive and Photo Service provides a fourth-level API domain name in the format of https://{domainId}.api.aliyunpds.com
.
(3) Create an application to be used as an OAuth client in the Drive and Photo Service console
Create an application. When you create the application, set the Type parameter to WebServer (Web Server Application). Select one or more scopes for the application. The selected scopes are displayed on the consent page that is used for authorization. For more information, see Scopes. 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.
3. Obtain an OAuth 2.0 access token
(1) Configure the parameters for the authorization request
If a user accesses your web server application by using a browser and does not complete authorization, your application must build a request for authorization. For example, the user does not log on to your web server application. The request includes the AppId of your web server application and the scope of permissions. Then, the user sends the request and the Drive and Photo Service authorization server grants the required permissions to your application.
Note: You must call the OAuth 2.0 service over HTTPS. API request syntax:
GET /v2/oauth/authorize?client_id=<appId>&redirect_uri=<redirect_uri>&login_type=<login_type>&scope=<scope>&response_type=code&state=[state] 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 the user after the authorization process is complete. Set this parameter to a URI that is provided by the web server application. Example: |
scope | No | The scopes that specify the permissions on actions required by your application. The scopes are a subset of the ones that you specify when you create an application and are displayed on the consent page. For more information, see Scopes. |
response_type | Yes | The type of the response. Set the value to |
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: |
login_type | Yes | The logon method. Valid values: |
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: |
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 the hide_consent parameter is not set to true in the request, 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 that is specified by the redirect_uri parameter. Example: https://example.com/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 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 server redirects the user to the redirect URI
that is specified in Step (1). Example: https://example.com/callback?code=xxxx&state=abc
.
(3) Exchange the authorization code for an access token
A web server application contains a frontend server and a backend server. The redirect URI
that you configure in Step (1) should be provided by the frontend server: https://example.com/callback
. After the frontend server receives the URI that includes ?code=xxx
, the authorization code
is resolved from the URI and is passed to the backend server. The backend server calls the following operation to exchange the authorization code for an access token, and returns the access token to the frontend server.
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\
&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 AppId of the application. |
client_secret | Yes | The AppSecret of the application. The AppSecret is generated after the application is created. |
redirect_uri | Yes | The 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 | Position | Type | Required | Description |
access_token | body | string | Yes | The generated |
refresh_token | body | string | Yes | The refresh token that is used to refresh the |
expires_time | body | string | Yes | The validity period of the |
expire_in | body | long | Yes | The remaining validity period of the access token. Default value: 7200. Unit: seconds. |
token_type | body | string | Yes | The type of the access token. The value is |
Example:
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*******"
}
Ignore the optional parameters in the response.
4. Call the API operations of Drive and Photo Service
The web frontend server can use the access token
to call the API operations of Drive and Photo Service. The access token
must be included in the Authorization
header of API requests.
For more information, see Call methods.
5. Refresh the access token
(1) API request syntax
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
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 |
client_secret | Yes | 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",
"refresh_token": "xxxxx",
"expires_in":7200,
"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.