WeChat Login for Web Apps
Content
- Getting Started
- Authorization Process
- Step 1: Getting the
code
parameter- Example flow
- Customizing Your Login Page
- Step 2: Passing the code to get the
access_token
- Renewing Your Token
- Step 3: Using APIs with the
access_token
- FAQs
Getting Started
This feature lets users log into third-party sites on their computer by scanning a QR code displayed on the page, using their mobile phone. This reduces any friction new users may encounter in using your site, saving the time and hassle of having to remember yet another password.
WeChat Login for Web Apps is based on the OAuth 2.0 protocol. To use it, you must register a developer account via our management interface.
Once registered, you should get an AppID
and AppSecret
for your app by submitting your app on the portal. After your application has been approved, you can start using this API!
Authorization Process
The process works like this:
The third party redirects the user to a page hosted by WeChat containing a QR code. After the user permits the third party site to access their account, WeChat will redirect the user back to the site, passing along a temporary
code
parameter in the query string.Using this code parameter, along with the previously-obtained AppID and AppSecret, the third-party app can receive an
access_token
.Finally, the third party app can use this
access_token
to call other APIs, such as the one for retrieving the user's profile info.
Step 1: Getting the code
parameter
When a user selects the “Login with WeChat” option, the third-party site should link the user to a URL following the format below. This page will display a QR code that the user can scan.
https://open.weixin.qq.com/connect/qrconnect?appid=APPID&redirect_uri=REDIRECT_URI&response_type=code&scope=SCOPE&state=STATE#wechat_redirect
If an error appears after loading this URL, double-check the parameters passed. The domain in the redirect_ui
must match what was entered and approved for your app on our developer portal. Also, be sure to use the scope "snsapi_login"
.
Parameters
Parameter | Required | Explanation |
---|---|---|
appid |
Yes | The ID registered for your application. |
redirect_uri |
Yes | The URL the user will be redirected to after authorization. Must be urlencoded. |
response_type |
Yes | Use 'code' |
scope |
Yes | Comma-delimited list of scopes authorized by user. For web login, use 'snsapi_login' |
state |
No | This can be any state information you wish to preserve across the OAuth process, for example a token to prevent CSRF attacks. |
Response
If the user authorizes the login, the parameters passed will include both code and state information:
redirect_uri?code=CODE&state=STATE
If the user refuses to authorize the login, the parameters passed in the query string will only include state:
redirect_uri?state=STATE
Example Flow
The commerce website YiHaoDian uses this API to allow users to login using a WeChat account. First, the user opens this page on their site:
https://passport.yhd.com/wechat/login.do
Afterwards, the site redirects the user to something like:
https://open.weixin.qq.com/connect/qrconnect?appid=wxbdc5610cc59c1631&redirect_uri=https%3A%2F%2Fpassport.yhd.com%2Fwechat%2Fcallback.do&response_type=code&scope=snsapi_login&state=3d6be0a4035d839573b04816624a415e#wechat_redirect
Then, once the user scans the code on their phone and authorizes the login, we redirect them back to YiHaoDian, passing along the appropriate parameters:
https://passport.yhd.com/wechat/callback.do?code=CODE&state=3d6be0a4035d839573b04816624a415e
Customizing Your Login Page
To make the WeChat login process better match your website’s look and feel, we also support another way to display the QR code on your page, using JavaScript.
First, include this line in your site’s <head>
(this also supports HTTPS):
<script src="http://res.wx.qq.com/connect/zh_CN/htmledition/js/wxLogin.js"></script>
Next, in your code, instantiate WxLogin, passing the following parameters:
var obj = new WxLogin({
id:"login_container",
appid: "",
scope: "",
redirect_uri: "",
state: "",
style: "",
href: ""
});
Parameters
Parameter | Required | Explanation |
---|---|---|
id |
Yes | The container ID you wish to show the QR code within |
appid |
Yes | The ID registered for your application. |
scope |
Yes | Comma-delimited list of scopes authorized by user. For web login, use 'snsapi_login' |
redirect_uri |
Yes | The URL the user will be redirected to after authorization. Must be urlencoded. |
state |
No | This can be any state information you wish to preserve across the OAuth process, for instance a token to prevent CSRF attacks. |
style |
No | Either “black” or “white”, defaults to black. |
href |
No | See more info in the FAQ section at the bottom |
gulp
Step 2: Passing the code to get the access_token
After the user is redirected back to your site, you can take the passed ‘code’ and call the access_token API as follows:
https://api.weixin.qq.com/sns/oauth2/access_token?appid=APPID&secret=SECRET&code=CODE&grant_type=authorization_code
Important Note: Which URL to send my HTTP requests
Parameters
Parameter | Required | Explanation |
---|---|---|
appid |
Yes | The ID registered for your application. |
secret |
Yes | The AppSecret as defined in the developer portal |
code |
Yes | The code parameter obtained previously |
grant_type |
Yes | Use “authorization_code |
Response Fields
Example:
{ "access_token":"ACCESS_TOKEN",
"expires_in":7200,
"refresh_token":"REFRESH_TOKEN",
"openid":"OPENID",
"scope":"SCOPE",
"unionid": "o6_bmasdasdsad6_2sgVt7hMZOPfL" }
Parameters
Parameter | Explanation |
---|---|
access_token |
The access_token that you can now use when making other API calls. |
expires_in |
The amount of time after which this token will expire, expressed in seconds. |
refresh_token |
You can use this token to get a new access token, as defined below. |
openid |
The unique identifier for this user |
scope |
Comma-delimited list of scopes authorized by user. For web login, use 'snsapi_login' |
unionid |
This field may be displayed only when the application has been authorized by users’ userinfo. |
An error response will look something like this:
{"errcode":40029,"errmsg":"invalid code"}
Refer to Return Codes.
Renewing your token
If an access token exceeds its validity period (typically 2 hours), there are two methods to renew it:
- If the token has already expired, call the refresh_token endpoint to get a new one.
- If the token has not yet expired, just call refresh_token to keep the same token but extend its validity.
The refresh_token
's validity period is 30 days. After that, you will need to have the user re-authorize by scanning the login page QR code using WeChat.
Request Format
After obtaining a code, you can use this endpoint to get a new token.
Method: GET
https://api.weixin.qq.com/sns/oauth2/refresh_token?appid=APPID&grant_type=refresh_token&refresh_token=REFRESH_TOKEN
Important Note: Which URL to send my HTTP requests
Parameters
Parameter | Required | Explanation |
---|---|---|
appid |
Yes | Your AppID used for development |
grant_type |
Yes | Use 'refresh_token' |
refresh_token |
Yes | The refresh_token obtained earlier when you got the initial access_token . |
Response Format
{
"access_token":"ACCESS_TOKEN",
"expires_in":7200,
"refresh_token":"REFRESH_TOKEN",
"openid":"OPENID",
"scope":"SCOPE"
}
Parameters
Parameter | Explanation |
---|---|
access_token |
An access_token that you can now use for calling other APIs. |
expires_in |
The validity period of this token. |
refresh_token |
Another refresh_token you can use in the future. |
openid |
The user's openid |
scope |
Comma-delimited list of scopes authorized by user. |
Step 3: Using your access_token
Here are all the APIs you can use:
Scope | API endpoint | Explanation |
---|---|---|
snsapi_base |
/sns/oauth2/access_token |
Get an access_token given a code (as described above) |
snsapi_base |
/sns/oauth2/refresh_token |
Refresh an access_token given a refresh_token for a previously-authorized user (as described above) |
snsapi_base |
/sns/auth |
Check the validity period of an access_token |
snsapi_userinfo |
/sns/userinfo |
Get the user's profile info |
FAQ
Q: What's code
for?
A: The code
parameter is used to obtain the access_token
, which, after the user authenticates, can be used to call APIs. Your code
is only valid for 10 minutes, to protect the security of the authentication process.
Q: What's scope
for?
A: scope
represents the privileges the third-party app has. You can apply for these privileges on the Official Account Admin site.
Q: In building a custom login page, how does the style
parameter change the way the QR code appears?
A: There are two options you can use ("white"
or "black"
), depending on what best matches your custom login page's design.
Here's what they look like:
Q: On custom login pages, what's the href
parameter for? How can I control its appearance?
A: This reminds the user what they're logging into. You can style it by adding custom CSS to the page like this:
.impowerBox .qrcode {width: 200px;}
.impowerBox .title {display: none;}
.impowerBox .info {width: 200px;}
.status_icon {display:none}
.impowerBox .status {text-align: center;}
Here's what that might look like: