From 2836bd04a0ee685f1a6a2d8ebc2ffb623675e8a2 Mon Sep 17 00:00:00 2001 From: jzhao234 Date: Tue, 15 Sep 2026 18:06:02 +0000 Subject: [PATCH] docs(auth): do not set AUTH_SIGNING_PUBKEY on a Fleet behind password-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. --- docs/features/central-auth-integration.md | 17 ++++++++++++----- 1 file changed, 12 insertions(+), 5 deletions(-) diff --git a/docs/features/central-auth-integration.md b/docs/features/central-auth-integration.md index b06bc821..afda3dd1 100644 --- a/docs/features/central-auth-integration.md +++ b/docs/features/central-auth-integration.md @@ -16,13 +16,20 @@ FLEET_OIDC_ISSUER=https://auth.example.com FLEET_OIDC_CLIENT_ID=fleet-client-id FLEET_OIDC_CLIENT_SECRET= FLEET_OIDC_SCOPES=openid email -AUTH_SIGNING_PUBKEY= ``` -Fleet also reads Auth's published `/jwks.json` (cached ten minutes, refreshed -once when a logout token names an unknown `kid`), so an Auth signing-key -rotation needs no Fleet env edit. Keep one static key as bootstrap and -offline fallback. +Do **not** set `AUTH_SIGNING_PUBKEY` on a Fleet that signs in through a +password-mode Auth. That variable is the switch for the legacy magic-link +path above: the login page shows "Use Elcano email" whenever it is set, and +a password-mode Auth never mints the shared `elcano_auth` cookie, so that +button dead-ends. Fleet verifies Auth's signed back-channel logout tokens +from Auth's published `/jwks.json` (cached ten minutes, refreshed once when a +logout token names an unknown `kid`), so a signing-key rotation needs no +Fleet env edit and no static key is required. The trade-off is that Fleet +must be able to reach the Auth host when a logout arrives; Auth retries +failed deliveries for seven days. Set `AUTH_SIGNING_PUBKEY` only where the +legacy magic-link cookie is actually in use; it then also serves as an +offline fallback for logout verification. Register the exact callback and signed logout endpoint on Auth: