Skip to content

docs(auth): do not set AUTH_SIGNING_PUBKEY on a Fleet behind password-mode Auth - #1513

Merged
jzhao234 merged 1 commit into
mainfrom
docs/central-auth-omit-static-pubkey
Sep 15, 2026
Merged

jzhao234 merged 1 commit into
mainfrom
docs/central-auth-omit-static-pubkey

Conversation

@jzhao234

Copy link
Copy Markdown
Contributor

TLDR

The central-Auth guide told operators to set Auth's public key on Fleet. That variable is also what turns on the legacy "Use Elcano email" button, and a password-mode Auth cannot complete that flow, so following the guide gave users a second sign-in button that dead-ends. The guide now says to leave the variable unset and explains that back-channel logout still verifies through Auth's JWKS.

Problem

login/page.tsx renders the magic-link button when AUTH_SIGNING_PUBKEY is non-empty, independently of FLEET_OIDC_*. Password-mode Auth mints a host-only __Host-auth_session cookie, never the shared elcano_auth cookie, so the legacy round-trip returns the browser to /login with nothing Fleet accepts. Meanwhile backchannelLogout.ts merges static keys with the JWKS cache and its tests verify a token with the key available only from JWKS, so the static key was never required for central mode.

Fix

  • Remove AUTH_SIGNING_PUBKEY from the central-mode variable block and add a paragraph saying not to set it behind password-mode Auth, why (the legacy button), what still works (JWKS-based logout verification, one-sided key rotation) and the trade-off (Fleet must reach Auth when a logout arrives; Auth retries for seven days). The variable remains documented for deployments that really use the magic-link cookie.
  • Code is unchanged; a separate explicit legacy-mode flag is the longer-term fix and is tracked in the Auth review decision list.

Tests

Documentation only.

…-mode Auth

TLDR

The central-Auth guide told operators to set Auth's public key on Fleet. That
variable is also what turns on the legacy "Use Elcano email" button, and a
password-mode Auth cannot complete that flow, so following the guide gave
users a second sign-in button that dead-ends. The guide now says to leave the
variable unset and explains that back-channel logout still verifies through
Auth's JWKS.

Problem

login/page.tsx renders the magic-link button when AUTH_SIGNING_PUBKEY is
non-empty, independently of FLEET_OIDC_*. Password-mode Auth mints a host-only
__Host-auth_session cookie, never the shared elcano_auth cookie, so the legacy
round-trip returns the browser to /login with nothing Fleet accepts. Meanwhile
backchannelLogout.ts merges static keys with the JWKS cache and its tests
verify a token with the key available only from JWKS, so the static key was
never required for central mode.

Fix

- Remove AUTH_SIGNING_PUBKEY from the central-mode variable block and add a
  paragraph saying not to set it behind password-mode Auth, why (the legacy
  button), what still works (JWKS-based logout verification, one-sided key
  rotation) and the trade-off (Fleet must reach Auth when a logout arrives;
  Auth retries for seven days). The variable remains documented for
  deployments that really use the magic-link cookie.
- Code is unchanged; a separate explicit legacy-mode flag is the longer-term
  fix and is tracked in the Auth review decision list.

Tests

Documentation only.
@jzhao234
jzhao234 merged commit 257f08e into main Sep 15, 2026
15 checks passed
@jzhao234
jzhao234 deleted the docs/central-auth-omit-static-pubkey branch September 15, 2026 18:20
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant