说明
本文档主要描述一个 Web 服务应用如何通过 OAuth2.0 接口接入 PDS 服务。
1. 介绍
(1) 原理
用户的文件（Resource）存在 PDS 服务（Resource Server）上，是用户的资源。Web服务应用，对于 PDS 服务（Resource Server）来说，是一个第三方提供的工具（Client）。第三方工具（Client）如果要访问用户的资源，在 PDS 服务看来，必须要用户同意授权才行。PDS 服务信任 PDS Auth 服务（Authorization Server），委托 PDS Auth 服务来做认证授权中介。
OAuth2.0 授权流程 （授权码模式,authorization code）
授权码模式（authorization code）是功能最完整、流程最严密的授权模式。
它的步骤如下：
（A）用户访问客户端，后者将前者导向认证服务器。
（B）用户选择是否给予客户端授权。
（C）假设用户给予授权，认证服务器将用户导向客户端事先指定的”重定向URI”（redirection URI），同时附上一个授权码。
（D）客户端收到授权码，附上早先的”重定向URI”，向认证服务器申请令牌。这一步是在客户端的后台的服务器上完成的，对用户不可见。
（E）认证服务器核对了授权码和重定向URI，确认无误后，向客户端发送访问令牌（access token）和更新令牌（refresh token）。
(2) Web 服务应用接入用例图
2. 接入前提
(1) 创建Domain
首先，您需要在 PDS 官网控制台
https://pds.console.aliyun.com
创建一个域（Domain）。创建完成后，会提供一个3级API域名
https://{domainId}.api.aliyunpds.com
。
(2) 启用登录页面
使用此种方式，还需要启用 PDS 提供的 Auth 登录页面。开通后，PDS 会提供一个3级域名
https://{domainId}.api.aliyunpds.com
。
(3) 创建 App(Client)
创建 App，选择类型为”Web服务端应用”。确定 App 的访问Scope: Scope说明 , 这个 Scope 要在用户授权页面展示。创建完成，可以得到 AppId(ClientId) 和 Secret(ClientSecret)。这个是授权认证的凭证，Secret要注意保密不要泄露。
3. 获取 OAuth2.0 Access Token 步骤
(1) 设置 Authorization 参数
用户通过浏览器访问您的Web服务应用，如果用户还没有认证（比如还没登录），您的 Web 服务应用需要构建一个 Authorization 请求，这个请求会带上您的 Web 服务应用的 ID(AppId) 和要访问 Scope 等信息，好让用户向 PDS Auth 服务（Authorization Server） 授权给您的Web服务应用。
说明
注意：调用 Auth 服务必须使用 https。 API 请求语法：
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|
参数 |
是否必选 |
描述 |
|
client_id |
是 |
AppId， 如果没有请到官网控制台去创建。 |
|
redirect_uri |
是 |
回调地址：告诉认证服务在授权认证流程完成后重定向到哪里。一般是您的Web服务提供的一个地址：比如：
|
|
scope |
否 |
App访问范围列表，描述您的Web服务应用需要的访问权限范围，是在创建App时填写的Scope的子集，将在用户同意授权页面展示。请看
Scope说明
。
|
|
response_type |
是 |
此处固定为”
|
|
state |
否，但推荐使用 |
如果请求中包含这个参数，认证服务器在重定向的时候会原封不动返回, 用于防止重放攻击。如：
|
|
login_type |
是 |
登录选项, 可选项：
|
|
hide_consent |
否 |
在用户第一次登录完成后，是否需要展示 consent 页面。可选值：true, false。如果为true则不展示，直接跳过。 |
|
lang |
否 |
界面展示的语言。目前支持：
|
发送此请求后，PDS Auth 服务会引导用户去登录。用户登录完成后，如果用户是第一次登录并且请求参数没有设置了
hide_consent=true
，则会重定向到 consent 页面，否则会直接重定向到请求参数中的 redirect_uri，比如：
https://example.com/callback?code=xxxx&state=abc
。
(2) Consent 页面
在此步骤中，用户可以决定是否授权给 Web 服务应用。如果不同意授权，则流程终止。 如果同意授权，将重定向到第一步请求中的
redirect_uri
, 比如：
https://example.com/callback?code=xxxx&state=abc
。
(3) 通过 code 获取 AccessToken
Web 服务应用，包括2个部分，前端和后端。第一步中配置的
redirect_uri
，应该由前端提供：
https://example.com/callback
。前端接受到
?code=xxx
之后，解析出
code
，传给后端。后端调用下面的接口换取 AccessToken，再返回给前端。
说明
API 请求语法：
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|
参数 |
是否必选 |
描述 |
|
code |
是 |
一次性code，使用过一次后即失效。 |
|
client_id |
是 |
AppId |
|
client_secret |
是 |
创建App时生成的secret。 |
|
redirect_uri |
是 |
这个redirect_uri 必须是您创建App时填写的 redirect_uri 中的一项。 |
|
grant_type |
是 |
根据OAuth2.0规范，此处的值固定为”authorization_code”。 |
返回 ：
|
名称 |
位置 |
类型 |
必选 |
说明 |
|
access_token |
body |
string |
是 |
生成的
|
|
refresh_token |
body |
string |
是 |
用来刷新
|
|
expires_time |
body |
string |
是 |
|
|
expire_in |
body |
long |
是 |
默认：7200，单位：秒。 |
|
token_type |
body |
string |
是 |
固定为
|
样例：
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"
}-
请忽略返回的数据中的非必选字段。
4. 调用 PDS 服务 API
web前端可以直接使用
access_token
调用 PDS API。只需在请求头的
Authorization
中带上
access_token
。
调用方式请参考 调用方式 。
5. 刷新Token
(1) 请求方式举例：
说明
API 请求语法：
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请求参数
|
参数名称 |
是否必选 |
描述 |
|
refresh_token |
是 |
用授权码换取访问令牌时获得的刷新令牌。 |
|
client_id |
是 |
应用的身份 ID。 |
|
grant_type |
是 |
根据 OAuth 2.0 协议， 取值为：
|
|
client_secret |
是 |
应用的密钥，用作换取访问令牌时鉴定应用身份的密码。 |
(2) 返回
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"
}返回参数
返回的结构和 (3) 通过 code 获取 AccessToken 返回的结构一致。