Authorization mechanism
The call of microblog open interface, such as microblogging, obtaining user basic information, obtaining popular microblog content, etc., all need to obtain user identity authentication. At present, OAuth2.0 is mainly used for user identity authentication of microblog open platform. In addition, in order to facilitate developers to develop and test their own applications, we also provide the identity authentication method of developers' own authorization, but the developers' own authorization is only applicable to the developers who own the application to call the interface.
OAuth2.0 Overview
For the authorization process of OAuth2.0 protocol, please refer to the following flow chart, where Client refers to third-party applications, Resource Owner refers to users, Authorization Server is the authorization server of Weibo open platform, and Resource Server is the API server of Weibo open platform.
Developers can first browse the interface document of OAuth2.0 to get familiar with the meaning of the interface and parameters, and then we will explain how to use OAuth2.0 according to the application scenario.
OAuth2.0 interface document
matters needing attention
- 1. The OAuth2.0 authorization interface can be used by any application without application. For the period of validity of authorization, please refer to the period of validity of authorization in this document.
- 2. For security reasons, developers need to fill in redirect_url (authorized callback address) on the platform website to use OAuth2.0. Fill in the address: "My apps>app info>advanced info" For the client, we also provide the default callback page address. Please see the function section of the authorization page for details.
Authorization interface
At present, the most complete authorization is divided into three steps: login - general authorization - advanced authorization (SCOPE). However, these three steps are not inevitable. When a user's microblog is in login status, the page will automatically jump to the general authorization page. "Advanced authorization" is also not necessary. If the developer does not apply for SCOPE permission, the system will automatically skip this step and call back to the third-party application. As long as SCOPE is used reasonably, developers need not worry about the page loss rate caused by increased operations. On the contrary, a clear authorization experience can gain users' trust.
At the same time, authorization items will become more organized. The previous ordinary permissions will be used as basic services, and users will no longer be aware of them. Those related to user privacy will be classified as advanced authorization. Users have the right to cancel authorization item by item, further enhancing privacy control.
Application scenarios
Developers need to select the applicable OAuth2.0 authorization process according to their respective application scenarios:
- 1. For PC side and Web site, please refer to: Authorization Code of Web site
- 2. Mobile applications can directly use the microblog mobile SDK to authorize by calling the microblog client (H5 authorization page will be called if microblog is not installed)
- 3. Developers can use their own authorization during the debugging phase
Authorization of Web site
1. Guide the user to the following address:
URL
https://api.weibo.com/oauth2/authorize?client_id=YOUR_CLIENT_ID&response_type=code&redirect_uri=YOUR_REGISTERED_REDIRECT_URI
2. If the user agrees to authorize, the page will jump to YOUR_REGISTERED_REDIRECT_URI/? code=CODE
URL
https://api.weibo.com/oauth2/access_token?client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET&grant_type=authorization_code&redirect_uri=YOUR_REGISTERED_REDIRECT_URI&code=CODE
Where client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET can be added to the header in basic mode, and the returned value
JSON
{ "access_token": "SlAV32hkKG", "remind_in": 3600, "expires_in": 3600 }
4. Use the obtained Access Token to call the API
Authorization of mobile applications
For mobile applications (mainly Mobile Native App), it is recommended to use the official mobile SDK.
Developer's own authorization
In order to facilitate developers' programming and debugging interfaces, developers can use developer authorization for themselves. In this way, developers do not need to frequently authorize their own applications to obtain authorization tokens before calling interfaces. In addition, the developer's authorized token is valid for 5 years.
The developer's own authorization has certain restrictions, that is, only when the owner account of the application authorizes the application under his own name can he enjoy this feature.
The developer's own authorization can be quickly obtained through the interface test tool, provided that the developer's account needs to be logged in to the microblog open platform, the applications under this account will be listed under the interface test tool, and then only the authorization tokens of the applications listed under the developer's name can be obtained.
Validity period of authorization
Under the OAuth2.0 authorization mechanism of the microblog open platform, the access_token obtained by a third party has an expiration time, usually 30 days.
Corresponding table of authorization level and OAuth2.0 access_token validity period:
| Authorization level |
test |
ordinary |
| Validity period of authorization |
1 day |
30 days |
Note:
- 1. Only unapproved applications are at the test level.
- 2. When the application developer authorizes the application, the validity period is 5 years.
You can "My Application>Interface Management>Authorization Mechanism" Query the authorization level of the current application on the.
Developers can calculate the effective time of access_token in two ways:
- 1. When the user authorizes, oauth2/access_token Interface returned expires_in Value is the lifecycle of access_token;
- 2. From the above corresponding table, find the authorization validity period corresponding to the application. Expiration time=user authorization time+authorization validity period;
Third party development applications need to be robust. When calling the interface, judge the return value of the interface. If the user's access_token fails, guide the user to re authorize.
The failure causes are as follows:
- 1. The user cancels the authorization of the application;
- 2. Access_token expires naturally;
- 3. The user has changed the password and frozen the authorization of the application;
- 4. Weibo found that the user account was stolen, freezing the user's authorization for the application;
Extension of validity period of authorization
Re authorization within the validity period of authorization
If the user re opens the authorization page for authorization within the validity period of authorization (if the user has Weibo login status at this time, this page will flash by), then Weibo will automatically extend the life cycle of access_token for the developer. Please maintain the access_token value after the new authorization.
Refresh the validity period of authorization through Refresh Token
In addition, we also provide a refresh token method to extend the validity period of the authorization, but we need to note that: Only mobile applications that use the official Weibo mobile SDK can obtain the Refresh Token from the SDK method.
Refresh Token is a kind of Access Grants. When obtaining an Access Token, the authentication server will return the corresponding Refresh Token. If the Access Token expires, you can use the Refresh Token to refresh.
The refresh token also has a validity period. The validity period of the refresh token is currently 30 days, and it can be refreshed at any time within the validity period.
The validity period of the new Access Token obtained by refreshing the Refresh Token is the same as the original validity period, that is, the validity period of the original Access Token is 30 days, and the new Access Token is also 30 days.
To put it simply, for mobile applications that use the microblog mobile SDK, the access token is valid for 30 days, renewable within 30 days, and the 30 day validity period is renewed from the refresh time point.
1. When you are a mobile app using the official mobile SDK of Weibo, when you are authorized to return access_token, you will also return an additional refresh_token:
JSON
{ "access_token": "SlAV32hkKG", "remind_in": 3600, "expires_in": 3600 "refresh_token": "QXBK19xm62" }
2. When you call the API interface and return that the Access Token has expired, you can call oauth2/access_token and pass in refresh_token:
URL
https://api.weibo.com/oauth2/access_token?client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET&grant_type=refresh_token&redirect_uri=YOUR_REGISTERED_REDIRECT_URI&refresh_token= …
Return value
JSON
{ "access_token": "SlAV32hkKG", "expires_in": 3600 }
3. Use the newly acquired Access Token to call the API
Use OAuth2.0 to call open APIs
There are two ways to call the API interface using OAuth2.0:
1. Directly use the parameter and pass the parameter name access_token
URL
https://api.weibo.com/2/statuses/public_timeline.json?access_token=abcd
2. It is passed in the header by adding the Authorization: OAuth2 space abcd in the header. The abcd here is assumed to be the value of the Access Token, and other interface parameters can be passed normally.
Other functions in authorization
Scope
Scope is a function provided by the new version of OAuth2.0 authorization page. Through scope, the platform will open more core functions of microblog to developers. At the same time, it will also strengthen user privacy protection and improve the user experience. Users have the right to choose the functions assigned to applications in the new OAuth2.0 authorization page.
Scope's open interface document: Interface document
Client default callback page
Generally, Mobile Native App does not have a server callback address. You can fill in the default callback page provided by the platform at the authorized callback page of the application console. This page is invisible to users and is only used to obtain access tokens.
OAuth2.0 client default callback page: https://api.weibo.com/oauth2/default.html
Force Login
The authorization page will read the microblog login status of the current user by default. If you want the user to log in again, please pass in the parameter: forcelogin=true when calling the authorize interface. By default, not filling in this parameter is equivalent to forcelogin=false.
Unauthorize callback page
Developers can fill in the authorization cancellation callback page on the application console. When a user cancels your application authorization, the open platform will call back the address you filled in. And passed to you the following parameters, source: application appkey, uid: user whose authorization is cancelled, auth_end: time when the authorization is cancelled
OAuth2.0 related resources
OAuth2.0 error code
In the microblog OAuth2.0 implementation, the authorization server will check the request header and request parameters of this request according to the OAuth2.0 protocol when receiving the authentication authorization request. If the request is illegal or the authentication fails, the authorization server will return the corresponding error information, including the following parameters:
- Error: error code
- Error_code: internal number of error
- Error_description: error description
- Error_url: a readable web page URI with information about errors, which is used to provide end users with additional information about errors.
There are two ways to return error messages:
1. When requesting authorization Endpoint: https://api.weibo.com/2/oauth2/authorize An error occurred while the return method is: jump to redirect_uri, and The error description information is attached to the query parameter of.
2. When requesting access token ending: https://api.weibo.com/oauth2/access_token An error occurred while returning the JSON text. For example:
JSON
{ "error": "unsupported_response_type", "error_code": 21329, "Error_description": "Unsupported ResponseType." }
The definition of error codes in OAuth2.0 error response is shown in the following table:
| Error code | Error number (error_code) | Error description |
| redirect_uri_mismatch | twenty-one thousand three hundred and twenty-two | Redirect address mismatch |
| invalid_request | twenty-one thousand three hundred and twenty-three | Illegal request |
| invalid_client | twenty-one thousand three hundred and twenty-four | Invalid client_id or client_secret parameter |
| invalid_grant | twenty-one thousand three hundred and twenty-five | The Access Grant provided is invalid, expired or revoked |
| unauthorized_client | twenty-one thousand three hundred and twenty-six | Client does not have permission |
| expired_token | twenty-one thousand three hundred and twenty-seven | Token expires |
| unsupported_grant_type | twenty-one thousand three hundred and twenty-eight | Unsupported GrantType |
| unsupported_response_type | twenty-one thousand three hundred and twenty-nine | Unsupported ResponseType |
| access_denied | twenty-one thousand three hundred and thirty | User or authorization server denied data access |
| temporarily_unavailable | twenty-one thousand three hundred and thirty-one | The service is temporarily inaccessible |
| appkey permission denied | twenty-one thousand three hundred and thirty-seven | Insufficient application permissions |
