Google Login Setup

Enable Google OAuth Web Application login in the accounts service of @downcity/services.

This page is about the Google OAuth Web Application login flow.

It maps to a Google Cloud web-application OAuth client, not Android, iOS, Chrome Extension, or desktop credentials.

What you need first

Before integration, you will usually need:

a Google Cloud project
a Google account that can manage that project
the public City domain you plan to use
if the app is public, a homepage, privacy policy, and support email

If these prerequisites are not ready, client creation and later OAuth approval often get blocked on the Google side.

Where to find the Google client ID and client secret

In Google's current official console flow, the usual path is:

Open Google Cloud Console
Go to Google Auth Platform
If this is the first setup, complete Branding and Audience first
Open Clients
Click Create Client
Choose Web application
Save the generated Client ID and Client secret

Many older tutorials still say APIs & Services -> Credentials. If your UI does not match older guides, follow the current Google Auth Platform flow instead.

What to configure in Downcity

The accounts service reads these two environment variables:

GOOGLE_CLIENT_ID
GOOGLE_CLIENT_SECRET

That means:

Google Client ID -> GOOGLE_CLIENT_ID
Google Client secret -> GOOGLE_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

If you are only using the Downcity accounts service server-side OAuth flow, this redirect URI is the critical part. You usually do not need to register your downcity frontend as a JavaScript origin for this flow alone.

The fields Google users most often get wrong

choosing the wrong Application type instead of Web application
putting the downcity frontend URL into Authorized redirect URIs instead of the City callback URL
using one public domain in production but registering another one in Google Cloud
changing redirect settings and testing immediately before Google finishes applying the change

How the frontend should use it

Do not hardcode the Google login button. Ask the server which providers are actually enabled:

const providers = await guest.service("accounts").get("providers");

If the response contains:

{ id: "google", type: "oauth", enabled: true }

then render a Google login entry.

To start login:

const start = await guest.service("accounts").action("oauth/start").invoke({
  provider: "google",
  city_id: "city_demo",
});

Then send the user to start.url, and use oauth/result to poll or confirm the result:

const result = await guest.service("accounts").get("oauth/result", {
  state: start.state,
});

Why you may see testing-mode or unverified prompts

If your Google OAuth setup is still missing Branding, Audience, domain details, or other required information, or if the app is still in a limited testing state, Google may block or warn during sign-in.

Downcity only handles the standard OAuth start and callback flow. It does not bypass Google's own branding, audience, or verification requirements.

What this flow returns

After Google login succeeds, the accounts service still returns a normal City user_token.

So the downcity does not need a different post-login client flow just because the user came from Google:

const user = new City({
  role: "user",
  city_url: "https://base.example.com",
  city_id: "city_demo",
  user_token: result.user_token,
});

Common mistakes

assuming the frontend URL should be used as redirect_uri
storing only the Client ID and forgetting the Client secret
hardcoding the Google login button instead of checking providers
creating the wrong Google OAuth client type, which breaks the callback flow

For the overall OAuth flow, continue with OAuth and Session
If you also need WeChat Website App login, continue with WeChat Login Setup
For the full integration path, read Accounts Service
After deployment, write GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET into Federation env through the Admin API or the fed admin workspace

Table of Contents