OAuth 2.0

OAuth 2.0文檔

目錄  [ 隱藏] 一、OAuth 2.0 簡介 二、獲取Access Token的流程 2.一、使用Authorization Code獲取Access Token 2.1.一、簡介 2.1.二、獲取Authorization Code 2.1.三、經過Authorization Code獲取Access Token 2.二、使用Implicit_Grant獲取Access_Token 2.2.一、簡介 2.2.二、獲取Access Token 2.三、使用Refresh_Token獲取Access_Token 2.3.一、簡介 2.3.二、獲取Access Token 三、使用OAuth2.0調用API 3.一、使用URL傳遞驗證參數 3.二、在header裏傳遞驗證參數 3.三、在Post中傳遞驗證參數 四、程序示例 4.一、基於360 OAUTH2.0 PHP SDK調用示例 4.二、返回結果

一、OAuth 2.0 簡介

OAuth爲應用提供了一種訪問受保護資源的方法。在應用訪問受保護資源以前，它必須先從資源擁有者處獲取受權（訪問許可），而後用訪問許可交換訪問令牌（表明許可的做用域、持續時間和其它屬性）。應用經過向資源服務器出示訪問令牌來訪問受保護資源。建議使用oauth2.0。

360開放平臺OAuth2.0服務支持如下3種獲取Access Token的方式：

A.Authorization Code：Web Server Flow，適用於全部有Server端配合的應用。

B.Implicit Grant：User-Agent Flow，適用於全部無Server端配合的應用。

C.Refresh Token：令牌刷新方式，適用於全部有Server端配合的應用。

下面咱們將逐個介紹三種獲取Access Token的方法。

二、獲取Access Token的流程

2.一、使用Authorization Code獲取Access Token

2.1.一、簡介

受權碼是經過將用戶引導到受權服務器而得到的一種訪問許可。受權服務器驗證用戶，得到受權，而後嚮應用分發一個受權碼。由於終端用戶只在受權服務器上進行驗證，因此終端用戶的密碼歷來不用分享給應用。

當應用經過一個user-agent同用戶進行交互的時候，受權碼訪問許可的方式是很合適的。 

圖1所示的受權碼獲取流程包含下列步驟：

A.應用調用javascript的window.open()彈出窗口，並在該窗口將用戶的user-agent引導到受權服務器的用戶受權endpoint來發起這個流程。客戶端傳入標識符、請求做用域、本地狀態，和一個重定向URI（在訪問被許可或被拒絕後受權服務器會從新將user-agent引導回這個URI）。

B.受權服務器驗證用戶的身份（經過user-agent），而且肯定用戶是許可仍是拒絕了應用的訪問請求。

C.若是訪問被許可，受權服務器會使用重定向URI將user-agent引導迴應用。受權服務器傳回一個受權碼給應用，用於進一步獲取訪問令牌。若是用戶選擇拒絕受權，user-agent將關閉此彈出窗口。

2.1.二、獲取Authorization Code

請求參數：

參數名	必選	介紹
client_id	True	建立應用時得到的App Key
response_type	True	此值固定爲「code」
redirect_uri	False	受權後要回調的URI，即接收Authorization Code的URI, 其值能夠是「oob」。 非「oob」值的redirect_uri所在域名必須與開發者註冊應用時所提供的回調地址的域名相匹配
scope	False	以空格分隔的權限列表，若不傳遞此參數，表明請求默認的basic權限。（目前只有basic權限）
state	False	用於保持請求和回調的狀態，受權服務器在回調時（重定向用戶瀏覽器到「redirect_uri」時），會在Query Parameter中原樣回傳該參數
oauth_version	False	（可選）版本號，若是填寫必須爲1.0
display	False	登陸和受權頁面的展示樣式，360桌面應用請傳遞「desktop」，默認爲「default」或空。
relogin	False	僅在實現"使用360帳號登錄"功能時才須要傳遞。當瀏覽器有360cookie時，傳遞relogin可展現「當前帳號登錄確認頁」；relogin值請傳遞公司域名，如www.360.cn可傳遞"relogin=360.cn"

