Skip to content

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:

  1. Checks the shape. The id must be 43 base64url characters and look random (enough distinct characters), so a guessable id is refused.
  2. Stores only a keyed hash. The id is never stored. auth stores 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.
  3. 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.
  4. Issues tokens. The access token is signed with an Ed25519 key and lasts 15 minutes. The refresh token is an opaque random value that auth stores 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-auth returns 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 admin role 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 an admin.
  • Refresh uses a __Host-otomo_refresh cookie, which the browser only sends to the exact host. gateway_dev forwards that cookie to admin-auth and 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's gateway_dev relays /env/<name>/... to the other environment's gateway_dev with 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_refresh on 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 by kid, so keys can be rotated with an overlap.
  • Player keys travel by file. auth writes its JWKS to deploy/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.json over 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):

  1. Two identity providers, two audiences. A single gateway with a flag would need both trust roots in the public-facing container.
  2. 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 a 404 there, and /api/player/... is a 404 on gateway_dev. Tests assert both.
  3. Blast radius. gateway_dev publishes 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.