Authentication

Authentication in Open Gauge is designed to be self-hostable end to end — including in fully offline / air-gapped environments — and is never coupled to a cloud-only provider.

Supported authentication modes

• Local users and passwords — the default for small self-hosted installations. Works fully offline; no external dependency. Every self-registered account requires activation before it can sign in — see Email notifications for how that works with and without SMTP configured. The one exception is the very first account created on a fresh install: with no admin yet able to activate anyone, it's created verified and as superadmin automatically, so a new deployment always starts empty and ready to use rather than pre-populated with demo data.
• OAuth2 / OpenID Connect — for organizations that already run an identity provider.
• Enterprise SSO — via an OIDC-compatible provider. Keycloak is the recommended choice for enterprise deployments that want self-hosted SSO without depending on a cloud identity service.

Authentication sits behind a clear abstraction layer in the backend, so a deployment can move from local auth to Keycloak (or another OIDC provider) without changing any business logic elsewhere in Open Gauge.

Roles (RBAC)

Every user has exactly one role, which governs what they can see and change. This is the account's only privilege flag — there is no separate "superuser" bit; Super Admin capability comes entirely from role == superadmin:

This is a system-wide grant, separate from the organization role (member/admin) a user has within a specific organization — managing a given organization's profile, members, and join requests is governed by that org-scoped role, not this one (Super Admin is the only global role with an override into organization management). See Organizations.

Protected endpoints reject unauthenticated requests, and role checks are enforced on the backend (not just hidden in the UI) — see the Auth and Admin sections of the API Reference for the exact endpoints each role can reach.

Profile picture

Every user can set a profile picture from Settings → Profile. It appears in the circular avatar in the top-right of the top bar and on the user's profile page (/users/{id}, reached by clicking a name anywhere it's mentioned — audit logs, activity, etc.). Users without a picture fall back to their initials. Uploads are limited to image files under 5MB and are stored in MinIO like any other attached file (see Data model & concepts).

Signatures

Every user with a role other than viewer can set a signature from Settings → Profile, either by uploading a transparent-background PNG or by drawing it directly with the mouse (or touch/pen) on a canvas — either way, the result is stored as a transparent PNG. While drawing, Undo reverts the last stroke and Erase toggles an eraser mode that removes ink under the pointer, so a mis-drawn portion can be corrected without clearing the whole canvas (that's still what Clear does).

Unlike a profile picture, a signature is cryptographically bound to the account:

1. The first time a user sets a signature, Open Gauge generates an Ed25519 keypair for them. The private key is encrypted at rest (AES-256-GCM, keyed from the app's SECRET_KEY) before it's stored — this protects against a database-only leak (a dump or backup theft), though it does not protect against compromise of the running app process itself, which is the practical ceiling for a self-hosted deployment with no external key-management service.
2. Open Gauge signs a canonical envelope — the user's ID, the SHA-256 hash of the exact image bytes, and a timestamp — with that private key. Both the signature image and the resulting signature bytes are stored.
3. The public key never changes once generated (replacing the signature image reuses the same keypair) and is available to any authenticated user via GET /users/{id}/signature/public-key, so a certificate — or any other consumer — can independently re-verify that a signature image is authentic and unmodified.

Replacing a signature does not delete the previous one — it's revoked (kept, marked inactive) so historical certificates that reference an older signature version remain independently verifiable. This mirrors how calibration history is never overwritten, only superseded.

A signature set this way is what certificates will use to visually and cryptographically attest to who performed a calibration.

Session tokens

Once authenticated, the frontend and any API client carry a session token on subsequent requests. See Auth in the API Reference for the exact login/refresh/logout endpoints and payload shapes.