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