Java

WeChat QR Login in Java: WxJava SDK vs Raw OAuth 2.0 Calls

By 皮皮林551 · Nov 9, 2026

Read original on juejin.cn ↗ Google Translate ↗ Alt translation

Any Java backend integrating WeChat login has to meet the callback-domain requirement and handle state validation correctly, or users can't authenticate at all. The dual choice between a wrapper SDK and raw HTTP calls applies to any OAuth integration where you trade boilerplate for control.

Summary

WeChat's QR login flow follows OAuth 2.0 but adds WeChat-specific constraints: an approved website app on the Open Platform, an ICP-registered callback domain, and a state parameter for CSRF protection. The backend builds an authorization URL, the frontend renders it as a QR code, and after the user scans, WeChat redirects with a code. That code exchanges for an access_token and openid, which then pulls user info and completes local login.

Two implementation paths exist. The WxJava SDK (version 4.6.0 shown) wraps token management and API calls, cutting boilerplate; a couple of methods handle URL generation and callback processing. The alternative runs manual HTTP calls with RestTemplate or WebClient, building the URL and token exchange yourself, which means more code but zero external dependencies.

Security and design get clear treatment. The state parameter must be generated server-side, stored in session or Redis, and compared against the callback's state, or login is rejected. openid serves as the unique user key within a single website app, while cross-app identity needs unionid, which requires all apps under the same Open Platform account. A practical note: the callback domain must match exactly, and ngrok can provide a temporary public domain during development.

Takeaways

— WeChat QR login uses OAuth 2.0 with the scope snsapi_login.

— You need an approved website app on the WeChat Open Platform to obtain AppID and AppSecret.

— The callback redirect URI must be an ICP-registered domain and exactly match the configured callback domain.

— The flow: backend generates authorization URL, frontend shows QR, user scans, WeChat calls back with code, backend exchanges code for access_token and openid, fetches user info, and completes local login.

— WxJava SDK example (4.6.0) uses WxMpService to build the authorization URL and handles the callback with getAccessToken(code).

— Manual HTTP approach builds the URL to open.weixin.qq.com/connect/qrconnect, then calls https://api.weixin.qq.com/sns/oauth2/access_token with grant_type=authorization_code.

— The state parameter must be a random value stored server-side and compared to the callback's state to prevent CSRF.

— openid is unique per website app; unionid is needed for cross-app identity.

— Use ngrok or similar for local development because the callback domain must be publicly reachable from WeChat.

— WxJava handles token caching, HTTP errors, and JSON parsing, while manual calls give full control over requests and responses.

Conclusions

The callback domain requirement is a hard prerequisite that forces a publicly reachable endpoint before any login can work, which is unusual among OAuth providers that allow localhost redirects.

openid's per-app scoping means a user's identity is fragmented across different website apps unless explicitly bound to a unionid, so multi-app integrations need identity planning up front.

WxJava's encapsulation cuts boilerplate but also hides the token exchange, so developers who need to understand the OAuth flow will get more from the manual approach.

Concepts & terms

openid

WeChat's unique identifier for a user within a single website app. The same user gets different openids in different apps.

unionid

A cross-app identifier that unifies a WeChat user across multiple apps, but only when those apps are bound to the same Open Platform account.

WxJava

A popular Java SDK for WeChat development that wraps token management, API calls, and JSON parsing, reducing boilerplate for OAuth and other WeChat integrations.

snsapi_login

The OAuth scope for WeChat QR login. It requests user authorization without requiring the user to follow an official account.

Source: juejin.cn ↗ Google Translate ↗ Backup ↗