Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Configuration

This page helps you change how auth-service and sourceorigin-web are configured, in a deployed environment or on your machine, and lists every variable they read.

Both read their configuration from environment variables at startup, and refuse to start when one is missing or invalid. A secret is never set directly: its variable says where to read it, through env://NAME or file:///absolute/path.

Change a setting in an environment

  1. Change infra/piqueld.toml:
    • the [spec.services.environment] table of the auth or web service, for a value every deployment shares;
    • or a variable, under [spec.environments.<name>.variables] or [spec.previews.variables], for a value one deployment sets.
  2. Merge the change to main. Staging deploys it.
  3. Promote staging to apply it to production.

A value that names a secret, such as AUTH_SMTP_PASSWORD, points at the file piqueld mounts. To change the secret itself, see secrets.

Generate a key

For a local configuration, generate the key-encryption key or a token digest key:

just auth generate-secret /absolute/path/key-encryption-key

The recipe writes 32 random bytes as unpadded base64url text, with the OpenSSL CLI, and refuses to overwrite a file. Generate an audit key with openssl rand -hex 32 > /absolute/path/audit-key.

Keep the keys across restarts, and give every replica the same ones. piqueld generates its own for each environment (see secrets). To change the token digest key, follow changing the token digest key.

Run auth-service locally

Apply migrations, then serve:

just db migrate
just auth serve

Deployed images run the executable’s same migrate and serve subcommands.

auth-service

Service

  • AUTH_PUBLIC_BASE_URL: The exact origin auth serves, such as https://auth.sourceorigin.dev. It is the OpenID Connect issuer and the passkeys’ relying party, so it must use a domain name. Required.
  • AUTH_PUBLIC_LISTENER: The address auth listens on, behind the HTTPS ingress. Default: 127.0.0.1:8080.
  • AUTH_WEB_ORIGIN: sourceorigin.dev’s origin. Every page links its privacy policy and terms, and discovery advertises them. Default: https://sourceorigin.dev.
  • AUTH_ADMIN_LISTENER: The address the admin dashboard listens on, such as 0.0.0.0:8081. Set it together with AUTH_ADMIN_ORIGIN; without them, auth serves no dashboard. Only a private route may reach this listener.
  • AUTH_ADMIN_ORIGIN: The admin dashboard’s origin, such as https://admin.sourceorigin.dev. Set it together with AUTH_ADMIN_LISTENER.
  • AUTH_INVITE_REQUIRED: false lets anyone sign up; true, the default, requires an invitation. It changes signing up only: existing accounts keep their access.
  • AUTH_REQUESTS_PER_MINUTE: How many requests one client may make a minute in each rate category, such as pages, sign-in and tokens. Default: 120.
  • AUTH_TRUSTED_PROXIES: The proxies in front of auth, as comma-separated IP addresses or CIDR ranges. Each must overwrite X-Forwarded-For with the one client address, which auth then throttles on. A missing or ambiguous header from one of them is refused, and the header is ignored from any other peer. Unset, auth trusts PIQUELD_INGRESS_PROXIES, and without either it throttles on the direct peer’s address.
  • PIQUELD_INGRESS_PROXIES: The gateway ranges piqueld gives every service, trusted when AUTH_TRUSTED_PROXIES is unset.

Database

  • AUTH_DATABASE_URL: The PostgreSQL URL every command connects with. Over TCP it requires sslmode=verify-full, or an explicit sslmode=disable on a trusted private network. For a local Unix socket, use localhost as the host and the socket’s absolute directory as the host parameter, such as postgres://USER:PASSWORD@localhost/sourceorigin?host=/run/postgresql&sslmode=disable. Required.
  • AUTH_DATABASE_PASSWORD: Where to read the database password, through env://NAME or file:///path, when the URL leaves it out.
  • AUTH_DATABASE_OWNER_URL: The schema owner migrate connects as instead, in the same format as AUTH_DATABASE_URL, which audit prune uses too. migrate then creates or resets the role AUTH_DATABASE_URL names, with the AUTH_DATABASE_PASSWORD password and only row access to auth’s tables. The owner must be a superuser.
  • AUTH_DATABASE_OWNER_PASSWORD: Where to read the schema owner’s password, as for AUTH_DATABASE_PASSWORD.

Keys

  • AUTH_KEY_ENCRYPTION_KEY: Where to read the key that seals signing keys in the database: 32 bytes as unpadded base64url text, through env://NAME or file:///path. A trailing newline is ignored. Required. It can’t be changed yet: the stored signing keys would no longer open.
  • AUTH_TOKEN_DIGEST_KEY: Where to read the key under which refresh tokens, authorization codes and pending logins are stored as HMAC digests. Its raw bytes are the key, at least 32 of them. Email verification, recovery and unsubscribe links derive from it too. Required. Replacing it at once ends every refresh token and every login in progress, so change it in two deploys.
  • AUTH_TOKEN_DIGEST_KEY_ACCEPTED: Where to read another token digest key, accepted but never used for new digests: the next key before it becomes current, or the old one after.
  • AUTH_AUDIT_KEY_PROVIDER: Where to read the key that signs audit checkpoints: a 32-byte Ed25519 seed as 64 hex characters. Required.

Sign-in providers

  • AUTH_GITHUB_CLIENT_ID: The client ID of auth’s GitHub OAuth app. Set, it turns GitHub sign-in on and requires AUTH_GITHUB_CLIENT_SECRET; unset or empty, GitHub is off and its secret isn’t read.
  • AUTH_GITHUB_CLIENT_SECRET: Where to read the GitHub OAuth app’s client secret, through env://NAME or file:///path. It is read and checked at startup: restart auth after changing it.
  • AUTH_GOOGLE_CLIENT_ID: The client ID of auth’s Google OAuth client, as AUTH_GITHUB_CLIENT_ID is GitHub’s.
  • AUTH_GOOGLE_CLIENT_SECRET: Where to read the Google OAuth client’s secret, as for AUTH_GITHUB_CLIENT_SECRET.

Email

  • AUTH_SMTP_URL: The SMTP relay auth sends through: smtps://USER@HOST:465, with implicit TLS, or smtp://USER@HOST:587, which requires STARTTLS. Only a loopback host, such as a local Mailpit, may be reached without TLS. Unset, email is off: adding an address is refused and queued messages are dropped.
  • AUTH_SMTP_PASSWORD: Where to read the password of the URL’s user, through env://NAME or file:///path. Required when the URL names a user; never put it in the URL.
  • AUTH_EMAIL_FROM: The sender of every message. Default: Origin Account <[email protected]>.

Telemetry

Both services read the standard OpenTelemetry variables, such as OTEL_EXPORTER_OTLP_ENDPOINT and OTEL_RESOURCE_ATTRIBUTES, and RUST_LOG: see telemetry.

sourceorigin-web

sourceorigin-web serves sourceorigin.dev: the homepage, the privacy policy at /privacy and the terms of service at /terms. It keeps no state, and needs no database or secret. It relies on auth only to sign people in: it links auth’s pages, and redirects every other path, with its query, to the same one on auth (see sourceorigin.dev). Its /health answers 204 for piqueld’s probe, and its telemetry’s service.name is sourceorigin-web.

Service

  • WEB_AUTH_ORIGIN: Auth’s origin, such as https://auth.sourceorigin.dev. sourceorigin.dev links its pages and redirects every other path there. Required.
  • WEB_LISTENER: The address sourceorigin-web listens on, behind piqueld’s gateway. Default: 127.0.0.1:8080.

The policies are HTML in apps/web/assets/policies/. Keep them true to what the code does: a change to what auth stores, keeps or shares changes them too.