Skip to content
Escriba Suite Escriba Suite

Lockatus documentation

Lockatus is the identity hub of the suite: the shared list of people and the common doorman. It holds the users, their passwords, their two-factor and their per-app roles, and hands each one a signed pass to enter any app without logging in again.

How it works

Section titled “How it works”

OIDC single sign-on

Authorization Code + PKCE. Sign in once at the hub; every federated app recognizes you and reads your role from the token. Logging in once opens every app you’re allowed into.

Offline verification

The hub signs tokens with RS256; apps verify them against the public JWKS without calling home. If the hub is down, live sessions keep working.

The access matrix

A who-by-system grid. Each app declares its own role catalog; Lockatus assigns them. No role for an app means no access — gating happens at the matrix.

Two-factor and recovery

Enroll TOTP once (Google Authenticator or compatible), with one-time recovery codes and an admin reset. Inherited by every app. Changing a password invalidates every refresh token.

Shallow roles

Section titled “Shallow roles”

The four single-user apps don’t become multi-user inside — Lockatus is their external user table. Each app declares the roles it understands; the hub assigns them from the matrix, and the app gates by role. Deeper, per-user ownership lives only where an app truly owns resources per person (such as Selega).

Onboarding a new app

Section titled “Onboarding a new app”

Any new family app joins from the matrix itself, with no redeploy: declare its slug and its role catalog (and optional redirect URIs) with the + App button, then assign roles to users. The catalog of the suite ships pre-seeded.

Federating an app

Section titled “Federating an app”

Federation is optional and non-breaking — each app keeps its standalone login behind an AUTH_MODE=federado flag (default off). In federated mode the app delegates /login to the hub and, on the callback, exchanges the code, verifies the RS256 tokens against the JWKS, and seeds its own session — so the rest of the app’s role gating is unchanged. Reference OIDC clients ship for Node (node:crypto, no extra dependencies) and Python (cryptography).

Security model

Section titled “Security model”
  • RS256 asymmetric signing. The hub holds the private key; apps verify with the public key (JWKS), offline.
  • Short tokens + refresh. Refresh re-checks the role, so revoking access in the matrix cuts the SSO on the next refresh.
  • Audit split. Security events (logins, 2FA, role changes) are on; per-app activity logging is opt-in and off by default.