Abstract

GAUTH is an authentication service you run yourself. It is a FastAPI process, a SQLite file, and a container, and it exists so that every other service in the stack stops re-inventing accounts. It issues short-lived Certified Gump Tokens (CGT) to app users, exposes a small public API for token issuance and introspection, and keeps an internal management API for the operator. It is open source under the World Gump Licence.

The problem

Authentication is the part of a project that is always finished last and always wrong first. It starts as a users table and a password hash, grows a reset flow, then a session store, then API keys, then an OAuth redirect for the one integration that needs it, and by the end there are four services with four ideas of what a user is. The work is not interesting, it is not differentiating, and it is the part most likely to be quietly insecure.

The alternative is usually a hosted identity provider: a per-month bill, a vendor in the login path, and a data model you do not control. For a small operator with a handful of apps, that is a worse trade than the code.

The model

GAUTH is deliberately an internal deployment, not a multi-tenant SaaS. There is one operator, a handful of apps, and the people who sign in to them.

master admin (environment only)
  ├── sub-admins (role: admin or moderator)
  └── apps
        └── app users

• Master admin — credentials from the environment, full access, never stored in the database.
• Sub-admin — a database account. admin sees every app; moderator sees only assigned apps and manages their users.
• App — an app_key (public) and an app_secret (private, shown once). Each app has its own user pool, portal, and optional skin.
• App user — a uid like a_9k2m4x, scoped to exactly one app.

There are no tenants, no client self-service, and no public administrator signup. Those are features of a product that has to serve strangers. GAUTH serves one operator.

What you get

• A browser portal per app at /apps/{app_key}/ with login, optional signup, profile, password change, API keys, and account deletion.
• Global skinning with per-app overrides: brand name, logo, colours, font, footer, support link.
• A public API for token issuance, identity, introspection, and revocation.
• An internal management API at /internal/v1 for your own services, guarded by an admin key and reachable only on the private network.
• An OAuth authorization-code flow for browser redirects.
• Two-ring login throttling: strict for administrators, lenient and tunable for app users.
• Built-in HTML documentation at /docs and /admindocs, rendered from the repository's markdown.
• A single-file agent manual at /skills.md, so a machine can read the API without a human summarising it.

The token

A CGT is short-lived and scoped to one app. Services verify it by calling /api/v1/introspect with app credentials or the admin key, or by trusting the claims in /api/v1/userinfo when the token is presented as a bearer. Revocation is a row, not a cache invalidation problem. Long-lived keys exist for machines, are listed per user, and can be revoked individually.

The point is that identity is a network call with a documented shape, not a shared secret copied into five config files.

Deployment

git clone https://github.com/3211/gauth.git
cd gauth
cp .env.example .env
# fill in GAUTH_MASTER_PASSWORD and GAUTH_ADMIN_API_KEY
docker network create gumpnet 2>/dev/null || true
docker compose up -d --build

The container binds 127.0.0.1:8081 only. nginx terminates TLS in front of it, and sibling containers reach it at http://gauth:8080 over the gumpnet network. Nothing is exposed to the internet except through the proxy.

Theming

The global theme is the default for every portal and the admin UI; each app can override any field. Fields are values, not CSS: brand_name, product_name, tagline, logo_url, primary, bg, panel, chrome, field, ink, line, font, footer_text, support_url. There is no raw CSS field, so a sub-admin cannot inject script into a login page.

What it is not

GAUTH is not a social login aggregator, not a directory service, and not a billing system. It does not do SAML, SCIM, or enterprise federation. It does one thing: give an app a stable user identity and a token that other services can check. If you need the rest, you need a different product, and that is fine.

Licence

GAUTH is released under the World Gump Licence. The source is public, the licence is ours, and the canonical signed text ships in the repository at licence/.