WeChat OAuth2.0 Mobile Login Integration Guide

Reference: WeChat Open Platform documentation (https://open.weixin.qq.com/...).

Preparation

The mobile app login is built on the OAuth2.0 standard. Before integration, register a developer account on the WeChat Open Platform, obtain an approved AppID and AppSecret, and ensure the app has passed the WeChat login review.

1. Only native login is supported; users must have the WeChat client installed.

2. For Android, always display the WeChat login button and guide users to install the client if it is missing.

3. For iOS, due to App Store review guidelines, first check isWXAppInstalled and hide the button for users without the client, offering alternative login methods.

Authorization Process Overview

WeChat OAuth2.0 enables users to log in to third‑party apps using their WeChat identity. After user consent, the third‑party receives an access_token that can be used to call WeChat Open Platform APIs for basic user information and other services.

The flow uses the authorization_code grant type and consists of the following steps:

1. The third‑party initiates an authorization request; the user authorizes and WeChat redirects back with a temporary code parameter.

2. The server exchanges the code together with AppID and AppSecret for an access_token .

3. The access_token is used to call protected APIs and obtain user data.

Step 1 – Request Authorization Code

Using the WeChat SDK, the mobile app launches the WeChat client for login. After the user approves, WeChat returns a code to the app, which then forwards it to its backend.

Parameters:

appid (required): the unique application identifier.

scope (required): e.g., snsapi_userinfo to obtain user info.

state (optional): a random string for CSRF protection.

Response example:

ppid: wxd477edab60670232
scope: snsapi_userinfo
state: wechat_sdk_demo

Result codes: ERR_OK = 0 (user consent), ERR_AUTH_DENIED = -4 (denied), ERR_USER_CANCEL = -2 (canceled).

Step 2 – Exchange Code for Access Token

Make a GET request to:

https://api.weixin.qq.com/sns/oauth2/access_token?appid=YOUR_APPID&secret=YOUR_APPSECRET&code=CODE&grant_type=authorization_code

Required parameters: appid , secret , code , grant_type=authorization_code .

Successful JSON response:

{
  "access_token":"ACCESS_TOKEN",
  "expires_in":7200,
  "refresh_token":"REFRESH_TOKEN",
  "openid":"OPENID",
  "scope":"SCOPE",
  "unionid":"UNIONID"
}

Key fields:

access_token : credential for API calls.

expires_in : token validity in seconds.

refresh_token : token to obtain a new access token.

openid : unique identifier of the authorized user.

scope : granted permission scopes.

unionid : appears only when the user has linked a public account.

Step 3 – Retrieve User Info

Call the user‑info endpoint with a valid token:

https://api.weixin.qq.com/sns/userinfo?access_token=ACCESS_TOKEN&openid=OPENID&lang=zh_CN

Required: a non‑expired access_token and the user must have granted the requested scope.

Typical response fields include nickname , openid , and unionid .

Step 4 – WeChat Login and Phone‑Number Binding

After obtaining the user’s WeChat OpenID, the backend checks whether the account is already bound to a phone number:

{"code":0,"msg":"成功","data":{"token":"","is_bind":false}}

If is_bind is false, the client must prompt the user to bind a phone number via the /user/wechat/bind API.

Step 5 – Re‑Login with Existing Token

On subsequent logins, the client sends the previously stored access_token . The server validates the token with WeChat; if it is still valid, login proceeds without re‑authorizing, otherwise a new authorization flow is started.

Step 6 – Test Cases

Comprehensive test scenarios cover combinations of phone‑login, WeChat binding, multiple accounts, missing WeChat client, network conditions, and failure handling to ensure robust integration.

Images and additional reference links were included in the original document for visual guidance.