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 AppID and AppSecret for 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_ID
  • WECHAT_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/callback

For example:

https://downcity.example.com/v1/accounts/oauth/callback

The 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/qrconnect

with 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 wechat button instead of checking providers first
  • For the overall OAuth flow, continue with OAuth and Session
  • For the full integration path, read Accounts Service
  • After deployment, write WECHAT_CLIENT_ID and WECHAT_CLIENT_SECRET into Federation env through the Admin API or the fed admin workspace