全部产品
云市场

Web服务端应用的OAuth2.0接入流程

更新时间:2019-09-06 11:12:26

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

1. 介绍

(1) 原理

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

OAuth2.0 授权流程 (授权码模式,authorization code)

授权码模式(authorization code)是功能最完整、流程最严密的授权模式。

a2

它的步骤如下:

(A)用户访问客户端,后者将前者导向认证服务器。

(B)用户选择是否给予客户端授权。

(C)假设用户给予授权,认证服务器将用户导向客户端事先指定的”重定向URI”(redirection URI),同时附上一个授权码。

(D)客户端收到授权码,附上早先的”重定向URI”,向认证服务器申请令牌。这一步是在客户端的后台的服务器上完成的,对用户不可见。

(E)认证服务器核对了授权码和重定向URI,确认无误后,向客户端发送访问令牌(access token)和更新令牌(refresh token)。

(2) Web 服务应用接入用例图

a1

2. 接入前提

(1) 创建Domain

首先,您需要在CCP官网控制台 https://ccp.console.aliyun.com 创建一个域(Domain)。创建完成后,会提供一个3级API域名 https://{domainId}.api.alicloudccp.com

(2) 启用登录页面

使用此种方式,还需要启用CCP提供的Auth登录页面。开通后,CCP会提供一个3级域名https://{domainId}.auth.alicloudccp.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等信息,好让用户向CCP Auth服务(Authorization Server) 授权给您的Web服务应用。

注意:调用Auth服务必须使用 https。

API 请求语法:

  1. GET /v2/oauth/authorize?client_id=<appId>&redirect_uri=<redirect_uri>&scope=<scope>&state=[state]&prompt=[prompt] HTTP/1.1
  2. Host: {domainId}.api.alicloudapp.com
参数 是否必选 描述
client_id AppId, 如果没有请到官网控制台去创建。
redirect_uri 回调地址: 告诉认证服务在授权认证流程完成后重定向到哪里。一般是您的web服务提供的一个地址:比如:http://a.com/callback, 认证服务在授权完成后,会redirect到这个地址并且带上一次性的code http://a.com/callback?code=xxxx ,然后您需要使用这个code完成后续流程。
注意:这个redirect_uri 必须是您创建App时填写的 redirect_uris 中的其中一个。
scope App访问范围列表,描述您的Web服务应用需要的访问权限范围,是在创建App是填写的Scope的子集,将在用户同意授权页面展示。请看支持的Scope列表注意:最终获取到的AccessToken的权限,将是整个scope和用户本身的权限的交集。
response_type 此处固定为”code”
state 否,但推荐使用 如果请求中包含这个参数,认证服务器在重定向的时候会原封不动返回, 用于防止重放攻击。如:http://a.com/callback?code=xxxx&state=abc
prompt 在用户第一次登录完成后,是否需要展示 consent 页面。可选值: none, consent。如果为none则不展示,直接跳过。

发送此请求后,CCP Auth服务会引导用户去登录。用户登录完成后,如果用户是第一次登录并且请求参数设置了prompt=consent,则会重定向到 consent 页面,否则会直接重定向到请求参数中的redirect_uri,比如: http://a.com/callback?code=xxxx&state=abc

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

(3) 通过 code 获取 AccessToken

Web服务应用,包括2个部分,前端和后端。第一步中配置的 redirect_uri,应该由前端提供: http://a.com/callback。前端接受到 ?code=xxx 之后,解析出code,传给后端。后端调用下面的接口换取 AccessToken,在返回给前端。

API 请求语法:

  1. POST /v2/oauth/token HTTP/1.1
  2. Host: {domainId}.api.alicloudapp.com
  3. Content-Type: application/x-www-form-urlencoded
  4. code=xxx\
  5. &client_id=your_app_id\
  6. &client_secret=your_app_secret\
  7. &redirect_uri=http://a.com/callback\
  8. &grant_type=authorization_code
参数 是否必选 描述
code 一次性code,使用过一次后即失效。
client_id AppId
client_secret 创建App时生成的secret。
redirect_uri 这个redirect_uri 必须是您创建App时填写的redirect_uris 中的一项。
grant_type 根据OAuth2.0规范,此处的值固定为”authorization_code”。

返回

名称 位置 类型 必选 说明
access_token body string 生成的 id_token,有效期2小时。
refresh_token body string 用来刷新 access_token, 有效期比较长,一般为7天。
expires_time body string access_token 的有效期。
token_type body string 固定为 Bearer

样例:

  1. HTTP/1.1 200 OK
  2. Content-Type: application/json
  3. {
  4. "access_token":"Aiasd76YSo23...LSdyssd2",
  5. "expires_time":"2019-11-11T10:10:10.009Z",
  6. "token_type":"Bearer",
  7. "refresh_token":"LSLKdklksd...li3ew6"
  8. }
  • 请忽略返回的数据中的非必选字段。

4. 调用CCP 服务API

web前端可以直接使用 AccessToken 调用 CCP API。只需在请求头的Authorization中带上AccessToken。

调用方式举例:

API 请求语法:

  1. POST /v2/files/list HTTP/1.1
  2. Host: {domainId}.api.alicloudapp.com
  3. Authorization: Bearer {AccessToken}
  4. Content-Type: application/json
  5. {
  6. "drive_id": "1"
  7. }

5. 刷新Token

(1) 请求方式举例:

API 请求语法:

  1. POST /v2/oauth/token/v2/auth/refresh_token HTTP/1.1
  2. Host: {domainId}.api.alicloudapp.com
  3. Content-Type: application/x-www-form-urlencoded
  4. refresh_token=xxx\
  5. &client_id=xxx\
  6. &client_secret=xxx\
  7. &grant_type=refresh_token

请求参数

参数名称 是否必选 描述
refresh_token 用授权码换取访问令牌时获得的刷新令牌。
client_id 应用的身份 ID。
grant_type 根据 OAuth 2.0 协议, 取值为:refresh_token。
client_secret 应用的密钥,用作换取访问令牌时鉴定应用身份的密码。

(2) 返回

  1. HTTP/1.1 200 OK
  2. Content-Type: application/json
  3. {
  4. "access_token":"xxxxxxxxx",
  5. "expires_in":3920,
  6. "expires_time":"2019-11-11T10:10:10.009Z",
  7. "token_type":"Bearer"
  8. }

返回参数

参数名称 描述
access_token 新的访问令牌。应用可以使用新的访问令牌来访问阿里云 API。
expires_in 访问令牌的剩余有效时间,单位为秒。
expires_time 访问令牌的失效时间,ISO时间格式。
token_type 访问令牌的类型。取值为:Bearer。

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