請求示例：

https://openapi.360.cn/oauth2/authorize?client_id=0fb2676d5007f123756d1c1b4b5968bc&response_type=code&redirect_uri=http://www.example.com/oauth_redirect&scope=basic&display=default

受權服務器會根據應用傳遞參數的不一樣，爲用戶展示不一樣的受權頁面。若是用戶在此頁面贊成受權，受權服務則將重定向用戶瀏覽器到指定的「redirect_uri」，並附帶上表示受權服務所分配的Authorization Code的code參數，以及state參數（若是請求authorization code時帶了這個參數）。

例如：繼續上面的例子，假設受權服務在用戶贊成受權後生成的Authorization Code爲「120653f48687763d6ddc486fdce6b51c383c7ee544e6e5eab「，則受權服務將會返回以下響應包以重定向用戶瀏覽器到「http://www.example.com/oauth_redirect」地址上：

返回示例：

HTTP/1.1 200 OK Location: http://www.example.com/oauth_redirect？ state=&code=120653f48687763d6ddc486fdce6b51c383c7ee544e6e5eab 

說明：

A. 「code」參數能夠在「redirect_uri」對應的應用後端程序中獲取。

B. 每個Authorization Code的有效期爲30秒，而且只能使用一次，再次使用將無效。

2.1.三、經過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所在域名必須與開發者註冊應用時所提供的回調地址的域名相匹配

請求示例：

https://openapi.360.cn/oauth2/access_token?grant_type=authorization_code&code=120653f48687763d6ddc486fdce6b51c383c7ee544e6e5eab&client_id=0fb2676d5007f123756d1c1b4b5968bc&client_secret=8d9e3305c1ab18384f562d7d3f3b5179&redirect_uri=http://www.example.com/oauth_redirect

返回參數：

若參數無誤，服務器將返回一段JSON文本，包含如下參數

參數名	必選	介紹
access_token	True	獲取的Access Token
expires_in	True	Access Token的有效期，以秒爲單位
refresh_token	True	用於刷新Access Token 的 Refresh Token
scope	True	Access Token最終的訪問範圍，即用戶實際授予的權限列表（用戶在受權頁面時，有可能會取消掉某些請求的權限）

返回示例：

HTTP/1.1 200 OK Content-Type: application/json Cache-Control: no-store {   "access_token":"120652e586871bb6bbcd1c7b77818fb9c95d92f9e0b735873",   "expires_in":"3600",   "scope":"basic",   "refresh_token":"12065961868762ec8ab911a3089a7ebdf11f8264d5836fd41" } 

2.二、使用Implicit_Grant獲取Access_Token

2.2.一、簡介

採用Implicit Grant方式獲取Access Token的受權驗證流程又被稱爲User-Agent Flow，適用於全部無Server端配合的應用（因爲應用每每位於一個User Agent裏，如瀏覽器裏面，所以這類應用在某些平臺下又被稱爲Client-Side Application），如手機/桌面客戶端程序、瀏覽器插件等，以及基於JavaScript等腳本語言實現的應用，他們的一個共同特色是，應用沒法妥善保管其應用密鑰（App Secret），若是採起Authorization Code模式，則會存在泄漏其應用密鑰的可能性。其流程示意圖以下：

2.2.二、獲取Access Token

爲了獲取Access Token，應用須要將用戶瀏覽器（或手機/桌面應用中的瀏覽器組件）引導到360應用開放平臺OAuth2.0受權服務的「https://openapi.360.cn/oauth2/authorize」地址上，並帶上如下參數：

參數名	必選	介紹
client_id	True	獲取的Access Token
response_type	True	此值固定爲「token」
redirect_uri	False	受權後要回調的URI，即接受code的URI, 其值能夠是「oob」。 非「oob」值的redirect_uri所在域名必須與開發者註冊應用時所提供的回調地址的域名相匹配
scope	False	以空格分隔的權限列表，若不傳遞此參數，表明請求默認的basic權限。（目前只有basic權限）
state	False	用於保持請求和回調的狀態，受權服務器在回調時（重定向用戶瀏覽器到「redirect_uri」時），會在Query Parameter中原樣回傳該參數
display	False	登陸和受權頁面的展示樣式，PC應用請傳遞「desktop」，默認爲「page」，手機應用請傳遞mobile.default

