人人OAuth 2.0文檔已經升級，老文檔請瀏覽 老Auhentication文檔。
人人開放平臺使用OAuth 2.0作爲驗證與授權協議。我們支持一系列OAuth 2.0驗證授權流程，支持網站、站內應用、手機客戶端、桌面客戶端。本文檔概述瞭如何使用各種人人OAuth 2.0的各種驗證授權流程，樣例代碼使用PHP作爲服務端編程語言，HTML/JavaScript作爲客戶端編程語言。樣例代碼非常直觀，也可以很容易的翻譯成其他編程語言。
目錄[隱藏] |
[編輯] 用戶登錄
人人開放平臺支持3種不同的OAuth 2.0驗證與授權流程：
- 服務端流程（協議中Authorization Code Flow）。此流程適用於在Web服務端調用REST API的的應用。例如：網站，站內應用。
- 客戶端流程（協議中Implicit Flow）。注意：此流程適用於在客戶端調用REST API的應用。例如：後端無Web Server支持的手機客戶端和桌面客戶端，運行於瀏覽器內部的JavaScript、ActionScript應用（瀏覽器插件、純Flash應用）。
- 用戶名密碼流程（協議中Resource Owner Password Credentials Flow）。此流程適用於無法使用瀏覽器發起服務端和客戶端驗流程的應用。
無論你使用那個流程，人人OAuth 2.0都會涉及到了三個步驟：
- 用戶驗證：確保用戶是誰；
- 應用授權：確保用戶知道他授予什麼樣的數據和權限給您的應用；
- 應用驗證：確保用戶授予權限的應用是您的應用，而不是其他應用。
當完成這些步驟後，您的應用可以獲得一個用戶的Access Token。使這個Access Token，您的應用可以獲取這個用戶的信息，並可以以這個用戶的身份做出相應的動作（髮狀態、上傳照片）。
[編輯] 服務端流程
登錄流程開始於重定向用戶瀏覽器（如果需要的話，可以彈出窗口或打開新頁面）到人人OAuth 2.0的Authorize Endpoint，並傳遞三個必須參數
- client_id：必須參數。在開發者中心註冊應用時獲得的API Key。
- redirect_uri：流程結束後要跳轉回得URL。redirect_uri所在的域名必須在開發者中心註冊應用後，填寫在編輯屬性選項卡中填寫到服務器域名中，人人OAuth2.0用以檢查跳轉的合法性。關於redirect_uri的驗證方式的詳細信息請參考 redirect_uri驗證配置。
- response_type：必須參數。服務端流程，此值固定爲“code”。
如果用戶已經登錄，人人OAuth 2.0會校驗存儲在用戶瀏覽器中的Cookie。如果用戶沒有登錄，人人OAuth 2.0會爲用戶展示登錄頁面，讓用戶輸入用戶名和密碼：
當人人OAuth 2.0成功驗證用戶之後，會爲用戶展示授權頁面，讓用戶爲應用授權：
默認情況下，會要求用戶授予用於訪問基本信息的權限，例如用戶公共信息、好友關係等。如果應用需要的權限超過基本信息權限，就需要要求用戶授予深層次的權限。這個過程是通過添加人人OAuth 2.0 'scope'請求參數實現的：
- scope：非必須參數。以空格分隔的權限列表，若不傳遞此參數，代表請求用戶的默認權限。全部權限請參考'權限列表'。
下面的例子展示瞭如何要求用戶授予訪問用戶的相冊、新鮮事的權限：
注意：上述scope參數中的'+'，是空格（' '）的URL Encode編碼。
如果用戶不同意授權（點擊關閉），應用將不會被授權。人人OAuth2.0會將用戶的瀏覽器重定向（通過HTTP 302）到redirect_uri參數對應的URL上，並在Query中帶上相應的錯誤信息。
如果用戶同意授權（點擊連接），應用將會被授權。人人OAuth2.0會將用戶的瀏覽器重定向（通過HTTP 302）到redirect_uri參數對應的URL上，並在Query中使用'code'參數返回一個Authorization Code。
Authorize Code可以在redirect_uri後端程序中獲得（例如：Java request.getParameter("code");）。獲得到Authorization Code後，你可以進行流程的下一步—應用驗證，以便獲得可以調用REST API的Access Token。
應用驗證需要使用HTTP POST請求人人OAuth 2.0的Access Token Endpoint，並需要帶上一系列需要的參數：
- grant_type：使用Authorization Code 作爲Access Grant時，此值爲“authorization_code”。
- code：上述過程中獲得的Authorization Code；
- client_id：在開發者中心註冊應用時獲得的API Key;
- client_secret：在開發者中心註冊應用時獲得的Secret Key。此值不要嵌入到任何要發佈到服務端以外的代碼裏（這種場景應該使用客戶端流程）;
- redirect_uri：必須與獲取Authorization Code時傳遞的“redirect_uri”保持一致。
注意：人人OAuth2.0支持多種傳遞“client_id”和“client_secret”的方式，包括：URI Query Parameter、Form-Encoded Body Parameter和RFC2617定義的HTTP Basic Authentication，詳細信息請瀏覽Client Authenticated。
如果應用驗證通過（client_id與client_secret匹配，redirect_uri與獲取Authorization Code時傳遞的redirect_uri保持一致），並且從用戶獲取的Authorization Code也正確，人人OAuth 2.0會返回Access Token相關的信息：
- access_token：獲取的Access Token；
- expires_in：Access Token的有效期，以秒爲單位；
- refresh_token：用於刷新Access Token 的 Refresh Token，長期有效，不會過期；
- scope：Access Token最終的訪問範圍，既用戶實際授予的權限列表（用戶在授權頁面時，有可能會取消掉某些請求的權限）。關於權限的具體信息請參考權限列表。
如果應用驗證過程中出錯，人人OAuth 2.0將返回HTTP 401（應用驗證失敗）或HTTP 400（參數錯誤），並在HTTP Body中返回錯誤信息：
- error：錯誤碼，有關錯誤碼的詳細信息請瀏覽錯誤碼；
- error_description：一段人類可讀的文字，用來幫助理解和解決發生的錯誤；
- error_uri：一個人類可讀的網頁URI，帶有關於錯誤的信息，用來爲終端用戶提供與錯誤有關的額外信息。
下圖展示了服務端流程HTTP請求的全過程：
下面的PHP示例代碼簡要展示了服務端流程，並考慮了CSRF攻擊的防範工作：
[編輯] 客戶端流程
客戶端流程同樣使用人人OAuth 2.0的Authorize Endpoint來實現用戶驗證和應用驗證。唯一不同點是需要指定'response_type'參數爲'token'：
與服務端流程一樣，可以使用'scope'參數來請求深層次權限，實現應用授權：
與服務端流程一樣，當用戶驗證和應用授權通過後，人人OAuth2.0會將用戶的瀏覽器重定向（通過HTTP 302）到redirect_uri參數對應的URL上。與服務端流程不同的是，客戶端流程不會返回code參數，而是在URI Fragment中返回Access Token（#access_token=...）：
由於返回的Access Token是在URI Fragment中返回，只有客戶端代碼(例如：例如運行與瀏覽器中的JavaScript、有瀏覽器控件支持的客戶端代碼)纔可以獲取Access Token。
應用驗證是通過驗證'redirect_uri'實現的，關於redirect_uri的驗證方式的詳細信息請參考 redirect_uri驗證配置。
下圖展示了客戶端流程HTTP請求的全過程：
下面的HTML/JavaScript示例代碼簡要展示了客戶端流程：
[編輯] 用戶名密碼端流程
注意：使用用戶名密碼端流程的權限需要提前申請，有關申請細節參見 申請Resource Owner Password Credentials Access Grant。
用戶名密碼流程需要使用HTTP POST請求人人OAuth 2.0的Access Token Endpoint，並需要帶上一系列需要的參數：
- grant_type：使用Resource Owner Password Credentials作爲Access Grant時，此值爲“password”。
- username：人人網用戶的用戶名；
- password：人人網用戶的密碼；
- client_id：在開發者中心註冊應用時獲得的API Key;
- client_secret：在開發者中心註冊應用時獲得的Secret Key。此值不要嵌入到任何要發佈到服務端以外的代碼裏（這種場景應該使用客戶端流程）;
- scope：非必須參數。以空格分隔的權限列表，若不傳遞此參數，代表請求用戶的默認權限。全部權限請參考'權限列表'。
注意：人人OAuth2.0支持多種傳遞“client_id”和“client_secret”的方式，包括：URI Query Parameter、Form-Encoded Body Parameter和RFC2617定義的HTTP Basic Authentication，詳細信息請瀏覽Client Authenticated。
請求如下：
https://graph.renren.com/oauth/token?
grant_type=password&
username=USERNAME&
password=PASSWORD&
client_id=YOUR_API_KEY&
client_secret=YOUR_SECRET_KEY&
scope=...
如果用戶驗證通過（用戶名密碼正確），並且應用驗證通過，人人OAuth 2.0會返回Access Token相關的信息：
- access_token：獲取的Access Token；
- expires_in：Access Token的有效期，以秒爲單位；
- refresh_token：用於刷新Access Token 的 Refresh Token，長期有效，不會過期；
- scope：Access Token最終的訪問範圍，既用戶實際授予的權限列表（用戶在授權頁面時，有可能會取消掉某些請求的權限）。關於權限的具體信息請參考權限列表。
[編輯] 使用Access Token
獲得Access Token後，可以Access Token調用REST API。詳細信息請瀏覽REST API以及使用Access Token調用REST API
[編輯] 刷新Access Token
Access Token生命週期較短，在某些場景下，應用需求的Access Token的生命期超過一個Access Token的生命期，就可以使用Refresh Token來刷新Access Token，Refresh Token是一個不過期的Token。
刷新Access Token需要使用HTTP POST請求人人OAuth 2.0的Access Token Endpoint，並需要帶上一系列需要的參數：
- grant_type：使用Refresh Token刷新Access Token時，此值爲“refresh_token”。
- refresh_token：獲取Access Token時，同時下發的Refresh Token；
- client_id：在開發者中心註冊應用時獲得的API Key;
- client_secret：在開發者中心註冊應用時獲得的Secret Key。此值不要嵌入到任何要發佈到服務端以外的代碼裏（這種場景應該使用客戶端流程）;
注意：人人OAuth2.0支持多種傳遞“client_id”和“client_secret”的方式，包括：URI Query Parameter、Form-Encoded Body Parameter和RFC2617定義的HTTP Basic Authentication，詳細信息請瀏覽Client Authenticated。
請求如下：
如果應用驗證通過，並且Refresh Token也正確，人人OAuth 2.0會返回Access Token相關的信息：
- access_token：獲取的Access Token；
- expires_in：Access Token的有效期，以秒爲單位；
- refresh_token：用於刷新Access Token 的 Refresh Token，長期有效，不會過期；
- scope：Access Token最終的訪問範圍，既用戶實際授予的權限列表（用戶在授權頁面時，有可能會取消掉某些請求的權限）。關於權限的具體信息請參考權限列表。
[編輯] 公共主頁登錄
每一個公共主頁都有若干個管理員，只有公共主頁的管理員授予應用'admin_page'權限，應用才能以管理員的身份管理公共主頁（髮狀態、上傳照片等）：
管理員授予應用權限後，應用可以使用管理員的Access Token調用公共主頁類API。
[編輯] 應用類型
人人網開放平臺提供了上述的OAuth 2.0驗證與授權流程以支持不同類型的應用，包括：網站、站內應用、手機客戶端和桌面客戶端。
[編輯] 網站
網站接入開發攻略詳細介紹瞭如何使用OAuth 2.0在網站上實現登錄和賬號綁定。
[編輯] 站內應用
站內應用開發攻略詳細介紹瞭如何使用OAuth 2.0開發彈層授權，以及集成應用到人人網的開發經驗。
[編輯] 手機客戶端
手機客戶端開發攻略詳細介紹瞭如何使用OAuth 2.0在手機上實現登錄和賬號綁定，同時也介紹了在手機上實現單點登錄的SSO API的使用。
[編輯] 桌面客戶端
由於OAuth 2.0協議定義的桌面客戶端的授權流程，用戶體驗方面過於複雜，所以桌面客戶端應用可以在應用中嵌入瀏覽器控件（很多框架都支持嵌入瀏覽器，例如：.NET、AIR、Cocoa等）使用客戶端流程。
由於大部分桌面客戶端軟件是沒有後端沒有Web服務器支持，沒辦法提供一個'redirect_uri'，所以人人網爲沒有Web服務器的客戶端應用提供了一個通用的URL：http://graph.renren.com/oauth/login_success.html。
流程如下：
- 在應用中嵌入一個瀏覽器控件，並使用客戶端流程定向控件到人人OAuth 2.0 Authorize Endpoint（https://graph.renren.com/oauth/authorize）：
- 經過用戶驗證、應用授權，人人OAuth 2.0將把瀏覽器控件定向導'redirect_uri'（http://graph.renren.com/oauth/login_success.html），並在URI Fragment中追加Access Token：
- 當應用發現瀏覽器的控件的URL跳轉到這個URL上時，從URL中解析出Access Token。
[編輯] 安全考慮
[編輯] 跨站請求僞造 (CSRF)
CSRF通過僞裝來自受信任用戶的請求來利用受信任的網站。爲了防止CSRF攻擊，在請求人人OAuth 2.0 Authorize Endpoint的時候，需要使用state傳遞一個用戶的唯一標示，這個標示在調轉到rediret_uri時會被原樣返回。人人網強烈推薦使用這種方式來保持用於的狀態，防止CSRF攻擊。
[編輯] Redirect_URI
應用指定的'redirect_uri'不要返回HTTP 302，既不要跳轉。詳細信息請參考OAuth 2.0協議第十章第十五節。