Historical Atlas Access Portal
The original prompt, shown in full as plain text.
Prompt
# SPEC: Authentication and Authorization
Status: draft. Part of [SPEC.md](../SPEC.md).
## Purpose
Define how users are identified and what they are allowed to do.
## Requirements
- Authentication, user management and role assignment are provided by a
self-hosted Keycloak.
- The application does not store passwords, implement its own login flow or
build its own user administration.
- The backend authenticates every request that is not explicitly public,
through the session established by a login at Keycloak.
- Authorization distinguishes at least viewing and editing locations; the
roles are defined here.
- The first public version has basic user management: an admin can create
accounts with a role, list them, change roles, disable or delete accounts
and reset passwords without an email service. Users can log in, log out
and change their own password. Self-registration is not offered.
- Login and account screens are available in English and German.
## Decisions
Decided in [AVARC-19](../tasks/finished/TASK-auth-provider-revisit.md),
which replaced the earlier choice of Ory Kratos
([AVARC-13](../tasks/finished/TASK-ory-auth-design.md)). Keycloak is
Apache-2.0 licensed.
- **Component:** Keycloak, in a single realm `avarc`. It provides the login,
logout, account (change password) and admin screens, so none of them are
built in this project.
- **Protocol and session model:** OpenID Connect, authorization code flow
with PKCE. The backend is the OIDC client (the confidential client
`avarc-web`) and the only component that talks to Keycloak; the frontend
talks to the backend. The backend keeps the tokens in a server-side
session; the browser holds only the backend's HttpOnly session cookie,
never a token. The access token carries the explicitly granted roles
only, so a user without any is a `viewer`. The single origin served by
the ingress (see [SPEC-ingress.md](SPEC-ingress.md)) keeps CORS out of
the picture. Validating bearer access tokens, for clients without a
browser such as the MCP server, is added when such a client is taken up.
- **Access policy:** login is required for everything; there is no anonymous
access to the application or its API. Public exposure of data is the job
of a separate read-only map server (post-MVP, see below), not of an
anonymous mode in the backend.
- **Roles:** `viewer`, `editor` and `admin`, where `editor` includes
`viewer` and `admin` includes `editor`.
- `viewer`: list and read locations.
- `editor`: additionally create, update and delete locations.
- `admin`: additionally manage users and grant and revoke roles.
- Every authenticated user is implicitly a `viewer`. Editor and admin are
explicit grants.
- **Backend module:** the backend code of this area is the application
module `auth` ([SPEC-backend.md](SPEC-backend.md)); other modules reach
it only through its top-level package.
- **Login and logout:** the pages `/login` and `/logged-out` belong to the
frontend ([SPEC-frontend.md](SPEC-frontend.md)); the password form is
Keycloak's. The backend offers, under `/api/auth/`:
- `GET /api/auth/login/keycloak` starts the login: a redirect to the realm's
authorization endpoint with PKCE. `GET /api/auth/callback` receives the
code, exchanges it with the client secret, creates the session and
redirects to `/`. A failed login redirects to `/login?error`.
- `POST /api/auth/logout` ends the session and redirects to Keycloak's
end-session endpoint, which returns to `/logged-out`. It requires the
CSRF token.
- `GET /api/auth/me` answers `200` with `username`, `name`, `email`,
`roles` and `csrfToken` of the logged-in user, or `401`.
- Every other request without a session, `/api/` included, answers `401`;
only these login endpoints are public. The actuator is on a port of its
own that the ingress does not route, see [SPEC-backend.md](SPEC-backend.md).
- The backend reaches Keycloak by its internal address for the token and
key requests, and sends the browser to the public one
(`<public origin>/auth/realms/avarc`); the issuer of the tokens is the
public one. It reads the realm's endpoints from its configuration, not
by discovery, so it starts without Keycloak. The client secret is a
file secret.
- The session cookie is HttpOnly, `Secure` (except on the plain-http
developer origin) and `SameSite=Lax`; the session expires after 30
minutes without use and is kept in memory, so a restart of the backend
logs everyone out.
- **Role storage:** the roles are Keycloak realm roles, with the inclusion
above modelled as composite roles and `viewer` as the realm's default
role. The token carries them and the backend maps them to permissions in
code. The user id (`sub` claim) is what is stored as `created_by` /
`updated_by` in [SPEC-locations.md](SPEC-locations.md). Per-location
permissions are not part of the MVP.
- **Application users:** Keycloak owns accounts, credentials and roles. The
application keeps its own `User` per Keycloak subject for preferences and
a copy of the profile claims, created at the login
([SPEC-users.md](SPEC-users.md)).
- **Hosting:** Keycloak runs as the service `keycloak` in the Docker Compose
project (see [SPEC-deployment.md](SPEC-deployment.md)). Its storage is a
database of its own (`keycloak`) in the application's database server,
created on demand at startup (decided, see
[SPEC-deployment.md](SPEC-deployment.md), "Keycloak's database"). Production mode is used in every
environment; the developer deployment differs only in its plain-http
origin.
- **Image:** introduced in [AVARC-32](../tasks/finished/TASK-keycloak-image.md).
Keycloak runs from an image of this project, built on the pinned Keycloak
image by a `Dockerfile` in the module `avarc-server-keycloak` (see
[SPEC-releases.md](SPEC-releases.md) for versioning and publishing). It
holds the realm import file, the start script as the entrypoint, and
Keycloak's build-time options (database vendor, health endpoints, the
`/auth` relative path) applied with `kc.sh build`, so that it starts with
`--optimized`. Nothing environment-specific or secret is in it: hostnames,
the database address and every secret are runtime configuration, the
secrets read from `/run/secrets`. The Keycloak version is the tag in the
`FROM` line of the `Dockerfile`, which Renovate updates. A `Dockerfile`
built with `docker build` is the exception to the buildpack build of the
other images. Paketo with a `Procfile` was tried and can run Keycloak, but
needs the distribution downloaded into the build, a full run image for
`bash`, and cannot run `kc.sh build`, which loses the optimized start; a
Dockerfile of a few lines avoids all of it.
- **Observability** ([AVARC-25](../tasks/finished/TASK-observability-identity.md),
conventions in [SPEC-observability.md](SPEC-observability.md)):
- Keycloak logs JSON to standard output (`--log-console-output=json`) with
its own field names (`timestamp`, `level`, `message`, `loggerName`, ...);
the log level is Keycloak's default (info). The collector adds the
service from the container. There is no request ID in these lines and no
Keycloak access log: the access log cannot leave out the query string,
which carries login session codes, and the ingress logs every request to
Keycloak with its request ID and no query string.
- The metrics (`--metrics-enabled`, including `keycloak_user_events_total`
by event, error and realm) and the health endpoints (readiness is the
Compose health check) are on the management port 9000, under `/auth`,
which the ingress never routes; the Compose service is on the metrics
network. Both are build-time options, set in the `Dockerfile`.
- Login and admin events (logins, failed logins, brute-force lockouts, user,
role and password changes, without the content of the change) are enabled
in the realm and kept for 30 days in its event store, which admins read in
the console under Events. They are not written to the logs: a failed
login names the login name, which is personal data. The counts are in the
metrics (a lockout is a login with the error `user_temporarily_disabled`).
The realm import file carries the settings; for a realm that exists,
`deploy/configure-keycloak-events.sh` applies them.
- No alert is raised for failed logins or lockouts in the first version;
the metrics make a dashboard or an alert possible later.
- **Configuration as code:** the realm (roles, client, login and password
settings, locales) is kept in the repository as a realm import file
without secrets, inside the image; secrets such as the client secret come
from the environment's secrets file. Keycloak imports it only when the
realm does not exist yet, so a change of the file reaches an existing
environment only through the admin console or its CLI; a new image version
carries it to new realms only.
- **User administration:** by admins in the Keycloak admin console of the
`avarc` realm (users, roles, disable, delete, set a temporary password
that must be changed at the next login). The initial admin account, and
optionally editor and viewer accounts of an environment, are created by a
provisioning script in `deploy/` from credentials in the environment's
secrets file; it skips accounts that already exist. Further users are
created by a second script, which takes email addresses and makes them
editors, or admins with an option; each gets a random one-time password
that must be changed at the first login, or, with an option, a password
read per user that stays valid. The backend has no
user-management endpoints.
- **Account policies:** self-registration, "forgot password" and email
verification are disabled because there is no email service in the MVP;
admins reset passwords. Brute-force protection is enabled. Users change
their own password in Keycloak's account console. English and German are
the enabled locales.
- **Exposure via the ingress:** builds on the `/auth/` prefix of
[SPEC-ingress.md](SPEC-ingress.md).
- Only the realm endpoints and static resources of the `avarc` realm are
routed (login, token, keys, logout, account console). The admin console,
the admin REST API, the `master` realm and the management and health
port are never routed by the ingress; admins reach the console on the
tailnet under a name of its own (see
[SPEC-deployment.md](SPEC-deployment.md)).
- Keycloak is served under `/auth` without prefix stripping and is
configured with the public origin as its hostname, trusting the
forwarded headers of the ingress.
- Cookies are host-only and `Secure`; the redirect URIs of the client are
limited to the application's own origin.
## Social login
Decided in [AVARC-54](../tasks/TASK-social-login.md). Google is implemented and runs on stage; Google on dev and prod follows when needed.
- **Providers:** Google. Other providers are added the same way, one
identity provider of the realm each.
- **Apple is rejected.** Sign in with Apple needs a paid developer
membership (yearly), which would have to stay active for the login to keep
working, and a client secret that expires after at most six months and must
be regenerated and rolled out before then, per environment. The cost and
the recurring upkeep are out of proportion for a low-traffic application
with a small user base, and a lapse would lock out the people who use it.
The decision is revisited if users ask for it.
- **Keycloak is the broker.** Users choose the provider on the login page of
the `avarc` realm; the backend, which is the only OIDC client, and the
frontend do not change. The application database keeps referring to the
Keycloak user id (`kc_subject`), whatever the provider.
- **Sign-up stays closed to roles.** A user who signs in with a provider for
the first time gets a Keycloak account without any role, so cannot do
anything until an admin grants one in the console, as for any new user.
Self-registration with a password stays disabled.
- **Linking.** A provider identity is never linked to an existing account
automatically. The first-login flow of the realm (`avarc-first-broker-login`,
created by `deploy/create-google-idp.sh`) creates a new user from
the provider's name and email, without a role and without a profile
review, when no account has that email. When one has, the login is denied
with a message telling the user to sign in with the password and link the
provider under Account, Linked accounts: the user proves control of both.
Keycloak's own flow would verify an existing account by an email that this
installation cannot send, and trusting the provider's email blindly would
link accounts whose email the provider has not verified. Linking
automatically when the provider reports the email as verified is a later
improvement ([AVARC-55](../tasks/TASK-automatic-linking.md)). The link is
the provider's stable account id, not the email address, so a later change
of email does not break it. The email of the provider is not trusted as
verified by Keycloak, and no tokens are stored.
- **Personal data.** Only name and email are taken from the provider, and
nothing else is requested (scopes `openid`, `email`, `profile`). What the
provider passes on is part of the privacy statement
([AVARC-9](../tasks/TASK-licensing-decision.md)).
- **Configuration.** The OAuth client is registered with the provider per
environment; its id and secret come from the environment's secrets file and
never from the repository. The identity provider is configured in the realm
by a script in `deploy/` that is safe to repeat, because a change of
`avarc-realm.json` does not reach an existing realm.
### Surviving a rebuild of Keycloak's data
The provider links (provider account id, Keycloak user id) and the roles live
only in Keycloak's database, and the application's users refer to the user
id. If that database is lost without a restore, every user logs in as a new
person: new id, no roles, no preferences, no tie to earlier contributions.
- The primary protection is the backup of the databases
([SPEC-deployment.md](SPEC-deployment.md)); a restore of the dump brings
everything back, local passwords included.
- A second protection works without a dump. A script exports the users of the
realm through the Keycloak Admin API: id, username, email, names, enabled
flag, attributes, the provider links and the realm roles. The script is
`deploy/export-keycloak-users.sh [--stage]`; it writes
`keycloak-users-<yyyymmdd-hhmmss>.json` (the realm, the time and the list of
users) into the backups directory of the environment, next to the dumps, and
the file appears under its final name only when complete. It is gitignored,
has mode 0600 and is produced by the same nightly run as the dumps
(`deploy/backup-db.sh`), under the same retention; a failed export makes
that run fail, after the dumps are taken. It holds personal data. The
default role of the realm is not exported, because every user has it.
- A restore script, `deploy/restore-keycloak-users.sh [--stage] [FILE]` (default the
newest export), reads that file and recreates the users through the
`partialImport` endpoint, with their original ids, links and roles, and
skips what exists, so running it twice changes nothing. The realm and its
identity providers must exist first; the script stops with a message when a
provider of a link is missing.
- Local passwords are not available through the API: a restored local user
gets a new one-time password, as with `deploy/create-user.sh`, printed once
as "EMAIL PASSWORD" on the standard output, for the users it created
only. Users of a provider have no local password and lose nothing.
- Direct changes to Keycloak's tables are not a restore method.
## Public read-only map server (post-MVP)
Anonymous viewing is served by a separate, read-only map server added after
the MVP, outside the authenticated application. It exposes only data
intended for the public, has no write capability and no Keycloak
dependency. It gets its own ingress prefix and is specified when it is taken
up.
## MCP server (post-MVP)
The MCP server authenticates AI assistants with tokens issued by the same
Keycloak realm; Keycloak supports this natively, so no further identity
component is expected. The details are specified when it is taken up.
## Open questions
- Which locations are public for the read-only map server.
- The capacity of the production host for Keycloak.