auth4.dev

Google sign-in

Players choose Google on the hosted login page, pick an account on Google's own page, and return signed in. You need an OAuth client for a web application from the Google Cloud console.

1. Create a Google OAuth client

You need a Google Cloud project. A project you already use for your game is fine.

  1. In the Google Auth Platform section of the Google Cloud console, set up the consent screen if you haven't yet: an app name, a support email and, under Audience, the External user type. auth4.dev asks only for the openid and email scopes.
  2. While the app's publishing status is Testing, only the test users you list can sign in. Publish the app before your players need it.
  3. Under Clients, create a client and choose the application type Web application.
  4. Under Authorized redirect URIs, add this URL, replacing {projectId} with your Project ID:
    https://auth.auth4.dev/t/{projectId}/identity/google/callback
    The console shows the exact URL with a copy button on the Google card. It must match exactly. You don't need any authorized JavaScript origins.
  5. Create the client and copy the Client ID, which ends in .apps.googleusercontent.com, and the Client secret. Keep the secret out of source control.

2. Connect it in the console

On the project's sign-in methods page, under Google:

  1. Paste the client ID into Google client ID.
  2. Paste the client secret into Client secret.
  3. Tick Enable Google sign-in.
  4. Select Save Google settings.

Only project owners can change these settings; admins and viewers see them read-only. The secret is write-only: it is stored encrypted and can't be viewed again. To rotate it, add a new secret in Google, enter it in Replace client secret and save, then delete the old one in Google. Leave the field blank to keep the saved secret. If you change the client ID you must also enter its secret.

Once Google is on, players see it in three places:

  • Continue with Google on the hosted login page.
  • Link a Google account on the page where guests save their progress.
  • Continue with Google on the device approval page.

Untick the box and save to turn Google off. The option disappears from all three pages.

What identity data you get

  • Players are identified by Google's stable account ID (the ID token's sub). It is stored as the player's Google identity in your project and isn't put in your tokens. Key game data by your auth4.dev sub, which stays the same whichever method the player used.
  • Google shares the account's email address. auth4.dev marks it verified only when Google says it is verified. Under the default setting, the verified email step is skipped for a verified address. Google's address never becomes the emailclaim; only an address verified with auth4.dev does.
  • auth4.dev doesn't ask Google for the player's name or picture.
  • A Google account and an email-code, Discord, Apple or Microsoft account with the same address are separate players. They are joined only through account linking in the email step.
  • Google's tokens and your client secret stay on the server. Your application only receives auth4.dev tokens.

Sending players straight to Google

For a Sign in with Google button, pass the provider to the browser SDK. The hosted login page then goes straight to Google:

await auth4.login({ provider: "google" });

login() sends provider_hint=google. The Next.js SDK takes the same provider. If you build the authorization request yourself, add that parameter. If Google is off for the application, the player sees the usual list instead. See theAPI reference.

Linking Google to a guest

A guest can save their progress by linking a Google account. They keep the same user ID and stop being a guest. Call upgradeGuest() or, in Unity, UpgradeGuestAsync without a provider, and the upgrade page offersLink a Google account with the other enabled methods.

  • Only a Google account that is new to your project moves to the guest. If it already belongs to another player, the upgrade fails with identity_in_use and the guest stays as it was. See When the identity is already in use.
  • Accounts are never merged.

Device approval

When Google is on, the device approval page offers Continue with Google. After Google, the player comes back to the same code to approve or deny it. Your game calls SignInWithDeviceAsync as usual; nothing changes on the game's side.

When something goes wrong

  • If the player cancels on Google, the page says that Google sign-in was cancelled and lets them choose another method.
  • If Google is unreachable or returns an unexpected response, the page reports a temporary problem and offers a retry. Google's own error text is never shown.
  • Google shows redirect_uri_mismatch when the redirect URI in the client doesn't match the one on the console card exactly. Copy it again from the console.
  • If the Google option doesn't appear, check that the box is ticked and a client ID and secret are saved. Incomplete configuration fails closed rather than showing a broken button.
  • If you change the client ID or turn Google off while a player is on Google's page, that sign-in fails with a temporary error and the player can try again.

Testing locally

Your app can run on localhost, but Google sign-in itself always happens on the hosted pages and on Google, so you need a real Google account. Use a separate auth4.dev project for testing, and add your test accounts as test users while the Google app is in testing.

If you run the auth4.dev API itself with Wrangler, you can point Google, Apple and Microsoft at a stand-in on your own machine instead. Set this in the ignored apps/api/.dev.vars:

Excerpt from apps/api/.dev.vars.example
# Google, Apple and Microsoft sign-in (AUTH4D-146) and Epic Games sign-in (AUTH4D-147) use
# per-project credentials saved in the console, not Worker vars. Optional, local runs only: one
# loopback stand-in for all four providers, with the provider as the first path segment (for
# example /google/token).
# OIDC_LOCAL_MOCK_ORIGIN=http://127.0.0.1:9100

The API honours it only in the local environment, and only for a loopback address. The repository's automated tests use a stand-in provider and never contact Google.