Skip to content

Sign in with Steam, Google and other providers

Players sign in with a device id by default. This page shows how to also let them sign in with Steam, Google, or any provider that speaks OAuth 2.0 (Discord, Twitch, a self-hosted OIDC server), link several of these to one account, and what to do when something goes wrong.

Everything here is off by default. A server with none of it configured behaves exactly as before, and /auth/steam, /auth/google and /auth/oauth/<name> answer 503 provider_not_configured.

The design is in design/21-sign-in-and-linking.md. This page is the how-to.

How it works, in one minute

  • Each provider is a way to prove who the player is. Auth checks the proof with the provider and turns it into the same account, session and tokens as a device login.
  • A signed-in player can link another provider to their account, see what is linked, and unlink one while at least one way in remains.
  • Two accounts are never merged. Linking an identity that already belongs to another account is refused (identity_taken).
  • The SDK never holds a Steam or OAuth secret. The game passes in a Steam ticket, or a code from a browser sign-in it ran; Auth does the checking with secrets only the server has.

For operators

Turn on Steam

  1. On the Steamworks partner site, create a Publisher Web API key for your organisation (Valve's Steamworks documentation has the current steps). It must be a publisher key, not a user key.
  2. Put the key in the secrets file and the app id in deploy/.env:
printf '%s' '<publisher key>' | sudo tee deploy/secrets/auth_steam_webapi.key >/dev/null
# deploy/.env
AUTH_STEAM_APP_ID=<your Steam app id>
  1. Tell the game which identity string to pass to GetAuthTicketForWebApi. The default is otomo-auth (AUTH_STEAM_IDENTITY). Steam refuses a ticket made for another app or identity.
  2. Restart auth. The startup log says steam sign-in is configured.

Optional: AUTH_STEAM_REFUSE_VAC_BANNED=true also refuses VAC-banned accounts (publisher bans are always refused).

Turn on Google

  1. In Google Cloud Console, create an OAuth client ID of type Desktop app. Under the consent screen, request only the openid scope: otomo asks for no email and no profile.
  2. Put the client id in deploy/.env and the client secret in the secrets file:
# deploy/.env
AUTH_GOOGLE_CLIENT_ID=<client id>.apps.googleusercontent.com
printf '%s' '<client secret>' | sudo tee deploy/secrets/auth_google_client.secret >/dev/null
  1. Restart auth. The game uses the same client id (it is not a secret).

Google's loopback redirect (http://127.0.0.1:<port>/) is the only redirect otomo accepts for Google. You do not register it: Desktop-app clients allow any loopback port.

Turn on Discord or another provider

A provider is configuration, not code. Name it in AUTH_OAUTH_PROVIDERS and set its variables. Discord is already wired through deploy/compose.yaml:

# deploy/.env
AUTH_OAUTH_PROVIDERS=discord
AUTH_OAUTH_DISCORD_CLIENT_ID=<application id>
AUTH_OAUTH_DISCORD_REDIRECT_URIS=https://your.game/oauth/callback
# or, for a desktop loopback flow:
# AUTH_OAUTH_DISCORD_ALLOW_LOOPBACK=true
printf '%s' '<client secret>' | sudo tee deploy/secrets/auth_oauth_discord.secret >/dev/null

Register the same redirect URI in the provider's developer portal. For another provider, copy the AUTH_OAUTH_DISCORD_* block in compose.yaml under another name (the name is 2 to 16 lower-case letters and digits). Per provider, set one of:

How Auth learns who the player is Variables Use for
Userinfo (plain OAuth 2.0) ..._USERINFO_URL, ..._SUBJECT_FIELD (default id) Discord, Twitch
ID token (OpenID Connect) ..._JWKS_URL and ..._ISSUERS Keycloak, Auth0, Okta

The full variable list is in services/auth/README.md. Every URL must be https, and the client secret is always read from a file, never from the environment. Plain-http provider URLs are accepted only with AUTH_ENV=dev (for a local fake provider); in staging and production auth refuses to start with one.

Use the provider's immutable id as the subject: nothing else. For a userinfo provider, ..._SUBJECT_FIELD must be a stable numeric or opaque id (id for Discord). A username, login, email or display name can be changed by the player or released and re-claimed by someone else, and whoever holds it next would sign in to the old holder's account. auth refuses the well-known mutable field names (username, login, email, name, global_name, display_name, and similar) at startup with an error that says so. Only if you have verified that a field really is immutable and unique, set AUTH_OAUTH_<NAME>_ALLOW_MUTABLE_SUBJECT=true to accept it.

Adding a provider name to compose

Docker Compose only passes variables it names. The Discord block is named; a provider with another name needs its AUTH_OAUTH_<NAME>_* lines added under auth.environment (or in a compose.override.yaml), and its secret file next to the others in deploy/secrets/. A provider named in AUTH_OAUTH_PROVIDERS whose settings are incomplete (no token URL, no verification setting, no redirect URI and loopback off, or no client id or secret) is simply off: auth logs a startup warning naming exactly what is missing, the provider answers 503 provider_not_configured, and device login and the other providers keep working. Only unsafe configuration stops auth at startup: a non-https URL outside dev, a malformed redirect URI, or a mutable subject field.

What you will see

Where What
Startup log one line per provider: configured, or which setting is missing
auth_provider_checks_total{method,result} ok, invalid, replayed, banned, key_refused, unavailable, not_configured, rate_limited
auth_provider_request_seconds{method} latency of the call to the provider
auth_identity_changes_total{action,method,result} links and unlinks
Alerts AuthProviderUnavailable (10 minutes of failures) and AuthProviderKeyRefused (your own key or secret was rejected: replace the secret file and restart)

Logs and metrics never contain a ticket, code, token, secret, provider user id or the redirect URI's port.

Limits

Each provider request costs one call to the provider, so these routes have their own limits: GATEWAY_PROVIDER_RATE_LIMIT_RPS / _BURST at the gateway (default 3 per second, burst 30, per address) and AUTH_PROVIDER_RATE_PER_MINUTE / _BURST in Auth (default 300 and 60). Signing in with an identity that has no account creates one and counts against AUTH_CREATE_QUOTA_PER_IP_HOUR like a new device. For an event where many players share one address, raise that quota.

Erasing a player

DELETE /auth/account removes the account and every identity linked to it, whichever provider. The identity is then free: signing in with it creates a new, empty account.

Troubleshooting

You see Likely cause
503 provider_not_configured the app id, client id or secret is not set, the secret file is empty, or (for AUTH_OAUTH_PROVIDERS) the startup log has a warning naming the missing setting
503 provider_unavailable and a key_refused metric the provider rejected your key or client secret
401 invalid_credential on sign-in (422 on link) the ticket or code is wrong, expired or already used, or was made for another app
400 invalid_redirect_uri the game used a redirect URI that is not allow-listed (or localhost instead of 127.0.0.1)
429 quota_exceeded too many new accounts from one address this hour

Auth deliberately answers every verification failure with the same invalid_credential; the log line says which check failed (signature, iss, aud, exp, token_rejected, ...).

For SDK users

The SDK adds IIdentityClient and IBrowserSignInClient, both implemented by AuthClient. It never runs Steamworks (the game passes in the ticket), and it runs the browser sign-in for Google and other providers itself. More ways to sign in is the shorter overview, with text you can reuse for players.

Sign in with Steam

// ticketHex: the hex of the ticket from Steamworks GetAuthTicketForWebApi("otomo-auth")
await auth.SignInWithSteamAsync(ticketHex);

Sign in with Google or another provider (browser flow)

The SDK runs the desktop flow for you: it listens on 127.0.0.1 on a free port, opens the browser with PKCE S256 and a random state, accepts only the redirect with that state, shows the player a page saying the window can be closed, and sends the code to Auth.

await auth.SignInWithGoogleAsync(clientId);                  // POST /auth/google
var linked = await auth.LinkGoogleAsync(clientId);           // POST /auth/identities/google
// another configured provider that allows the loopback redirect:
await auth.SignInWithBrowserAsync("discord", "https://discord.com/oauth2/authorize", clientId, "identify");

auth.BrowserLauncher = new GodotBrowser();                   // optional: open with OS.ShellOpen
auth.BrowserSignInTimeout = TimeSpan.FromMinutes(5);         // the default

The browser flow adds local errors (status 0): sign_in_cancelled (the player declined), state_mismatch, sign_in_failed, browser_unavailable and timeout.

If the game would rather run the flow itself (an embedded browser, a custom redirect), the pieces are public:

var verifier = Pkce.NewVerifier();
var state    = Pkce.NewState();
var redirect = Pkce.LoopbackRedirectUri(port);      // http://127.0.0.1:<port>/
var url = Pkce.BuildAuthorizationUrl(
    "https://accounts.google.com/o/oauth2/v2/auth", clientId, redirect, "openid", verifier, state);

// 1. open `url` in the system browser
// 2. listen on 127.0.0.1:<port>, read ?code=...&state=...
// 3. refuse the redirect unless Pkce.StateMatches(state, returnedState)
await auth.SignInWithProviderCodeAsync("google", code, verifier, redirect);   // or "discord", ...

For a provider other than Google, pass its configured name; it signs in through /auth/oauth/<name>. The redirect URI must be exactly one the operator allow-listed.

var identities = await auth.GetIdentitiesAsync();               // method, linked_at, display_hint
await auth.LinkSteamAsync(ticketHex);                           // add Steam to this account
await auth.LinkProviderCodeAsync("google", code, verifier, redirect);
await auth.UnlinkAsync("steam");                                // 409 last_identity if it is the only one

Linking never creates an account and never changes your session. A failed link answers 422, not 401, so a bad ticket never signs the player out.

The no-fallback rule

Once an install has signed in with, or linked, Steam or Google, the SDK stops signing in with the device id by itself. A device id may no longer belong to the account (the player can unlink it), and a device login would then silently create a new, empty account. When the session is lost the SDK raises LoggedOut and the game shows its sign-in choices. LoginWithDeviceIdAsync is still there for a "play as guest" button. The record is the file login_method next to the refresh token (FileSecretStore); a custom ISecretStore opts in by also implementing ILoginMethodStore.

Errors

Code Meaning
invalid_credential the ticket or code failed a check: get a new one
provider_banned this Steam account is banned from your game
identity_taken that identity belongs to another account (no merge)
method_already_linked the account already has another identity of that kind: unlink it first
last_identity removing it would leave no way to sign in
provider_not_configured hide that button
provider_unavailable retry after Retry-After
invalid_redirect_uri the redirect URI is not allow-listed

More in the error reference.