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¶
- 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.
- 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>
- Tell the game which identity string to pass to
GetAuthTicketForWebApi. The default isotomo-auth(AUTH_STEAM_IDENTITY). Steam refuses a ticket made for another app or identity. - Restart
auth. The startup log sayssteam sign-in is configured.
Optional: AUTH_STEAM_REFUSE_VAC_BANNED=true also refuses VAC-banned accounts (publisher bans
are always refused).
Turn on Google¶
- In Google Cloud Console, create an OAuth client ID of type Desktop app. Under the
consent screen, request only the
openidscope: otomo asks for no email and no profile. - Put the client id in
deploy/.envand 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
- 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.
Link, list and unlink¶
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.