人人OAuth 2.0文档
人人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协议第十章第十五节。