OAuth2.0

跳转至: 导航搜索

English version for OAuth2.0

简介:本文档主要介绍了人人网的各种验证授权的实现流程。第三方应用可以借此实现人人账号的登录授权,同时进一步获得人人网开放API提供的丰富功能,全面提升应用的功能性和社交推广能力!


目录

OAuth 2.0 简介

人人开放平台使用OAuth 2.0作为验证与授权协议。OAuth是一个开放标准,允许第三方应用在用户授权的情况下访问其在网站上存储的信息资源(如照片,视频,好友列表),而这一过程中网站无需将用户的账号密码告诉给第三方应用。

人人授权流程图:

网站操作流程1.png
手机流操作流程.png

用户登录授权

服务端授权

对于拥有独立服务器的网站,站内应用和客户端,可以通过以下方式实现人人网的登录授权功能。

网站操作流程2.png
服务端授权流程图.png

Step 1

注册您的开放平台应用:注册应用。并获得APP ID, API KEY, Secret Key


Step 2

获取Authorization Code。

在应用中添加人人的登录按钮(素材下载)。用户点击按钮后需要重定向用户的浏览器(也可以弹出窗口或打开新页面)到人人OAuth 2.0的授权页面。参数说明:

  • 请求地址:https://graph.renren.com/oauth/authorize
  • client_id:参数值为开发者中心注册应用时获得的API KEY
  • redirect_uri:授权流程结束后要跳转回的URL地址,该地址必须在开发者中心注册的网站地址之后;
  • response_type:此值固定为“code”;
  • scope:可选。若不传递此参数表示请求用户的默认权限。若要请求其他权限则用空格进行分隔;
  • display:此参数可以配置人人网授权页的风格,参数类型有:page,iframe,popup,touch,mobile。具体用法和效果请参考第3节。

举例1:

https://graph.renren.com/oauth/authorize? client_id=YOUR_API_KEY&redirect_uri=YOUR_CALLBACK_URL&response_type=code

举例2:

https://graph.renren.com/oauth/authorize& client_id=YOUR_API_KEY&redirect_uri=YOUR_CALLBACK_URL& response_type=code&scope=read_user_album+read_user_feed&display=page
  (上述scope参数中的'+',是空格(' ')在URL Encode操作之后显示的结果!)

注:人人OAuth2.0支持多种传递“client_id”和“client_secret”的方式,详细信息请浏览这里

如果用户点击“授权并登录”同意授权,人人OAuth2.0会将用户的浏览器重定向到redirect_uri参数对应的URL上,并在Query中使用'code'参数返回一个Authorization Code。

http://YOUR_CALBACK_URL?code=A_CODE_GENERATED_BY_SERVER

如果用户直接关闭授权页面不同意授权,则应用将不会被授权。如果用户点击“取消”按钮,浏览器会被重定向到redirect_uri对应的URL上,并在Query中带上相应的错误信息。

http://YOUR_CALBACK_URL? error=access_denied& error_description=The+end-user+or+authorization+server+denied+the+request.& error_uri=http%3a%2f%2fgraph.renren.com%2foauth%2ferror%3ferror%3daccess_denied%26error_description%3dThe%2Bend-user%2Bor%2Bauthorization%2Bserver%2Bdenied%2Bthe%2Brequest.

这种情况,开发者需要提供合适的提示页面,以保证用户体验。


Step 3

得到Authorization Code之后,继续获得Access Token。

使用HTTP POST请求人人OAuth 2.0的Access Token Endpoint,所需的参数有:

  • 请求地址:https://graph.renren.com/oauth/token
  • grant_type:使用Authorization Code 作为Access Grant时,此值固定为“authorization_code”;
  • client_id:在开发者中心注册应用时获得的API Key;
  • client_secret:在开发者中心注册应用时获得的Secret Key。Secret Key是应用的保密信息,请不要将其嵌入到服务端以外的代码里;
  • redirect_uri:必须与获取Authorization Code时传递的“redirect_uri”保持一致;
  • code:上述过程中获得的Authorization Code。

