文档

移动端和桌面端应用的OAuth2.0接入流程

更新时间:

说明

本文档主要描述移动端和桌面客户端如何通过 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) 用例图

image

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_CNen_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 返回结构一样。

  • 本页导读 (0)
文档反馈