v0.3.0

0.3.0 (2026-08-26)

Features

• remember application cookies, and add config remove-domain (dcfbdfc)

Fixes

• keep the config at ~/.albauth.toml (a443711)
• return binary bodies intact, and stop treating every 401 as expiry (7c919af)

---

Upgrading from 0.2.0

Three behaviours changed. None requires you to do anything, but each is worth knowing.

A 401 no longer triggers re-authentication by default.
It used to mean "the load-balancer session expired", so albauth opened a browser, ran the identity-provider flow, retried, failed again, and reported auth_loop. But almost every API behind a load balancer also authenticates its own callers, so a 401 is usually the application refusing the request — and re-authenticating cannot possibly fix that. Measured against Grafana and Hasura, the old behaviour cost a surprise browser window and a three-minute stall on a request that could never have succeeded.

Set treat_401_as_expired = true per domain if your listener rule uses OnUnauthenticatedRequest = "deny", or if you sit behind oauth2-proxy or Traefik forwardAuth, where the 401 really is the proxy.

Binary responses come back base64-encoded.
A response that is not valid UTF-8 — a PNG, a spreadsheet, a PDF — used to be returned as a string, which silently replaced the invalid bytes. Grafana's /render output and Metabase's exports were corrupt with no sign of it. Such bodies now arrive base64 with "body_base64": true alongside. Text responses are unchanged.

Requests within a server process now share application cookies.
Some tools issue a token in one response and require it back in the next, paired with a session cookie set at the same moment — Jenkins' crumb and Superset's CSRF token both work this way. albauth now keeps a per-domain cookie jar, so those writes work. The jar is in memory only, excludes the load balancer's own cookies, is cleared by auth_logout, and Set-Cookie is still stripped from every response, so cookie values never reach the caller.

The consequence is that requests are no longer wholly independent of one another. That is the point of the feature, but it is a change in how albauth behaves.

The config moved to ~/.albauth.toml — the same path on every operating system. Nothing breaks: a config already under $XDG_CONFIG_HOME, or where an earlier version wrote it, is still found and used. Only a fresh install gets the new location. The old macOS location was ~/Library/Application Support/albauth/config.toml, whose space made an unquoted cat $(albauth config path) fail as though the file were missing.

Also in this release

albauth config remove-domain <name> — the counterpart add-domain was missing. It preserves your comments, deletes the now-orphaned session, and refuses to leave you with a config that has no domains.

What this was tested against

Eleven applications, each run in a container behind a load balancer with a real authenticate-oidc rule and driven end to end: Grafana, Hasura, Metabase (API key and session cookie), Vault, RabbitMQ, Loki, Prometheus, MinIO, Superset and Jenkins. Also oauth2-proxy and Traefik forwardAuth in front of Dex, with a real browser completing the login — albauth is not AWS-specific, and docs/compatibility.md records what works, what does not, and which of those were measured rather than inferred.