OAuth2.0如何接入PSD服务_网盘与相册服务-阿里云帮助中心

说明

本文档主要描述一个 Web 服务应用如何通过 OAuth2.0 接口接入 PDS 服务。

1. 介绍

(1) 原理

用户的文件（Resource）存在 PDS 服务（Resource Server）上，是用户的资源。Web服务应用，对于 PDS 服务（Resource Server）来说，是一个第三方提供的工具（Client）。第三方工具（Client）如果要访问用户的资源，在 PDS 服务看来，必须要用户同意授权才行。PDS 服务信任 PDS Auth 服务（Authorization Server），委托 PDS Auth 服务来做认证授权中介。

参考 The OAuth 2.0 Authorization Framework

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服务提供的一个地址：比如：`https://example.com/callback`, 认证服务在授权完成后，会redirect到这个地址并且带上一次性的code `https://example.com/callback?code=xxxx` ，然后您需要使用这个code完成后续流程。注意：这个`redirect_uri` 必须是您创建App时填写的 redirect_uris 中的一个。
scope	否	App访问范围列表，描述您的Web服务应用需要的访问权限范围，是在创建App时填写的Scope的子集，将在用户同意授权页面展示。请看Scope说明。`注意：最终获取到的AccessToken的权限，将是整个scope和用户本身的权限的交集。`
response_type	是	此处固定为”`code`”
state	否，但推荐使用	如果请求中包含这个参数，认证服务器在重定向的时候会原封不动返回, 用于防止重放攻击。如：`https://example.com/callback?code=xxxx&state=abc`。
login_type	是	登录选项, 可选项：`['default','phone','ding','ldap','wx','ram']`。 `default`表示默认的登录页面（页面包含手机号登录和其他登录链接），`phone`表示手机号登录，`ding`表示钉钉扫码登录，`ldap`表示LDAP/AD域登录，`wx`表示企业微信登录，`ram`表示阿里云RAM子账号登录。
hide_consent	否	在用户第一次登录完成后，是否需要展示 consent 页面。可选值：true, false。如果为true则不展示，直接跳过。
lang	否	界面展示的语言。目前支持：`zh_CN`，`en_US`。默认： `zh_CN`。

发送此请求后，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	是	生成的 `access_token`，有效期2小时。
refresh_token	body	string	是	用来刷新 `access_token`, 有效期比较长，一般为7天。
expires_time	body	string	是	`access_token`的有效期。
expire_in	body	long	是	默认：7200，单位：秒。
token_type	body	string	是	固定为 `Bearer`

样例：

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 协议，取值为：`refresh_token`。
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 返回的结构一致。