移动端和桌面端如何通过OAuth2.0接入PDS_网盘与相册服务(PDS)-阿里云帮助中心

说明

本文档主要描述移动端和桌面客户端如何通过 OAuth2.0 接口接入 PDS。

1. 介绍

由于是端应用，您的应用中无法存放机密信息，比如 App 的 secret。

对于移动端（Android, IOS），一般是要唤醒授权App授权，需要使用 URL Scheme。

对于桌面客户端（mac,linux windows 桌面端），可以通过回环IP地址（Loopback IP address）唤醒授权端, 也可以通过 URL Scheme。

还有一种方式也比较常用，就是通过webview 请求Web服务应用的方式。

(1) 原理：

授权码模式：同Web服务应用接入的授权码模式基本相同，除了获取token的步骤不需要提供Secret参数（因为没有Web服务端，而secret不能放在客户端）。

(2) 用例图

2. 接入前提

(1) 创建Domain

首先，您需要在 PDS 官网控制台 https://pds.console.aliyun.com创建一个域（Domain）。创建完成后，会提供一个3级API域名 https://{domainId}.api.aliyunpds.com。

(2) 开启用户体系登录

PDS提供了几种常用的用户体系登录认证方式，开发者可以直接到PDS控制台开启对接。详情请看PDS支持的用户体系介绍。

(3) 创建App（Client）

创建App，选择类型为”Native应用”。确定App的访问Scope, 这个Scope要在用户授权页面展示。创建完成，可以得到 AppId(ClientId) 和 Secret(ClientSecret)。这个是授权认证的凭证，Secret要注意保密不要泄露。

(4) 规划 redirect_uri

自定义URL Scheme（Android, iOS）

APP需要注册自己的URL Scheme，用来唯一标识一个App。Scheme格式：<scheme域名>://<path>?<params>=<value>

自定义Lookback IP Address（桌面客户端）

可以启动一个本地Web服务，监听端口，如 : http://127.0.0.1:3000/callback或者 http://[::1]:3000

3. 获取 OAuth2.0 Access Token 步骤

(1) /authorize 接口

API 请求语法：

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

参数	是否必选	描述
client_id	是	AppId，如果没有请到官网控制台去创建。
redirect_uri	是	回调地址：告诉认证服务在授权认证流程完成后重定向到哪里。一般是您的客户端应用提供的一个URL Scheme或者LookBack IP Address。比如：`pdshz001://callback/`, 认证服务在授权完成后，会redirect到这个地址并且带上一次性的code: `pdshz001://callback/?code=xxxx`，然后您需要使用这个code完成后续流程。注意：这个`redirect_uri`必须和您创建App时填写的`redirect_uri`一致。
scope	是	访问范围列表，描述您的Web服务应用需要的访问权限范围，将在用户同意授权页面展示。请看：Scope说明。
response_type	是	此处固定为”`code`”
state	否，但推荐使用	如果请求中包含这个参数，认证服务器在重定向的时候会原封不动返回, 用于防止重放攻击。如：`pdshz001://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，比如：pdshz001://callback/?code=xxxx&state=abc。

(2) Consent 页面

在此步骤中，用户可以决定是否授权给Web服务应用。如果不同意授权，则流程终止。如果同意授权，将重定向到第一步请求中的 redirect_uri, 比如：pdshz001://callback/?code=xxxx&state=abc。

(3) 通过 code 获取 AccessToken

应用获取到 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\
&redirect_uri=pdshz001://callback\
&grant_type=authorization_code

参数	是否必选	描述
code	是	一次性code，使用过一次后即失效。
client_id	是	AppId
redirect_uri	是	这个redirect_uri 必须和您创建App时填写的redirect_uri 一致。
grant_type	是	根据OAuth2.0规范，此处的值固定为”authorization_code”。

名称	位置	类型	必选	说明
access_token	body	string	是	生成的 id_token，有效期2小时。
expires_time	body	string	是	access_token 的有效期。
expire_in	body	string	是	失效时间。单位秒。
token_type	body	string	是	固定为 Bearer

样例：

HTTP/1.1 200 OK
Content-Type: application/json

{
  "access_token":"Aiasd76Y****...LSdyssd2",
  "expires_time":"2019-11-11T10:10:10.009Z",
  "expire_in": 7200,
  "token_type":"Bearer",
  "refresh_token":"LSLKdklksd...li3ew6"
}

说明

本次请求的返回值与用授权码换取访问令牌的返回值一致，但不包含 refresh_token。

说明

请忽略返回的数据中的非必选字段。

4. 调用 PDS 服务 API

客户端可以直接使用 AccessToken 调用 PDS API。只需在请求头的Authorization中带上AccessToken。

调用方式详细请参考调用方式。

5. 刷新Token

(1) 请求方式举例：

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

请求参数

参数名称	是否必选	描述
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",
  "expires_in":3920,
  "expire_time":"2019-11-11T10:10:10.009Z",
  "token_type":"Bearer"
}

返回参数

同 (3) 通过 code 获取 AccessToken 返回结构一样。