OAuth2.0说明文档

OAuth2.0说明文档

1、OAuth 2.0 简介

OAuth为应用提供了一种访问受保护资源的方法。在应用访问受保护资源以前，它必须先从资源拥有者处获取受权（访问许可），而后用访问许可交换访问令牌（表明许可的做用域、持续时间和其它属性）。应用经过向资源服务器出示访问令牌来访问受保护资源。

 

下图中的名词说明

Resource Owner：用户

User-Agent：浏览器

Client：应用服务器

Authorization Server：认证服务器（用户信息存放服务的认证服务器）

Resource Server：资源服务器（用户真正信息存放的服务器，须要经过access_token进行访问）

Web-Hosted Client Resource：web托管的客户端资源（这个确切的说，我也不知道叫啥才适合）

 

OAuth2.0服务支持如下5种获取Access Token的方式：（图片来源：OAuth2.0协议草案 ）

1.1、APP密钥模式（Client Credentials Flow）

直接使用app密钥，不另做说明

 

 

1.2、Resource Owner Password Credentials Flow

直接使用用户密码，不另做说明

 

 

1.3、Authorization Code Flow

受权码模式

 

流程简单表述为，当用户访问应用服务器

(A)应用服务器返回带有受权信息的重定向连接，浏览器拿到连接，转为访问认证服务器（见下面：获取Authorization Code）

(B)认证服务器提供界面给用户进行确认受权，用户确认受权

(C)用户确认受权后，认证服务器返回带有code的重定向连接，浏览器拿到连接，转为访问应用服务器

(D)应用服务器拿到code，访问认证服务器（见下面：经过Authorization Code获取Access Token）

(E)认证服务器验证后，返回access_token给应用服务器

受权码是应用弹出窗口，并将用户引导到受权服务器，传入标识符、请求做用域、本地状态，和一个重定向URI。受权服务器验证用户，得到受权，而后用重定向URI引导回应用，并传回受权码给应用。由于终端用户只在受权服务器上进行验证，因此终端用户的用户名和密码历来不用分享给应用。

 

获取Authorization Code

参数名	必选	介绍
client_id	True	建立应用时得到的App Key
response_type	True	此值固定为“code”
redirect_uri	True	受权后要回调的URI，即接收Authorization Code的URI, 其值能够是“oob”。 非“oob”值的redirect_uri所在域名必须与开发者注册应用时所提供的回调地址的域名相匹配
scope	False	以空格分隔的权限列表，若不传递此参数，表明请求默认的basic权限。（目前只有basic权限）
state	False	hash，用于预防CSRF，用于保持请求和回调的状态，受权服务器在重定向到“redirect_uri”时，会在Query Parameter中原样回传该参数

/authorize?client_id=ABCDEFGHIJKLMNOP&response_type=code&redirect_uri=http://www.example.com/oauth_redirect&scope=basic&state=mytest

若是用户在此页面赞成受权，则将重定向用户浏览器到指定的“redirect_uri”，并附带上表示受权服务所分配的Authorization Code的code参数（假设为“0987654321“），以及state参数（若是有），验证经过后，认证服务器将重定向用户浏览器到“http://www.example.com/oauth_redirect?state=mytest&code=0987654321”

说明：每个Authorization Code的有效期为60秒（可根据需求调长一些，但原则上应尽量短），而且只能使用一次，再次使用将无效。

 

经过Authorization Code获取Access Token

经过上面第一步得到Authorization Code后，即可以用其向认证服务器换取一个Access Token。

参数名	必选	介绍
grant_type	True	此值固定为“authorization_code”
code	True	经过上面第一步所得到的Authorization Code
client_id	True	建立应用时得到的App Key
client_secret	True	应用的App Secret
redirect_uri	True	redirect_uri所在域名必须与开发者注册应用时所提供的回调地址的域名匹配

/access_token?grant_type=authorization_code&code=0987654321&client_id=ABCDEFGHIJKLMNOP&client_secret=abcdefg...&redirect_uri=http://www.example.com/oauth_redirect

 

若参数无误，服务器将返回一段JSON文本，包含如下参数：

参数名	必选	介绍
access_token	True	获取的Access Token
token_type	False	令牌类型“bearer”或“mac”，暂无很明确的说明，一般是brearer或省略
expires_in	True	Access Token的有效期，以秒为单位
refresh_token	False	用于刷新Access Token 的 Refresh Token
scope	False	Access Token最终的访问范围，即用户实际授予的权限列表，用户在受权页面时，有可能会取消掉某些请求的权限，一般只做或只有登陆认证的话，可忽略

示例：Content-Type: application/json

{"access_token":"uuvvwwxxyyzz","expires_in":"3600", "scope":"basic","refresh_token":"qwertyuiop"}

 

1.4、Implicit Grant Flow

简化模式，该模式下，一般client和user-agent是在一块儿的，如手机app等

 

流程简单表述为，当用户访问应用服务

(A)应用服务返回带有受权信息的重定向连接，浏览器拿到连接，转为访问认证服务器

(B)认证服务器提供界面给用户进行确认受权，用户确认受权

(C)假设资源全部者授予访问权限，则认证服务器返回带有获取access_token的令牌的连接

(D)浏览器连接重定向到一个web客户端资源，访问资源服务器

(E)返回一个网页（一般是一个嵌入式脚本的HTML文档）

(F)浏览器从脚本中提取access_token（包括其余参数）

(G)浏览器带着access_token重定向到应用服务器，应用服务器到浏览器传来的access_token

采用Implicit Grant方式获取Access Token的受权验证流程又被称为User-Agent Flow，适用于全部无Server端配合的应用（因为应用每每位于一个User Agent里，如浏览器里面，所以这类应用在某些平台下又被称为Client-Side Application），如手机/桌面客户端程序、浏览器插件等，以及基于JavaScript等脚本语言实现的应用。

 

1.5、Refreshing an Expired Access Token

令牌刷新方式，适用于全部有Server端配合的应用，其实就是更新access_token

 

获取Access Token，都会拿到有效期为14天的Refresh Token，和2分钟有效期的Access Token。对于这些应用，只要用户在14天内登陆，应用就可使用Refresh Token得到新的Access Token。

 

要使用Refresh Token得到新的Access Token，须要应用在其服务端发送请求（推荐用POST方法）到开放平台OAuth2.0受权服务的如下地址： “/access_token”，并带上如下参数：

参数名	必选	介绍
grant_type	True	必须为“refresh_token”
refresh_token	True	用于刷新Access Token用的Refresh Token
client_id	True	建立应用时得到的App Key
client_secret	True	应用的App Secret
scope	False	以空格分隔的权限列表，若不传递此参数，表明请求默认的basic权限。注：经过Refresh Token刷新Access Token时所要求的scope权限范围必须小于等于上次获取Access Token时授予的权限范围

示例：

/access_token?grant_type=refresh_token&refresh_token=qwertyuiop&client_id=ABCDEFGHIJKLMNOP&client_secret=abcdefg...&scope=basic

若请求成功服务器将返回一段JSON文本，包含如下参数

示例：Content-Type: application/json

{ "access_token":"uuvvwwxxyyzz","expires_in":"120","scope":"basic","refresh_token":" qwertyuiop"}

 

2、使用access_token调用API

获取access_token之后，就可使用access_token调用API接口。

调用API的URL“/json”传递须要的参数，参数的详细介绍请参照以上描述

例：/json?access_token=uuvvwwxxyyzz