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