授權(quán)機(jī)制
微博開(kāi)放接口的調(diào)用，如發(fā)微博、關(guān)注等，都是需要獲取用戶身份認(rèn)證的。目前微博開(kāi)放平臺(tái)用戶身份鑒權(quán)主要采用的是OAuth2.0。另外，為了方便開(kāi)發(fā)者開(kāi)發(fā)、測(cè)試自己的應(yīng)用，我們還提供了Basic Auth的身份鑒權(quán)方式，但Basic Auth僅適用于應(yīng)用所屬的開(kāi)發(fā)者自己調(diào)用接口。
快速索引
- 授權(quán)有效期
- 授權(quán)有效期的延續(xù)
OAuth2.0概述
OAuth2.0較1.0相比，整個(gè)授權(quán)驗(yàn)證流程更簡(jiǎn)單更安全，也是未來(lái)最主要的用戶身份驗(yàn)證和授權(quán)方式。
關(guān)于OAuth2.0協(xié)議的授權(quán)流程可以參考下面的流程圖，其中Client指第三方應(yīng)用，Resource Owner指用戶，Authorization Server是我們的授權(quán)服務(wù)器，Resource Server是API服務(wù)器。
開(kāi)發(fā)者可以先瀏覽OAuth2.0的接口文檔，熟悉OAuth2.0的接口及參數(shù)的含義，然后我們根據(jù)應(yīng)用場(chǎng)景各自說(shuō)明如何使用OAuth2.0。
接口文檔
| 接口 | 說(shuō)明 |
|---|---|
| OAuth2/authorize | 請(qǐng)求用戶授權(quán)Token |
| OAuth2/access_token | 獲取授權(quán)過(guò)的Access Token |
| OAuth2/get_token_info | 授權(quán)信息查詢接口 |
| OAuth2/revokeoauth2 | 授權(quán)回收接口 |
| OAuth2/get_oauth2_token | OAuth1.0的Access Token更換至OAuth2.0的Access Token |
注意事項(xiàng)
- 1、OAuth2.0授權(quán)無(wú)需申請(qǐng)，任何應(yīng)用都可以使用。如果開(kāi)發(fā)者需要更長(zhǎng)的授權(quán)有效期參考本文檔授權(quán)有效期部分。
- 2、如果你是站外網(wǎng)頁(yè)應(yīng)用或客戶端應(yīng)用，出于安全性考慮，需要在平臺(tái)網(wǎng)站填寫(xiě)redirect_url（授權(quán)回調(diào)頁(yè)），才能使用OAuth2.0，填寫(xiě)地址：“我的應(yīng)用>應(yīng)用信息>高級(jí)信息”，對(duì)于客戶端，我們也提供了默認(rèn)的回調(diào)頁(yè)地址。詳細(xì)請(qǐng)查看授權(quán)頁(yè)功能部分。
授權(quán)界面
新版授權(quán)頁(yè)改變了之前頁(yè)面信息元素過(guò)多，對(duì)用戶使用帶來(lái)干擾的問(wèn)題，登錄和授權(quán)這兩個(gè)行為已在新版中分離，用戶能夠更好地理解帳號(hào)登錄和授權(quán)的過(guò)程，也為未來(lái)更多的功能帶來(lái)承載空間。
當(dāng)前一個(gè)最完整的授權(quán)分為三個(gè)步驟：登錄-普通授權(quán)-高級(jí)授權(quán)（SCOPE）。但這三個(gè)步驟并不是必然出現(xiàn)，當(dāng)用戶的微博處于登錄狀態(tài)時(shí)，頁(yè)面會(huì)自動(dòng)跳轉(zhuǎn)到普通授權(quán)頁(yè)，“高級(jí)授權(quán)”同樣也不是必須，如果開(kāi)發(fā)者不申請(qǐng)SCOPE權(quán)限，系統(tǒng)會(huì)自動(dòng)跳過(guò)此步驟，回調(diào)應(yīng)用。我們?cè)诨叶葴y(cè)試中統(tǒng)計(jì)發(fā)現(xiàn)，只要合理的使用高級(jí)授權(quán)，開(kāi)發(fā)者完全不必?fù)?dān)心增加操作所帶來(lái)的頁(yè)面流失率問(wèn)題，相反，一個(gè)清晰的授權(quán)體驗(yàn)更能獲取用戶的信任。
與此同時(shí)，授權(quán)項(xiàng)將會(huì)變的更加有條理，之前的普通權(quán)限將作為基礎(chǔ)服務(wù)，用戶不再有感知，與用戶隱私相關(guān)的會(huì)歸到高級(jí)授權(quán)，用戶在授權(quán)時(shí)有權(quán)利逐條取消，進(jìn)一步增強(qiáng)了隱私控制。
應(yīng)用場(chǎng)景
開(kāi)發(fā)者需要根據(jù)各自的應(yīng)用場(chǎng)景，選擇適用的OAuth2.0授權(quán)流程：
- 1、PC端和Web網(wǎng)站，請(qǐng)參考：Web網(wǎng)站的驗(yàn)證授權(quán)（Authorization Code）
- 2、移動(dòng)端應(yīng)用可直接使用官方移動(dòng)SDK，通過(guò)呼起微博客戶端（未安裝微博客戶端的會(huì)呼起H5授權(quán)頁(yè)）方式授權(quán)
- 3、H5輕應(yīng)用，請(qǐng)參考 輕應(yīng)用開(kāi)發(fā)指南
1. 引導(dǎo)需要授權(quán)的用戶到如下地址：
URL
2. 如果用戶同意授權(quán)，頁(yè)面跳轉(zhuǎn)至 YOUR_REGISTERED_REDIRECT_URI/?code=CODE
3. 換取Access Token
其中client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET可以使用basic方式加入header中，返回值
{
"access_token": "SlAV32hkKG",
"remind_in": 3600,
"expires_in": 3600
}4. 使用獲得的Access Token調(diào)用API
移動(dòng)應(yīng)用（主要指Mobile Native App），建議使用官方提供的支持SSO授權(quán)的SDK, 可以大大簡(jiǎn)化授權(quán)流程開(kāi)發(fā)，降低開(kāi)發(fā)成本。
需要說(shuō)明的是，移動(dòng)應(yīng)用請(qǐng)使用open.weibo.cn上的授權(quán)接口，普通的發(fā)博，評(píng)論等資源API依舊調(diào)用weibo.com接口。
- SDK接入流程
- iOS SDK下載
- Android SDK下載
授權(quán)有效期
微博開(kāi)放平臺(tái)的OAuth2.0授權(quán)機(jī)制下，第三方獲取到的access_token是有過(guò)期時(shí)間的，通常過(guò)期時(shí)間為30天。
授權(quán)級(jí)別和OAuth2.0 access_token有效期對(duì)應(yīng)表：
| 授權(quán)級(jí)別 | 測(cè)試 | 普通 |
|---|---|---|
| 授權(quán)有效期 | 1天 | 30天 |
注：
- 1、只有未過(guò)審核的應(yīng)用才處于測(cè)試級(jí)別。
- 2、應(yīng)用所屬開(kāi)發(fā)者授權(quán)應(yīng)用時(shí)，有效期為5年。
你可以在 “我的應(yīng)用>接口管理>授權(quán)機(jī)制” 上查詢當(dāng)前應(yīng)用的授權(quán)級(jí)別。也可以在這里申請(qǐng)?zhí)岣呤跈?quán)有效期。
開(kāi)發(fā)者可以通過(guò)兩種方式計(jì)算access_token的實(shí)效時(shí)間：
- 1、用戶授權(quán)時(shí)，oauth2/access_token接口返回的expires_in值就是access_token的生命周期；
- 2、從上述對(duì)應(yīng)表中，找到應(yīng)用所對(duì)應(yīng)的授權(quán)有效期，過(guò)期時(shí)間 = 用戶授權(quán)時(shí)間 + 授權(quán)有效期；
第三方開(kāi)發(fā)應(yīng)用需要具備一定的健壯性，調(diào)用接口時(shí)判斷接口的返回值，如果用戶的access_token失效，需要引導(dǎo)用戶重新授權(quán)。
失效原因有以下幾個(gè)：
- 1、用戶取消了對(duì)應(yīng)用的授權(quán)；
- 2、access_token自然過(guò)期；
- 3、用戶修改了密碼，凍結(jié)了對(duì)應(yīng)用的授權(quán)；
- 4、微博發(fā)現(xiàn)用戶帳號(hào)被盜，凍結(jié)了用戶對(duì)應(yīng)用的授權(quán)；
授權(quán)有效期的延續(xù)
授權(quán)有效期內(nèi)重新授權(quán)
如果用戶在授權(quán)有效期內(nèi)重新打開(kāi)授權(quán)頁(yè)授權(quán)（如果此時(shí)用戶有微博登錄狀態(tài)，這個(gè)頁(yè)面將一閃而過(guò)），那么微博會(huì)為開(kāi)發(fā)者自動(dòng)延長(zhǎng)access_token的生命周期，請(qǐng)開(kāi)發(fā)者維護(hù)新授權(quán)后得access_token值。
通過(guò)Refresh Token刷新授權(quán)有效期
除此之外，我們也提供了通過(guò) Refresh Token 刷新的方式來(lái)延續(xù)授權(quán)有效期，但需要注意的是：只有使用微博官方移動(dòng)SDK的移動(dòng)應(yīng)用，才可以從SDK的方法中獲取到 Refresh Token。
Refresh Token 是 Access Grants 的一種，在獲取 Access Token 時(shí)，認(rèn)證服務(wù)器將返回相應(yīng)的 Refresh Token，如果 Access Token 過(guò)期，就可以用 Refresh Token 去刷新。
Refresh Token 也是有有效期的，Refresh Token 的有效期目前為30天，在有效期內(nèi)隨時(shí)可以刷新。
通過(guò) Refresh Token 刷新得到的新的 Access Token ，其有效期等同于原來(lái)的有效期，即原來(lái) Access Token 的有效期是30天，則新獲得的也是30天。
簡(jiǎn)單來(lái)說(shuō)就是對(duì)于使用了微博移動(dòng)SDK的移動(dòng)應(yīng)用，授權(quán)（Access Token）30天有效，30天內(nèi)可續(xù)，從刷新時(shí)間點(diǎn)算起重新得到30天有效期。
1、當(dāng)你是使用微博官方移動(dòng)SDK的移動(dòng)應(yīng)用時(shí)，授權(quán)返回access_token的同時(shí)，還會(huì)多返回一個(gè)refresh_token：
{
"access_token": "SlAV32hkKG",
"remind_in": 3600,
"expires_in": 3600
"refresh_token": "QXBK19xm62"
}
2、當(dāng)你調(diào)用API接口返回 Access Token 過(guò)期時(shí)，你可以調(diào)用 oauth2/access_token 并傳入 refresh_token：
返回值
3、使用新獲得的Access Token調(diào)用API
使用OAuth2.0調(diào)用API
使用OAuth2.0調(diào)用API接口有兩種方式：
1、 直接使用參數(shù)，傳遞參數(shù)名為 access_token
2、在header里傳遞，形式為在header里添加 Authorization:OAuth2空格abcd，這里的abcd假定為Access Token的值，其它接口參數(shù)正常傳遞即可。
注：所有的微博開(kāi)放平臺(tái)接口都部署在weibo.com域下，僅有移動(dòng)端的授權(quán)接口在open.weibo.cn域。
授權(quán)中的其他功能
Scope
Scope是OAuth2.0新版授權(quán)頁(yè)提供的一個(gè)功能，通過(guò)scope，平臺(tái)將開(kāi)放更多的微博核心功能給開(kāi)發(fā)者，同時(shí)也加強(qiáng)用戶隱私保護(hù)，提升了用戶體驗(yàn)，用戶在新OAuth2.0授權(quán)頁(yè)中有權(quán)利選擇賦予應(yīng)用的功能。
Scope開(kāi)放的接口文檔：接口文檔
客戶端默認(rèn)回調(diào)頁(yè)
通常Mobile Native App沒(méi)有服務(wù)器回調(diào)地址，您可以在應(yīng)用控制臺(tái)授權(quán)回調(diào)頁(yè)處填寫(xiě)平臺(tái)提供的默認(rèn)回調(diào)頁(yè)，該頁(yè)面用戶不可見(jiàn)，僅用于獲取access token。
OAuth2.0客戶端默認(rèn)回調(diào)頁(yè)：https://api.weibo.com/oauth2/default.html
強(qiáng)制登錄
授權(quán)頁(yè)會(huì)默認(rèn)讀取當(dāng)前用戶的微博登錄狀態(tài)，如果你想讓用戶重新登錄，請(qǐng)?jiān)谡{(diào)用authorize接口時(shí)傳入?yún)?shù)：forcelogin=true，默認(rèn)不填寫(xiě)此參數(shù)相當(dāng)于forcelogin=false。
取消授權(quán)回調(diào)頁(yè)
開(kāi)發(fā)者可以在應(yīng)用控制臺(tái)填寫(xiě)取消授權(quán)回調(diào)頁(yè)，當(dāng)用戶取消你的應(yīng)用授權(quán)時(shí)，開(kāi)放平臺(tái)會(huì)回調(diào)你填寫(xiě)的這個(gè)地址。并傳遞給你以下參數(shù)，source：應(yīng)用appkey，uid ：取消授權(quán)的用戶，auth_end ：取消授權(quán)的時(shí)間
OAuth2.0相關(guān)資源
以下SDK包含了OAuth2.0及新版API接口
| 下載Android SDK | 下載iOS SDK | 下載WP7 SDK |
| 下載PHP SDK(由SAE維護(hù)) | 下載Java SDK | 下載Python SDK |
| 下載Flash SDK | 下載Javascript SDK | 下載C# SDK |
移動(dòng)開(kāi)發(fā)SDK說(shuō)明文檔
| Android SDK 說(shuō)明文檔 | iOS SDK 說(shuō)明文檔 | WP7 SDK 說(shuō)明文檔 |
其他參考資料
OAuth是一種國(guó)際通用的授權(quán)方式， OAuth2.0的官方技術(shù)說(shuō)明可參看 http://oauth.net/2/
如果你仍在使用Oauth1.0，請(qǐng)進(jìn)入瀏覽相關(guān)文檔。
OAuth2.0 錯(cuò)誤碼
微博OAuth2.0實(shí)現(xiàn)中，授權(quán)服務(wù)器在接收到驗(yàn)證授權(quán)請(qǐng)求時(shí)，會(huì)按照OAuth2.0協(xié)議對(duì)本請(qǐng)求的請(qǐng)求頭部、請(qǐng)求參數(shù)進(jìn)行檢驗(yàn)，若請(qǐng)求不合法或驗(yàn)證未通過(guò)，授權(quán)服務(wù)器會(huì)返回相應(yīng)的錯(cuò)誤信息，包含以下幾個(gè)參數(shù)：
- error: 錯(cuò)誤碼
- error_code: 錯(cuò)誤的內(nèi)部編號(hào)
- error_description: 錯(cuò)誤的描述信息
- error_url: 可讀的網(wǎng)頁(yè)URI，帶有關(guān)于錯(cuò)誤的信息，用于為終端用戶提供與錯(cuò)誤有關(guān)的額外信息。
錯(cuò)誤信息的返回方式有兩種：
1. 當(dāng)請(qǐng)求授權(quán)Endpoint：https://api.weibo.com/2/oauth2/authorize 時(shí)出現(xiàn)錯(cuò)誤，返回方式是：跳轉(zhuǎn)到redirect_uri，并在uri 的query parameter中附帶錯(cuò)誤的描述信息。
2. 當(dāng)請(qǐng)求access token endpoing:https://api.weibo.com/oauth2/access_token 時(shí)出現(xiàn)錯(cuò)誤，返回方式：返回JSON文本。例如：
OAuth2.0錯(cuò)誤響應(yīng)中的錯(cuò)誤碼定義如下表所示：