举例:

https://graph.renren.com/oauth/token?grant_type=authorization_code& client_id=YOUR_API_KEY&redirect_uri=YOUR_CALLBACK_URL& client_secret=YOUR_SECRET_KEY&code=THE_CODE_FROM_ABOVE

如果应用验证通过,人人OAuth 2.0会返回Access Token相关的信息:

  • token_type:获得的Token类型,bearer或者mac;
  • expires_in:Access Token的有效期,单位为秒;
  • refresh_token:当Access Token过期后,可以用Refresh Token对其进行刷新;
  • user:用户的个人信息,包含用户id,名称“name”,头像“avatar”(包含四种大小不同的尺寸“type”,大小依次为:“tiny”,“avatar”,“main”,“large”);
  • access_token:获取的Access Token,是调用人人API必需的参数;
  • scope:Access Token最终的访问范围,既用户实际授予的权限列表(用户在授权页面时,有可能会取消掉某些请求的权限)。关于权限的具体信息请参考权限列表

举例:

{ "token_type":"bearer", "expires_in":2595096, "refresh_token":"127021|0.KAS3b8doSitHk6RLDtitb2VY8PjktTRA.229819774.1376381303243", "user":{ "id":229819700, "name":"二小姐", "avatar":[ { "type":"avatar", "url":"http://hdn.xnimg.cn/photos/hdn121/20130805/2055/h_head_KFTQ_d536000000d0111b.jpg" }, { "type":"tiny", "url":"http://hdn.xnimg.cn/photos/hdn221/20130805/2055/tiny_jYQe_ec4300051e7a113f.jpg" }, { "type":"main", "url":"http://hdn.xnimg.cn/photos/hdn121/20130805/2055/h_main_ksPJ_d536000000d0111b.jpg"}, { "type":"large", "url":"http://hdn.xnimg.cn/photos/hdn121/20130805/2055/h_large_yxZz_d536000000d0111b.jpg" } ] }, "access_token":"127066|6.08718aa138db0578dda3250f33bads6e.2592000.1378976400-229819774" "scope":"read_user_feed read_user_album", }

如果应用验证出错,人人OAuth 2.0则返回HTTP 401(应用验证失败)或HTTP 400(参数错误),并在HTTP Body中返回错误信息:

  • error:错误码。错误码的详细说明,请点错误码
  • error_code:错误的内部编码;
  • error_description:对错误码的说明信息;
  • error_uri:一个可读的网页URI,带有关于错误的信息,用来为终端用户提供与错误有关的额外信息。

举例:

{ "error": "invalid_grant", "error_code": 20204, "error_description": "Invalid authorization code: {Authorization_Code}" }

Step 4

提交您的网站进入审核阶段

如果审核通过,您的网站就可以正式上线了。网站可以利用用户的Access Token调用相应的API接口,实现人人网丰富的接入功能。

如果审核未通过,除测试用户外其他人人网用户登录后都会无法正常调用API。

客户端授权

对于没有单独服务器的手机客户端和桌面客户端,可以通过以下方式实现人人网的登录授权功能。

客户端授权流程图.png

无单独服务器的客户端流程同样使用人人OAuth 2.0的Authorize Endpoint来实现用户验证和应用验证。唯一不同点是需要指定”response_type”参数为”token”,而不是之前的”code”:

https://graph.renren.com/oauth/authorize? client_id=YOUR_API_KEY&redirect_uri=YOUR_CALLBACK_URL&response_type=token

