English version for OAuth2.0

跳转至: 导航搜索

This document describes the various authentication and implementation processes of Renren. Third-party applications can use it to implement account login authorization, and access to all network API which provides rich features in order to enhance application functionality and social marketing capabilities!

目录

OAuth 2.0 introduction

Renren open platform use OAuth 2.0 as the authentication and authorization protocol. OAuth is an open standard that allows third-party applications’ users to access their information stored on the site resources (such as photos, videos, buddy lists) in the case of authorized, and during this process, the web site don’t have to tell user's account password to third-party applications.

Renren authorization process flowchart:

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

User login authorization

Server license

As for websites, station and client applications that have a separate server, you can be use Renren login authorization functions as follow:

网站操作流程2.png
服务端授权流程图.png
   Step 1- Register Application 

Register your open platform Application:Register Application and get APP ID, API KEY, Secret Key.

   Step 2-Get Authorization Code

Add Renren’s login button you’re your application (Download material). After the user clicks the button, they need to redirect their browser (pop-up window or you can open a new page) to Renren’s OAuth 2.0 authorization page. Parameter Description:

  • Request address :https://graph.renren.com/oauth/authorize
  • client_id:Parameter value is the API KEY that received in Developer Registration Center;
  • redirect_uri:After the authorization process, you need to jump back to the URL address, which must be after the Developer Registration Center website address;
  • response_type:This value is fixed at “code”;
  • scope:Optional. If you do not pass this parameter, it means you indicates the requesting user's default permissions. To request additional permissions, please use spaces to separate. Permissions list;
  • display:This parameter can configure Renren authorization page style, Parameter types: page, iframe, popup, touch, mobile. For specific usage and effects, please refer to:Authorizations Type Configuration

Example 1:

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

Example 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
  ('+' in the parameters of scope should be space(' ') which is displayed after the URL Encode operation!)

Note: Renren OAuth2.0 supports multiple methods to pass "client_id" and "client_secret", for detailed information, please visit here.


If the user clicks the "authorization and sign" consent authority, Renren OAuth2.0 will redirect user's browser to the redirect_uri parameter corresponds to the URL and Query returns an Authorization Code using 'code' parameter.
http://YOUR_CALBACK_URL?code=A_CODE_GENERATED_BY_SERVER

If the user does not agree authorization and close the authorization page directly, the application will not be authorized. If the user clicks the "Cancel" button, the browser will be redirected to the URL corresponding redirect_uri and Query take the appropriate error message.

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.

In this case, developers should provide appropriate page in order to guarantee the user experience.

   Step 3-get Access Token

After getting Authorization Code, you should continue to get Access Token。

Use HTTP POST to request OAuth 2.0’s Access Token Endpoint, needed parameters are:

  • Request address :https://graph.renren.com/oauth/token
  • grant_type: When using Authorization Code as Access Grant, this value is fixed at ”authorization_code”;
  • client_id: API Key that received in Developer Registration Center;
  • client_secret: Secret Key that received in Developer Registration Center. Secret Key is application secured information, please don’t use it outside the server code.;
  • redirect_uri:Should be consist with “redirect_uri” passed when getting Authorization Code;
  • code: Authorization Code received in the process above.

Example:

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


If the application is verified, Renren OAuth 2.0 will return information related to Access Token:

  • token_type: Received Token type, bearer or mac;
  • expires_in: Access Token’s valid time, Units of seconds;
  • refresh_token: When Access Token expires; you can use Refresh Token to refresh it;
  • user: User’s personal information, containing user’s id, “name”, “avatar”(containing four different sizes of “type”, ordered by “tiny”, “avatar”, “main”, “large”);
  • access_token:Received Access Token, the necessary parameter to call API;
  • scope: The final access scope of Access Token, namely the actual list of permissions granted to the user (User may cancel some request permission in the authorization page). For specific information about permissions, please refer to Permissions list.

Example:

