RootAuth supports using a verified WeChat Official Account as a third-party login and sign-up method. After it is enabled, users can scan a QR code with the WeChat app on a PC login or sign-up page, follow the Official Account, and automatically complete sign-up or login.
Path: Log in to the RootAuth console → open the target application → click Configuration in the top navigation bar → Authentication Configuration → select Providers
1. Before You Start
Before configuring WeChat login, make sure you have completed the following:
- You have a verified WeChat Official Account. WeChat Subscription Accounts are not supported.
- You have obtained the Developer ID (AppID) and Developer Secret (AppSecret) from the WeChat Official Accounts Platform.
- You can configure message push settings, the web authorization domain, and the IP whitelist on the WeChat Official Accounts Platform.
- The annual review of your WeChat Official Account is still valid.
The
access_tokenassociated with the same AppID and AppSecret is globally unique. Requests from multiple servers may overwrite each other. Use one central server to obtain and refresh the token, and let other business servers access it through that service.
2. Enable WeChat in RootAuth
2.1 Enable the WeChat Provider
In the provider list, find WeChat and click Enable.
In the configuration dialog, turn on the WeChat switch at the top. The configuration fields and Save button become available.
2.2 Select a QR Code Generation Method
RootAuth supports two QR code generation methods:
| Method | Description |
|---|---|
| Event QR Code | Uses the WeChat API to generate a QR code with a scene value. When a user scans the code, follow or scan events are sent back to RootAuth. Users who have not followed the Official Account can automatically complete login after following it. This method is selected by default. |
| Web URL QR Code | The QR code contains a WeChat web authorization URL. After scanning, the page opens in WeChat and obtains the OpenID through web authorization. Follow events are not processed. |
2.3 Configure an Event QR Code
If you select Event QR Code, complete the following fields:
| Field | Required | Description |
|---|---|---|
| Developer ID | Yes | The AppID provided by the WeChat Official Accounts Platform. |
| Developer Secret | Yes | The AppSecret provided by the WeChat Official Accounts Platform. |
| Token | Yes | Enter 3-32 letters or numbers. It must match the token in the WeChat message push settings. |
| Callback URL | Generated by RootAuth | Generated for the current application and available to copy. Configure it as the message push URL on the WeChat Official Accounts Platform. |
| QR code validity period | Yes | The QR code validity period in seconds. The default is 600 seconds. An expired QR code is refreshed automatically. |
| IP whitelist | Generated by RootAuth | The RootAuth server IP address. Copy it to the APP IP whitelist on the WeChat Official Accounts Platform. |
| EncodingAESKey | Yes | A 43-character message encryption and decryption key. It must match the WeChat configuration. |
| Official Account annual review date | Yes | Select the annual review date. An expired Official Account may lose API permissions and affect user login. |
| Message encryption mode | Fixed | Fixed to Secure Mode (Recommended). Select the same mode on the WeChat Official Accounts Platform. |
| Login mode | Fixed | Fixed to Available for login and sign-up and cannot be cleared. |
First save the Token, EncodingAESKey, and Callback URL in RootAuth, then configure and save the same values on the WeChat Official Accounts Platform. Otherwise, WeChat may fail to validate the configuration.
2.4 Configure a Web URL QR Code
If you select Web URL QR Code, complete or confirm the following fields:
| Field | Required | Description |
|---|---|---|
| Developer ID | Yes | The AppID provided by the WeChat Official Accounts Platform. |
| Developer Secret | Yes | The AppSecret provided by the WeChat Official Accounts Platform. |
| Domain | Generated by RootAuth | The web authorization domain provided by RootAuth. Copy it to the web authorization domain settings of the WeChat Official Account. |
| IP whitelist | Generated by RootAuth | The RootAuth server IP address. Copy it to the APP IP whitelist on the WeChat Official Accounts Platform. |
| Official Account annual review date | Yes | Select the annual review date. A date before today cannot be selected. |
| Login mode | Fixed | Fixed to Available for login and sign-up and cannot be cleared. |
2.5 Save the Configuration
After completing the fields, click Save. After the configuration is saved:
- The WeChat provider displays the Enabled and WeChat Official Account Follow labels.
- The action button changes to Manage.
- Click Manage to view or update the saved configuration.
3. Configure the WeChat Official Accounts Platform
After saving the RootAuth configuration, complete the corresponding settings on the WeChat Official Accounts Platform.
3.1 Event QR Code
| Step | Setting | Action |
|---|---|---|
| 1 | Server URL | Copy the callback URL provided by RootAuth and configure it as the message push URL on the WeChat Official Accounts Platform. |
| 2 | Token | Enter the same Token configured in RootAuth. |
| 3 | EncodingAESKey | Generate or enter the key on the WeChat Official Accounts Platform and make sure it matches RootAuth. |
| 4 | Message encryption and decryption mode | Select Secure Mode to match the RootAuth setting. |
| 5 | IP whitelist | Add the RootAuth server IP address to the APP IP whitelist on the WeChat Official Accounts Platform. |
3.2 Web URL QR Code
| Step | Setting | Action |
|---|---|---|
| 1 | Web authorization domain | Copy the domain provided by RootAuth and configure it under Account Settings → Function Settings → Web Authorization Domain in the WeChat Official Account backend. |
| 2 | IP whitelist | Add the RootAuth server IP address to the APP IP whitelist on the WeChat Official Accounts Platform. |
4. How Users Log In with WeChat
4.1 Hosted Integration
When you use the login and sign-up pages hosted by RootAuth, enabling WeChat adds a WeChat entry to the third-party login area. Clicking it opens a WeChat QR code dialog.
If Google, Facebook, WeChat, and other third-party providers are enabled at the same time, the entries are displayed in the configured order. If some providers are collapsed, WeChat may appear under More Login Options or More Sign-Up Options.
4.2 Scan to Log In or Sign Up
- The user clicks the WeChat entry on the login or sign-up page.
- A QR code dialog opens, and the user scans the code with the WeChat app.
- For an Event QR Code, a user who has not followed the Official Account must follow it first.
- RootAuth uses the WeChat user identifier to find an associated account.
- If an account exists, RootAuth logs the user in. If no account exists, RootAuth creates an account and completes login.
- After login succeeds, the QR code dialog closes and the page redirects to the application callback URL.
Whether the user scans from the login page, sign-up page, or unified login/sign-up page, RootAuth automatically completes login or sign-up based on whether an account already exists.
4.3 API Integration
If your application uses a custom frontend, use the RootAuth API to implement the WeChat QR code entry. A typical flow includes:
- Request a WeChat QR code with a scene value.
- Poll or query the scan status.
- After a successful scan, obtain the user information and login session.
With API integration, your application is responsible for displaying the QR code, showing loading states, refreshing expired codes, and redirecting after successful login.
5. View a User's WeChat Authentication Method
5.1 View User Records
After a user signs up by scanning a WeChat QR code, RootAuth creates a user record. If WeChat does not return an email address or phone number, the corresponding fields in the user list remain empty.
Administrators can go to User Management → Users, open the user details, and add an email address, phone number, or other basic information.
5.2 View the Authentication Method
On the user details page, check the Authentication Methods section for the WeChat Official Account Follow record.
| Field | Description |
|---|---|
| Authentication method | WeChat Official Account Follow |
| Identifier | The WeChat user identifier associated with the current user, such as OpenID. |
| Last used | The most recent time the user logged in through the WeChat Official Account. |
6. Bind or Unbind a WeChat Account
WeChat QR code login creates a new user when no associated account is found. To associate the WeChat identity with an existing account, the application must call the RootAuth API after the user has logged in.
- Bind: The logged-in user submits the WeChat authorization result, and the application calls the RootAuth API to associate the WeChat identity with the current account.
- Unbind: The logged-in user requests unbinding, and the application calls the RootAuth API to remove the WeChat binding from the current account.
- One WeChat account can be associated with only one system account.
The RootAuth console does not provide buttons for administrators to bind or unbind WeChat accounts manually. The application must implement the binding and unbinding flows.
7. Logs
RootAuth records WeChat-related actions under Audit Logs → User Behavior Logs.
| Event type | Description |
|---|---|
| WeChat Official Account sign-up | The user creates an account by scanning a WeChat QR code. |
| WeChat Official Account login | The user logs in to an existing account by scanning a WeChat QR code. |
| Bind WeChat Official Account | A logged-in user binds a WeChat Official Account through the application. |
| Unbind WeChat Official Account | A logged-in user unbinds a WeChat Official Account through the application. |
Logs include the user, IP address, country, time, result, and failure reason. For a newly registered user without an email address or phone number, the user field may display the user ID. After the identity is bound to an existing account, the email address or phone number is displayed first.
8. Disable WeChat Login
To disable WeChat login, click Manage for WeChat, turn off the switch at the top of the dialog, and save.
After WeChat login is disabled:
- The Hosted login and sign-up pages no longer display the WeChat entry.
- The saved AppID, AppSecret, and other settings are retained for future use.
- Existing users' WeChat authentication records are not deleted.
- After enabling it again, you can update and save the configuration. The new configuration replaces the previous settings.
;}.cls-2{fill:%230868f7;}.cls-3{fill:url(%23未命名的渐变_44);}.cls-4{fill:%23333;}%3c/style%3e%3clinearGradient%20id='未命名的渐变_8'%20x1='33.73'%20y1='100.61'%20x2='-0.03'%20y2='-1.06'%20gradientUnits='userSpaceOnUse'%3e%3cstop%20offset='0'%20stop-color='%237ae9fb'/%3e%3cstop%20offset='0.67'%20stop-color='%232b90f8'/%3e%3cstop%20offset='1'%20stop-color='%230868f7'/%3e%3c/linearGradient%3e%3clinearGradient%20id='未命名的渐变_44'%20x1='27.86'%20y1='18.67'%20x2='68.36'%20y2='22.22'%20gradientUnits='userSpaceOnUse'%3e%3cstop%20offset='0'%20stop-color='%235ac7f2'/%3e%3cstop%20offset='1'%20stop-color='%230868f7'/%3e%3c/linearGradient%3e%3c/defs%3e%3cpath%20class='cls-1'%20d='M29,28.74V81.91l-9.51-3.68v0L8.52,74A7.17,7.17,0,0,1,4,67.32V24.54A3.76,3.76,0,0,1,9.08,21Z'/%3e%3cpath%20class='cls-2'%20d='M68.09,78.07a13.15,13.15,0,0,1-17.9,12.06L29,81.91h0V28.74L50.19,37A13.17,13.17,0,0,0,68.08,25.3h0Z'/%3e%3cpath%20class='cls-3'%20d='M68.08,25.3a13.19,13.19,0,0,1-6.73,10.87A13.09,13.09,0,0,1,50.19,37L29,28.74V6A3.76,3.76,0,0,1,34.1,2.52l25.59,9.91A13.22,13.22,0,0,1,68.08,25.3Z'/%3e%3cpath%20class='cls-4'%20d='M129.06,81.76a4.33,4.33,0,0,1-3.19-1.31,4.4,4.4,0,0,1-1.31-3.24V56.86H97.65V77.21a4.36,4.36,0,0,1-1.35,3.2A4.68,4.68,0,0,1,93,81.76a4.32,4.32,0,0,1-3.19-1.31,4.37,4.37,0,0,1-1.32-3.24V27.27A4.58,4.58,0,0,1,89.83,24a4.59,4.59,0,0,1,7.82,3.27V48.15h26.91V27.27A4.58,4.58,0,0,1,125.91,24a4.59,4.59,0,0,1,7.82,3.27V77.21a4.37,4.37,0,0,1-1.36,3.2A4.65,4.65,0,0,1,129.06,81.76Z'/%3e%3cpath%20class='cls-4'%20d='M163.77,81.66c-6.57,0-11.76-1.92-15.44-5.7s-5.54-9.07-5.54-15.74a26.76,26.76,0,0,1,2.09-10.43,17.72,17.72,0,0,1,6.67-8.06,19.15,19.15,0,0,1,10.68-2.95,19,19,0,0,1,10.46,2.8,18.7,18.7,0,0,1,6.55,7.36,22.53,22.53,0,0,1,2.36,10.28A4.51,4.51,0,0,1,177,63.77H152.23a10.8,10.8,0,0,0,3.49,6.65c2,1.68,4.88,2.52,8.66,2.52a22.25,22.25,0,0,0,7.54-1.21c.74-.3,1.55-.67,2.37-1.07a3.75,3.75,0,0,1,1.84-.4,4.09,4.09,0,0,1,3,1.15,4,4,0,0,1,1.12,3,4.38,4.38,0,0,1-2.58,3.82,32.34,32.34,0,0,1-6.36,2.61A28.67,28.67,0,0,1,163.77,81.66ZM172.4,55.9a9.72,9.72,0,0,0-1.63-4.56A9.9,9.9,0,0,0,167,48a10.38,10.38,0,0,0-4.64-1.14,12,12,0,0,0-4.77,1.06,9.54,9.54,0,0,0-4.89,5.66,11.78,11.78,0,0,0-.51,2.3Z'/%3e%3cpath%20class='cls-4'%20d='M193,81.64a4.49,4.49,0,0,1-4.51-4.55V27.28A4.58,4.58,0,0,1,189.84,24a4.48,4.48,0,0,1,3.28-1.36A4.36,4.36,0,0,1,196.35,24a4.46,4.46,0,0,1,1.31,3.31V77.09a4.34,4.34,0,0,1-1.35,3.2A4.67,4.67,0,0,1,193,81.64Z'/%3e%3cpath%20class='cls-4'%20d='M263.79,81.71a5.7,5.7,0,0,1-4.2-1.74,5.76,5.76,0,0,1-1.73-4.19V27.37a4.58,4.58,0,0,1,1.35-3.27A4.59,4.59,0,0,1,267,27.37V72.53h24a4.58,4.58,0,0,1,3.27,7.82A4.66,4.66,0,0,1,291,81.71Z'/%3e%3cpath%20class='cls-4'%20d='M424.48,81.74a4.71,4.71,0,0,1-2.71-.88,5.43,5.43,0,0,1-1-1l-.07-.09-12.41-17-5.41,5v9.44a4.31,4.31,0,0,1-1.36,3.19,4.66,4.66,0,0,1-3.3,1.36A4.29,4.29,0,0,1,395,80.42a4.36,4.36,0,0,1-1.32-3.23V27.37A4.58,4.58,0,0,1,395,24.1a4.52,4.52,0,0,1,6.58.12,4.54,4.54,0,0,1,1.24,3.15V56.31l17.72-16.38.05,0a4.8,4.8,0,0,1,2.94-1.11,4.4,4.4,0,0,1,3.27,1.2,4.57,4.57,0,0,1,1.2,3.27,4.44,4.44,0,0,1-.77,2.33,7.45,7.45,0,0,1-1.43,1.65l-11,9.64,13.34,17.68a5,5,0,0,1,1,2.71,4.12,4.12,0,0,1-1.36,3.24A4.64,4.64,0,0,1,424.48,81.74Z'/%3e%3cpath%20class='cls-4'%20d='M317.93,81.76a21.5,21.5,0,1,1,21.17-21.5A21.37,21.37,0,0,1,317.93,81.76Zm0-34.1a12.61,12.61,0,1,0,12.42,12.6A12.52,12.52,0,0,0,317.93,47.66Z'/%3e%3cpath%20class='cls-4'%20d='M212.18,101.22a4.12,4.12,0,0,1-3.05-1.26,4.17,4.17,0,0,1-1.26-3.1V43.34a4.37,4.37,0,0,1,1.3-3.14,4.26,4.26,0,0,1,3.13-1.3,4.19,4.19,0,0,1,3.1,1.26,4.32,4.32,0,0,1,1.26,3.16,20.77,20.77,0,0,1,13-4.54,21.51,21.51,0,0,1,0,43,20.51,20.51,0,0,1-13-4.57V96.86a4.15,4.15,0,0,1-1.3,3.06A4.5,4.5,0,0,1,212.18,101.22Zm17.43-53.63c-6.23,0-12.93,4.11-12.93,12.72a12.73,12.73,0,0,0,25.46,0A12.71,12.71,0,0,0,229.61,47.59Z'/%3e%3cpath%20class='cls-4'%20d='M365.76,81.76a21.5,21.5,0,1,1,21.18-21.5A21.37,21.37,0,0,1,365.76,81.76Zm0-34.1a12.61,12.61,0,1,0,12.42,12.6A12.52,12.52,0,0,0,365.76,47.66Z'/%3e%3c/svg%3e)