例如：「client_id」爲「 0fb2676d5007f123756d1c1b4b5968bc」的應用要請求某個用戶的默認權限，並在受權後需跳轉到「http://www.example.com/oauth_redirect」，同時但願在彈出窗口中展示用戶登陸受權界面，則應用須要重定向用戶瀏覽器到以下URL：

https://openapi.360.cn/oauth2/authorize?client_id=0fb2676d5007f123756d1c1b4b5968bc&response_type=token&redirect_uri=http://www.example.com/oauth_redirect&scope=basic&display=default

返回參數：

參數名	必選	介紹
access_token	True	要獲取的Access Token
expires_in	True	Access Token的有效期，以秒爲單位
state	False	若是請求獲取Access Token時帶有state參數，則將該參數原樣返回

返回示例：

HTTP/1.1 200 OK Location: http://www.example.com/oauth_redirect?state=# access_token=120652e586871bb6bbcd1c7b77818fb9c95d92f9e0b735873& expires_in=3600 

2.三、使用Refresh_Token獲取Access_Token

2.3.一、簡介

360應用開放平臺的應用不管經過OAuth2.0哪一種方式獲取Access Token，都會拿到有效期爲14天的Refresh Token，和一個小時有效期的Access Token。對於這些應用，只要用戶在14天內登陸，應用就可使用Refresh Token得到新的Access Token。

2.3.二、獲取Access Token

要使用Refresh Token得到新的Access Token，須要應用在其服務端發送請求（推薦用POST方法）到360開放平臺OAuth2.0受權服務的如下地址： 「https://openapi.360.cn/oauth2/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時授予的權限範圍

請求示例：

https://openapi.360.cn/oauth2/access_token?grant_type=refresh_token&refresh_token=12065961868762ec8ab911a3089a7ebdf11f8264d5836fd41&client_id=0fb2676d5007f123756d1c1b4b5968bc&client_secret=8d9e3305c1ab18384f562d7d3f3b5179&scope=basic

若請求成功服務器將返回一段JSON文本，包含如下參數

HTTP/1.1 200 OK Content-Type: application/json Cache-Control: no-store {   "access_token":"120652e586871bb6bbcd1c7b77818fb9c95d92f9e0b735873",   "expires_in":"3600",   "scope":"basic",   "refresh_token":"12065961868762ec8ab911a3089a7ebdf11f8264d5836fd41 "} 

三、使用OAuth2.0調用API

獲取access_token之後，就可使用OAuth2.0調用API接口，有如下3種方法。

3.一、使用URL傳遞驗證參數

在調用API的URL中傳遞須要的參數，以下（參數的詳細介紹請參照API文檔）：

https://openapi.360.cn/user/me.json?access_token=120652e586871bb6bbcd1c7b77818fb9c95d92f9e0b735873

3.二、在header裏傳遞驗證參數

在header裏添加Authorization:OAuth2空格Access Token的值。

Authorization: Oauth2 120652e586871bb6bbcd1c7b77818fb9c95d92f9e0b735873 

3.三、在Post中傳遞驗證參數

在post傳遞的參數中加上Access Token。

access_token=120652e586871bb6bbcd1c7b77818fb9c95d92f9e0b735873 

四、程序示例

4.一、基於360 OAUTH2.0 PHP SDK調用示例

// Create a Oauth2 object $connection = new QClient(API_KEY, API_SECRET, $access_token); $apiResult = $connection->userMe(); 

4.二、返回結果

userMe:object(stdClass)#4 (3) {   ["id"]=>string(8) "11111111"   ["name"]=>string(7) "nameExample"   ["avatar"]=>string(69) "http://avataraddress/face.jpg" }