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：
As for websites, station and client applications that have a separate server, you can be use Renren login authorization functions as follow:
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。
('+' 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.
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.
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.
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.
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.
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.
For mobile client and desktop client that have no separate server, you can achieve the registration authority features in Renren as following:
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:
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=...):
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)
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
The specific method is when getting Access Token, set "grant_type" parameter to "client_credentials" Example:
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
- 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);
Access Token Type Description
Renren OAuth2.0 currently supports two types of Access Token: Bearer and MAC. MAC type applies only API2.0 interfaces:
|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.
MAC type of results to return:
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:
If the application is verified, and the Refresh Token is also correct, Renren OAuth 2.0 will return Access Token related information：
Specific instructions for returning contents, please refer to section 2.1 Step 3.
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.
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.