Identity and sign-in¶
Otomo has three kinds of identity, and each has its own issuer, its own keys and its own rules: players, staff, and services. This page explains how each proves who it is, how that proof is checked, and why the player and staff halves are kept apart all the way down to separate gateways.
If you have never met tokens before, read Logins and tokens first. This page builds on it.
The three identities¶
| Players | Staff | Services | |
|---|---|---|---|
| Issued by | auth |
admin-auth |
deploy/scripts/generate-secrets.sh |
| Credential | A signed token (JWT) | A signed token (JWT) | A static random key in a file |
| Audience | otomo:player |
otomo:staff |
not applicable |
| Carries | sub (the account id), no roles |
sub and a roles list |
a role, fixed by which key it is |
| Lifetime | Access token 15 minutes; refresh token 30 days, sliding | Access token 15 minutes by default (at most 1 hour) | until rotated by an operator |
| Verified by | Gateway, Session, Economy, Matchmaker, Patch (recordings) | Gateway, gateway_dev, Config, Patch, Dashboard, Session, Economy |
the service being called |
| Used on | Public listeners | Public listeners | Internal listeners (:8081) |
Player sign-in¶
Device login¶
A player has no password. The SDK makes a long random device id the first time the game
runs and saves it. To sign in, the game sends it to POST /auth/anonymous and gets back an
access token and a refresh token.
What auth does with it:
- Checks the shape. The id must be 43 base64url characters and look random (enough distinct characters), so a guessable id is refused.
- Stores only a keyed hash. The id is never stored.
authstores an HMAC of it under a secret pepper (deploy/secrets/device_pepper). The same id always maps to the same account (sub). The pepper cannot be rotated, and losing it strands every device binding, so it is part of the backup. - Finds or creates the account. Each new account counts against a per-address quota (5 an hour by default), which is why the gateway must pass the true client address.
- Issues tokens. The access token is signed with an Ed25519 key and lasts 15 minutes. The
refresh token is an opaque random value that
authstores hashed.
Refreshing¶
POST /auth/refresh swaps a refresh token for a new access token and a new refresh token.
Each refresh token works once. Presenting one that was already used is treated as theft and
revokes the whole family of tokens from that login. To tolerate two copies of the game
racing on one machine, a token that was spent in the last 30 seconds is refused without
punishing the family. Players can list and revoke their sessions (GET/DELETE
/auth/sessions) and erase their account (DELETE /auth/account).
Identity providers¶
auth separates proving who you are from which account you are. A provider verifies
one kind of credential and returns a subject (a method plus an external id). The resolver
turns the subject into exactly one account. Today there are two providers: the device login,
and a fixture login (POST /auth/prototype) that exists only to prove the boundary and
refuses to run outside a dev environment. The reasoning is in
design/26-auth-split-decision.md.
Steam, Google and any other OAuth 2.0 / OpenID Connect provider (Discord and others, by
configuration) are further providers behind the same login path, so a sign-in with them gives
the same account, refresh family and tokens as a device login. A signed-in player can link
several identities to one account and unlink all but the last. All of it is off until an
operator configures it; Sign in with Steam, Google and others
has the steps and design/21-sign-in-and-linking.md the reasoning.
Staff sign-in¶
Staff accounts live in admin-auth, a different service with a different database, signing key
and issuer. Staff never use device ids.
- Invite, then password. An admin creates an invite;
admin-authreturns a one-time link of the form/admin/onboard#token=.... The token is in the URL fragment, which browsers never send to a server, so it cannot appear in any log. The new user opens it and sets a password (12 to 128 characters, checked against a common-password list). Otomo sends no email. - Passwords are hashed with argon2id. Repeated failures lock the account for a while.
- Two-factor sign-in (TOTP). It is required for the
adminrole and optional for the others. A password login for an account with a confirmed factor returns a short-lived MFA ticket instead of a token; the second step exchanges the ticket and a 6-digit code (or a recovery code) for the real token. An admin with no factor yet is forced to enroll. - The root account. Exactly one break-glass account,
root@otomo.internal, has a password but no TOTP. Its only job is to create personal admin accounts. Only root can create or change anadmin. - Refresh uses a
__Host-otomo_refreshcookie, which the browser only sends to the exact host.gateway_devforwards that cookie toadmin-authand drops every cookie on all other routes. - More than one environment. Each environment (the live game, the test copy) has its own
admin-auth, accounts, signing keys and tokens; a token from one is refused by the other. One admin console can still operate both: the console'sgateway_devrelays/env/<name>/...to the other environment'sgateway_devwith the caller's token untouched, and that gateway verifies and authorises as usual. Staff sign in once per environment. To keep two sessions apart in one browser, the relay renames the refresh cookie per environment (__Host-otomo_refresh_<name>) on the way out and back to__Host-otomo_refreshon the way in. The console asks each environment who it is (GET /api/admin/env) and refuses to act when the answer is not the environment the person chose.
The staff roles¶
Roles are a ladder: viewer < live_ops < admin. A higher role can do everything a
lower one can. The gateway applies a coarse bar and each service re-checks with its own table.
| Role | Can do (as implemented) |
|---|---|
viewer |
Read everything: namespaces, drafts, versions, releases, audit, dashboards, logs, players, ledgers, maintenance and update-gate state. Preview a gate decision. Read the dev and staging manifests |
live_ops |
Also save and validate drafts, create versions, upload packs, publish to dev and staging, republish a release's update-gate block, change maintenance and the update gate, disband a party, grant a reward through a configured reward class |
admin |
Also create namespaces and replace schemas, publish to live, roll back and promote channels, exempt write routes from a maintenance window, manage staff accounts (but not other admins) |
Only root can create an admin or change anything about one.
The ladder is stated once for each service:
| Where | Source of truth |
|---|---|
| Config | services/config/internal/api/routes.go |
gateway_dev |
services/gateway_dev/ROUTE-POLICY.md and internal/router/dev.go |
| Admin website menu | services/adminui/ROUTE-MAP.md |
How a token is checked¶
Tokens are JWTs signed with Ed25519 (algorithm EdDSA). Checking one needs only the
issuer's public key, so no service has to ask auth anything on the hot path.
- JWKS. The public keys are published as a JSON Web Key Set, identified by key id (
kid). A verifier picks the key bykid, so keys can be rotated with an overlap. - Player keys travel by file.
authwrites its JWKS todeploy/secrets/jwks/and every verifier mounts that folder read-only and reloads it when it changes. No player token is ever verified against a URL in Compose, and a CI check enforces it. - Staff keys travel by HTTP. Every staff verifier fetches
http://admin-auth:8080/.well-known/jwks.jsonover the Docker network and refreshes it every 30 seconds. Neither gateway proxies/.well-known/jwks.json. - What is checked. Signature,
iss,aud,exp/nbf(with 30 seconds of leeway), and for staff routes,roles. A token for the wrong audience fails before any role is read. - Defence in depth. The gateway checks the token, and then the service checks it again.
Revocation has honest limits: a refresh token dies at its next use, but an access token lives out its 15 minutes. Retiring a signing key kills its tokens at the next reload.
Service keys between services¶
Internal calls do not use tokens. Each caller holds a service key: a long random value in a
file, one per caller role for each service it calls. The files are generated by
generate-secrets.sh into deploy/secrets/service_keys/, named <callee>_<caller>.key, and
mounted read-only only into the containers that need them.
The callee reads the key from Authorization: Bearer ... and compares it in constant time:
| Presenting | Answer |
|---|---|
| Nothing, an unknown key, or a player token | 401 |
| A valid key of a role this route does not admit | 403 |
| The right key | the response |
Examples, from deploy/compose.yaml:
| File | Held by | Lets it |
|---|---|---|
allocator_session.key |
Session | Reserve a server for a party |
allocator_matchmaker.key |
Matchmaker | Reserve a server for a whole match |
session_allocator.key |
Allocator | Tell Session an allocation ended |
patch_session.key |
Session | Read the server manifest |
config_gameserver.key |
Game servers | Download the configuration bundle |
economy_gameserver.key |
Game servers | Pay a loot class or record progress |
ops_gateway.key, ops_auth.key, ops_session.key |
The three enforcers | Read the ops snapshot |
ops_admin_viewer.key, _live_ops.key, _admin.key |
gateway_dev |
Call the ops admin API as a given role |
Internal listeners publish no port and no gateway routes to them. A service key is
authentication for a service; it carries no player or staff identity. Where an action needs
to be attributed, the caller passes the actor along (for example, gateway_dev sends
X-Otomo-Actor-Id to Ops so the audit row names the person).
The ops admin API takes a key, not a token
/api/admin/ops/* is the one staff route whose upstream does not read a staff token.
gateway_dev verifies the token and the role first, then replaces Authorization with the
key for the role the token proved and forwards the subject. Ops still refuses a viewer's
write on its own. A planned change would make Ops verify tokens itself.
Why two gateways¶
gateway and gateway_dev look similar, and most of their code is the same. They are separate
programs on purpose (services/gateway_dev/README.md has the full argument):
- Two identity providers, two audiences. A single gateway with a flag would need both trust roots in the public-facing container.
- A flag is not a boundary. With one binary, whether admin routes exist is an environment
variable on a container facing the internet. With two, the player gateway has no admin route
table at all:
/api/admin/...is a404there, and/api/player/...is a404ongateway_dev. Tests assert both. - Blast radius.
gateway_devpublishes only on the host's loopback address, because its/admin-auth/and/admin/prefixes are public by design: it is how you get a token. Exposing it to the internet would be a whole-service bypass, not a hardening gap.
The cost is duplicated code, kept honest by tests and the route-policy documents.
Related pages¶
- How otomo works: the big picture
- Logins and tokens: the beginner version of this page.
- Use the admin website: signing in as staff, step by step.
- Live ops: what each role can change in the admin website.
- Deployment and operations: the SSH tunnel and key rotation.
- Error codes: the
401and403reasons. - Repository:
design/06-auth-identity-contract.md,design/07-auth-techspec.md,design/26-auth-split-decision.md,services/auth/README.md,services/admin_auth/README.md.