当用户验证和应用授权通过后,人人OAuth2.0会将用户的浏览器重定向(通过HTTP 302)到redirect_uri参数对应的URL上。与服务端流程不同的是,客户端流程在URI Fragment中直接返回Access Token(#access_token=...):

http://YOUR_CALLBACK_URL #access_token=1000%7C5.a6b7dbd428f731035f771b8d15063f61.86400.1292922000-222209506 &expires_in=64090

(上述access_token参数中的'%7C是竖线(|)在URL Encode操作之后显示的结果,在使用token前需要进行URL Decode操作以获得正确的Token值)


由于返回的Access Token是在URI Fragment中返回,只有客户端代码(例如运行与浏览器中的JavaScript、有浏览器控件支持的客户端代码)才可以获取Access Token。

客户端凭证授权

客户端凭证流程是不需要用户参与的应用验证的流程,因此无需用户授权便可直接获取Access Token。通过客户端凭证授权得到的Access Token只能调用不需要用户授权的公共API,比如获取人人推荐资源的API: /v2/share/hot/list。

客户端凭证授权流程图.png

具体方法为在获取Access Token时指定“grant_type”参数为“client_credentials”

举例:

https://graph.renren.com/oauth/token? client_id=YOUR_API_KEY&client_secret=YOUR_SECRET_KEY&redirect_uri=YOUR_CALLBACK_URL& grant_type=client_credentials

返回内容的具体说明请参考2.1节Step 3。

移动终端授权登录

移动端手机平台的人人OAuth2.0授权有两种方式。

  • 一种是直接使用人人网开放平台提供的各种接口,按照2.1、2.2、2.3部分的方式进行登录操作。
  • 另一种是使用人人网开放平台官方封装的基于各种移动系统平台的SDK,下载地址_sdk:
    • 人人开放平台开源iOS SDK
    • 人人开放平台开源Android SDK

授权页类型配置

在向人人OAuth2.0 授权页graph.renren.com/oauth/authorize发送请求时,可以配置display参数以返回不同风格的授权页(如不发送,默认是page风格),参数有:

  • page: 适用于Web端网站,最小尺寸(横版:575px*405px),当浏览器宽度过窄时,会页面会自适应成纵版,最小尺寸(290px*580px);
  • ifame: 弹窗样式,适用于站内应用,最小尺寸(595px*425px);
  • touch: 适用于移动终端,最小尺寸(320px*480px);
  • mobile: 适用于不支持js的移动终端,最小尺寸(480*800px);

举例:

https://graph.renren.com/oauth/authorize? client_id=YOUR_API_KEY&redirect_uri=YOUR_CALLBACK_URL&response_type=code &display=page

page 风格:

Page.png

iframe 风格:

Iframe.png

touch 风格:

Touch.png

mobile 风格:

Mobile.png

Access Token

Access Token 类型介绍

目前人人OAuth2.0支持Bearer和MAC两种类型的Access Token。其中MAC类型只适用于API2.0接口:

  • Bearer 介绍
    • 优点:
      • 调用简单,不需要对请求进行签名。
    • 缺点:
      • 请求API需要使用https协议保证信息传输安全。
      • Access Token有效期一个月,过期后需要使用Refresh Token进行刷新。
  • MAC 介绍
    • 优点:
      • 不依赖https协议,无协议加密带来的性能开销。
      • Access Token长期有效,无需使用Refresh Token刷新。
    • 缺点:
      • 需要进行MAC计算。

默认情况下,您会获得Bearer类型的Access Token。如果开发者想要获得MAC类型的Access Token,需要在获取token时指定'token_type'参数为'mac'。

举例:

https://graph.renren.com/oauth/token?grant_type=authorization_code&token_type=mac& client_id=YOUR_API_KEY&redirect_uri=YOUR_CALLBACK_URL& client_secret=YOUR_SECRET_KEY&code=THE_CODE_FROM_ABOVE

MAC类型下返回的结果:

{ "mac_algorithm":"hmac-sha-1", "mac_key":"6c590a5e2c6748d297770a14e2f239d3", "scope":"read_user_feed read_user_album", "token_type":"mac", "user":{ "id":2238192232, "name":"QianLong", "avatar":[ {"type":"avatar", "url":"http://hdn.xnimg.cn/photos/hdn121/20130705/2055/h_head_KFTQ_d536000000d0111a.jpg"}, {"type":"tiny", "url":"http://hdn.xnimg.cn/photos/hdn221/20130705/2055/tiny_jYQe_ec4300051e7a113e.jpg" }, {"type":"main", "url":"http://hdn.xnimg.cn/photos/hdn121/20130705/2055/h_main_ksPJ_d536000000d0111a.jpg" }, {"type":"large", "url":"http://hdn.xnimg.cn/photos/hdn121/20130705/2055/h_large_yxZz_d536000000d0111a.jpg" } ] }, "access_token":"127089|2.nVvgz3cjNLOvCsVDTp0khw6rI4AejbHs.229819774.1326448901423" }

具体说明请浏览MAC类型的Access Token 介绍

Access Token 使用

获得Access Token后,可以Access Token调用REST API。详细信息请浏览REST API接口使用说明

Access Token 刷新

对于Bearer类型的Access Token,会存在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。

请求如下:

https://graph.renren.com/oauth/token? grant_type=refresh_token& refresh_token= Refresh Token & client_id= YOUR_API_KEY & client_secret= YOUR_SECRET_KEY

如果应用验证通过,并且Refresh Token也正确,人人OAuth 2.0会返回Access Token相关的信息:

{ "scope":"read_user_feed read_user_album", "token_type":"bearer", "expires_in":2593124, "refresh_token":"127012|0.KAS3b8doSitHk6RLDtitb2VY8PjktTRA.229819774.1376381303243", "user":{ "id":229819700, "name":"二小姐", "avatar":[ { "type":"avatar", "url":"http://hdn.xnimg.cn/photos/hdn121/20130805/2055/h_head_KFTQ_d536000000d0111b.jpg" }, { "type":"tiny", "url":"http://hdn.xnimg.cn/photos/hdn221/20130805/2055/tiny_jYQe_ec4300051e7a113f.jpg" }, { "type":"main", "url":"http://hdn.xnimg.cn/photos/hdn121/20130805/2055/h_main_ksPJ_d536000000d0111b.jpg"}, { "type":"large", "url":"http://hdn.xnimg.cn/photos/hdn121/20130805/2055/h_large_yxZz_d536000000d0111b.jpg" } ] }, "access_token":"123389|6.409c58cffd57c88d456342ae77ef60ff.2592000.1378980000-229819774" }

返回内容的具体说明请参考2.1节 Step 3。

安全问题

跨站请求伪造 (CSRF)

为了防止CSRF攻击,在请求人人OAuth 2.0 Authorize Endpoint的时候,需要使用state传递一个用户的唯一标识。授权页面在跳转到rediret_uri时这个标识会被原样返回,以保证授权流程中的安全性。人人网强烈推荐使用这种方式来保持用户的状态,防止CSRF攻击。

举例:

https://graph.renren.com/oauth/token?grant_type=authorization_code& client_id=YOUR_API_KEY&redirect_uri= https://www.example.com/callback & client_secret=YOUR_SECRET_KEY&code=THE_CODE_FROM_ABOVE&state=指定用户的唯一标识

Redirect_URI

应用指定的'redirect_uri'不要返回HTTP 302,即不要跳转。详细信息请参考OAuth 2.0协议第十章第十五节

强制切换人人账号

已经使用OAuth2.0登录授权后的浏览器,点击人人登录的按钮后,不会再次出现登录授权页面。 如果第三方应用需要强制用户切换账号,可以在请求https://graph.renren.com/oauth/authorize 时传递参数“x_renew=true”,这样登录授权页面会重新弹出。

  • x_renew:非必须参数。此参数为“true”时,强行使授权流程出现登录授权页,用于切换人人账号;默认为false。

举例:

https://graph.renren.com/oauth/authorize?response_type=code&client_id=YOUR_API_KEY& redirect_uri=YOUR_CALLBACK_URL&state=指定用户的唯一标识&x_renew=true