{ "token_type":"bearer", "expires_in":2595096, "refresh_token":"127021|0.KAS3b8doSitHk6RLDtitb2VY8PjktTRA.229819774.1376381303243", "user":{ "id":229819700, "name":"Miss Zhang", "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", }


If the application validation error, Renren OAuth 2.0 will return HTTP 401 (Application authentication failure) or HTTP 400 (parameter error), and an error message will be returned in HTTP Body:

  • error:Error code. A detailed description of the error codes, Please refer to Error code
  • error_code: Internal code of error;
  • error_description: A description of the error code information;
  • error_uri: A readable page URI with information about the error, Used to provide end users with additional information about the errors.

Example:

{ "error": "invalid_grant", "error_code": 20204, "error_description": "Invalid authorization code: {Authorization_Code}" }
   Step 4- Submit 

Submit your website into the Audit stage.

If approved, your website can be formally launched. Website users can use Access Token call the appropriate API interface, and access to rich functions of Renren.

If the audit is not passed, aside from testers, all the users who login Renren will fail to call API.

Client licenses

For mobile client and desktop client that have no separate server, you can achieve the registration authority features in Renren as following:

客户端授权流程图.png

No separate server client process also uses OAuth 2.0 to Authorize Endpoint Renren to achieve user authentication and application verification。The only difference is that you need to specify "response_type" parameter to "token", but not the "code" like before:

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

When the user authentication and authorization applications passed, Renren OAuth2.0 will redirect the user's browser (via HTTP 302) to the redirect_uri parameter corresponds to the URL. Different from server process, the client processes directly returns Access Token in the URI Fragment (#access_token=...):

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

Note:('%7C ' in the parameters of access_token should be ('|') which is displayed after the URL Encode operation! You need to do the URL Decode operation before using the token in order to obtain the correct Token value)

Since the return of the Access Token is returned in the URI Fragment, only the client code (such as JavaScript that running in the browser, client code that supported by browser controls) can get Access Token.

Client certificate authority

Client certificate process is the application authentication processes that does not require user involved, so no user authorization is needed to obtain the Access Token directly. Access Token that received through the client certificate authority does not require calling the user authorized API, such as access to the Renren Recommended Resources’ API: /v2/share/hot/list

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

The specific method is when getting Access Token, set "grant_type" parameter to "client_credentials" Example:

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

Specific instructions for return contents, please refer to section 2.1Step 3。

Mobile terminal license registration

There are two ways to use OAuth2.0 authorization in Mobile phone platform side,

One is use variety of interfaces provided by Renren Open Platform directly, according to part ways 2.1,2.2,2.3 login operation. Another is to use the official package Renren open platform SDK for various mobile platforms

Download address:
  • Renren open source platform iOS SDK
  • Renren open source platform Android SDK

License page type configuration

When sending the request to the Renren OAuth2.0 authorization page “graph.renren.com / oauth / authorize”, you can configure the display parameters to return different styles of authorization page (if not sent, the default is the page style), parameters:

  • page: Apply to the Web client site, the minimum size (horizontal version: 575px * 405px), when the browser width is too narrow, the page will be adaptive to vertical version, the minimum size (290px * 580px);
  • ifame: Pop style, suitable for application of the station, the minimum size (595px * 425px);
  • touch: Suitable for mobile terminals, the minimum size (320px * 480px);
  • mobile: For the mobile terminal does not support the js, the minimum size (480 * 800px);

Example:

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

page style:

Page.png

iframe style:

Iframe.png

touch style:

Touch.png

mobile style:

Mobile.png

Access Token

Access Token Type Description

Renren OAuth2.0 currently supports two types of Access Token: Bearer and MAC. MAC type applies only API2.0 interfaces:

Interface name Advantage Disadvantage
Bearer Called simple, does not require the signature of the request. Request API requires use https protocol to ensure secure transmission of information.
Access Token valid for one month, after which you need to refresh Refresh Token.
MAC Do not rely on https protocol, no protocol encryption performance overhead. MAC computation needed.
Access Token effective long-term, you don’t need to refresh the Refresh Token


By default, you get Bearer type Access Token. If developers want to get the MAC type of Access Token, you need to designated 'token_type' parameter to 'mac' when obtaining token.

Example:

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 type of results to return:

{ "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" }

Specific instructions please visit MAC type of Access Token introduction.

Use of Access Token

After getting Access Token, you can call the REST API using Access Token. For more information, please visit API interface using instruction.

Access Token refreshing

For Bearer type Access Token, there will be situations that Token expired. When Access Token expired, the developer can use the Refresh Token to refresh the Access Token. Refresh Token Token is will not expire.

Refresh Access Token need to use HTTP POST request Renren OAuth 2.0 for Access Token Endpoint, the necessary parameters are:

  • grant_type: Use Refresh Token refresh Access Token, this value is "refresh_token";
  • refresh_token: Access Token bound to Refresh Token;
  • client_id: API Key obtained when Registration application in the Developer Center;
  • client_secret: Secret Key obtained when Registration application in the Developer Center。

Requests are as folloing:

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

If the application is verified, and the Refresh Token is also correct, Renren OAuth 2.0 will return Access Token related information:

{ "scope":"read_user_feed read_user_album", "token_type":"bearer", "expires_in":2593124, "refresh_token":"127012|0.KAS3b8doSitHk6RLDtitb2VY8PjktTRA.229819774.1376381303243", "user":{ "id":229819700, "name":"Ms. Zhang", "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" }

Specific instructions for returning contents, please refer to section 2.1 Step 3.

Security issue

Cross-Site Request Forgery (CSRF)

To prevent CSRF attacks, need to use the state of users to pass a unique identifier when requesting Renren OAuth 2.0 Authorize Endpoint. When authorize pages jump to rediret_uri identity, it will be returned unchanged in order to guarantee the security authorization process. Renren is strongly recommended to use this way to keep the user's state, to prevent CSRF attacks.

Example:

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

Do not return HTTP 302 in Application-specific 'redirect_uri', ie do not jump. For more information, please refer to OAuth 2.0 Agreement Chapter 10.

Forced switching Renren account

Browser that have used OAuth2.0 login authorization, click Renren login button, the login authorization page will not appear again. If the third-party applications need to force the user to switch account, you can request https://graph.renren.com/oauth/authorize when passing parameters "x_renew = true", the authorization login page will pop back up.

  • x_renew: Non required parameters. When this parameter is set to "true", the login authorization process will forcibly show the authorization page for switch Renren accounts; default is false.

Example:

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=指定用户的唯一标识& x_renew=true