WeChat Login Setup
Enable WeChat Open Platform Website App login in the accounts service of @downcity/services.
This page is specifically about the "WeChat Open Platform -> Website App -> WeChat Login" flow.
It is not Official Account login, and it is not Mini Program login.
The primary shape of this flow is PC-side QR-code login.
However, according to the current WeChat documentation, newer Windows and Mac WeChat desktop clients may sometimes show a fast-login confirmation instead of requiring a QR scan every time when the user is already signed in locally.
What you need first
Before integration, make sure you already have:
- a WeChat Open Platform developer account
- a Website App that has passed review
- WeChat Login enabled and approved for that Website App
- the
AppIDandAppSecretfor that Website App
If these prerequisites are missing, adding a wechat provider in code will not make real login work.
What to configure in Downcity
The accounts service reads these two environment variables:
WECHAT_CLIENT_IDWECHAT_CLIENT_SECRET
That means:
- WeChat Website App
AppID->WECHAT_CLIENT_ID - WeChat Website App
AppSecret->WECHAT_CLIENT_SECRET
in Federation env.
Which callback URL to register
The OAuth callback URL used by the accounts service is fixed:
https://your-base-domain/v1/accounts/oauth/callbackFor example:
https://downcity.example.com/v1/accounts/oauth/callbackThe callback URL registered in the WeChat Open Platform Website App console must match this exact URL.
If you use a custom domain, register the same path under that custom domain.
Why the domain often fails
When WeChat website login starts, the accounts service generates a login URL under:
https://open.weixin.qq.com/connect/qrconnectwith the current City redirect_uri.
If the callback domain configured in WeChat does not match the real public City domain used by the downcity, login usually fails immediately.
So two things must stay aligned:
- the real public City domain used by the downcity
- the exact callback URL registered in WeChat
How the frontend should use it
Do not hardcode the WeChat login button. Ask the server which providers are actually enabled:
const providers = await guest.service("accounts").get("providers");If the response contains:
{ id: "wechat", type: "oauth", enabled: true }then render a WeChat login entry.
Start login through the unified login/start entry:
import { create_loopback_login_callback } from "@downcity/federation/node";
const callback = await create_loopback_login_callback(180_000);
const start = await federation.user.account.login_start({
provider: "wechat", client_type: "cli",
redirect_uri: callback.redirect_uri, state: callback.state,
code_challenge: callback.code_challenge, code_challenge_method: "S256",
});Open start.url in the local system browser and complete WeChat authentication. The browser automatically returns to the receiver, which validates Host, path, and state. Wait for callback.authorization_code, then exchange it with the verifier. Close the receiver on cancellation, timeout, and completion. Keep the initiating proof and verifier private; reuse the exchange ID and callback proof on transport retries. Remote/headless CLI OAuth is unsupported.
OAuth supplies client_type, an exact redirect_uri, random state, and S256 PKCE. Website callbacks must match AccountsService trusted_web_callbacks; an empty list rejects web OAuth. CLI/Desktop use an exclusive local 127.0.0.1 ephemeral port. After validating callback state, exchange the authorization code, private verifier, login_secret, and stable exchange_id for a token. Status never delivers credentials.
if (!callback.authorization_code) throw new Error("Wait for the local browser callback");
const result = await federation.user.account.exchange({
authorization_code: callback.authorization_code,
code_verifier: callback.code_verifier,
});
callback.close();What this flow returns
After WeChat login succeeds, the accounts service still returns a normal City user_token.
So the downcity does not need a special post-login client flow just because the user came from WeChat:
const user = new City({
role: "user",
city_url: "https://base.example.com",
user_token: result.user_token,
});Common mistakes
- mixing Website App login with Official Account login
- mixing Website App login with Mini Program login
- configuring one domain in WeChat while the downcity actually uses another City domain
- hardcoding the
wechatbutton instead of checkingprovidersfirst
Related docs
- For the overall OAuth flow, continue with OAuth and Session
- For the full integration path, read Accounts Service
- After deployment, write
WECHAT_CLIENT_IDandWECHAT_CLIENT_SECRETinto Federation env through the Admin API or thefedadmin workspace