Accepted12 Nov 2026
0065. Move sign-in to Spring Security after the port, keeping its HTTP contract
Context and Problem Statement#
ADR-0037 signed people in with plain Spring MVC. While the Python and Java APIs shared one database, each had to accept the other's session cookies, CSRF tokens and state cookies, and answer with FastAPI's errors in FastAPI's order. Spring Security would have had every part replaced to keep that. The owner accepted it on condition that it is weighed again at stage 6 of the port, once the contract can change. The Python API is now gone. Should sign-in move to Spring Security, and if so, how?
The code today: access (29 files, 940 lines of code) and signin (28 files, 1,020), about
1,960 lines, of which roughly 700 do sign-in itself. The rest is workspace roles, client
addresses, trusted proxies and accounts, which stay whatever is decided. tokens (210) manages
API tokens. web holds the security headers, CORS and the body-size limit.
What must hold#
The contract is now the web app and the people who hold API tokens, not a second API. The
black-box suite (archsim-api-tests) checks it.
- API tokens:
Authorization: Bearer asim_pat_…, stored as their SHA-256, each read-only or not and maybe bound to a workspace. Tokens in use must keep working. - Browser sessions: the
__Host-archsim_sessioncookie (HttpOnly,Secure,SameSite=Lax) and thesessionstable, which stores the secret's SHA-256, its expiry and where it was used. Signing out ends one session or all of them. - CSRF on cookie requests that change something: the web app reads
__Host-archsim_csrf(readable,SameSite=Strict) and sends it inX-ArchSim-CSRF(apps/web/src/lib/session.ts). An API token needs none. - Sign-in with GitHub or Google: authorization code with PKCE
S256, anextpath checked to stay on the site,/signin?error=<reason>on failure, and GitHub's rule that the account's email is its verified primary one. - Without
ARCHSIM_AUTH_MODE=oauth: everyone is the local user, and nothing asks to sign in. - Answers:
401withWWW-Authenticate: Bearerand{"detail": …}, which the web app reads, and403for a missing or wrong CSRF header. Public endpoints need nothing and ignore anAuthorizationheader. An unknown path is404whoever asks.
Status (12 Nov 2026), API tokens: a wrong API token is refused wherever it is sent but for
the two sign-in paths (below), so for a request that carries one, two sentences of "Answers" no
longer hold: that public endpoints ignore an Authorization header, and that an unknown path is
404 whoever asks. Spring Security's bearer token filter answers a revoked, expired, mistyped or
malformed Bearer token with the 401 above (WWW-Authenticate: Bearer, the same
{"detail": …}) before the request reaches an endpoint, so a public endpoint and an unknown path
answer it 401 too. A request with no token, or with credentials of another kind (Basic …),
still reaches the endpoint: public endpoints need nothing, and an unknown path is 404. Decided
in slice 2 under the owner's delegation, because the rule that a public endpoint ignores a token
came from matching FastAPI, which no longer binds; a token's holder is better told at once that
it is wrong than treated as anonymous, as GitHub's API does. The black-box suite's TokensTests
checks both. With sign-in, the resource server also answers its metadata (RFC 9728) at
/.well-known/oauth-protected-resource/api/v1, on the API's own address: it names the API and
the header as the one way to send a token. Since slice 5 (12 Nov 2026),
GET /auth/{provider}/login and /auth/{provider}/callback of a provider set up here are the
exception: Spring Security's OAuth2 login answers them before its bearer token filter, so a wrong
token sent there gets the same 302 as none. Decided under the owner's delegation, because both
are browser navigations, which never carry an Authorization header, so no token holder is
misled; refusing it there would take a branch in the chain and an answer of our own against
Spring's design. OAuthTests checks it, so a change to the filter order shows.
Status (12 Nov 2026), CSRF: a change a browser session signs in is refused without its
CSRF header wherever it is sent, so for such a request, the "Answers" bullet's 404 for an
unknown path (and 405 for a route that does not take the method) no longer holds: Spring
Security's CSRF filter answers the 403 above before the request reaches an endpoint. A change
without a session cookie still reaches its route. Decided in slice 4 under the owner's
delegation, for the reason given for tokens above: matching FastAPI no longer binds, and the
browser's own changes always carry the header (apps/web/src/lib/session.ts). Every change
that needs someone takes a person, so an unknown path stands for a public endpoint in the
black-box suite's TokensTests. As planned, the token is a random value in the
__Host-archsim_csrf cookie, returned in X-ArchSim-CSRF (a double-submit cookie), so a change
sends the cookie with the header. A browser signed in before keeps its cookie's old value as its
token, rather than getting a new one at its next /auth/me as the plan expected: the filter
compares the header with the cookie, and nothing has to change for it. The handler is the plain
one, reading the token from the header only: the _csrf form or query parameter the plain one
also takes would put the token in URLs, logs and Referer headers, and the web app sends the
header.
Status (12 Nov 2026), OAuth2 login: Spring Security's oauth2Login signs people in, as
planned. The registrations are Spring's GitHub and Google, with the site's addresses,
client_secret_post and PKCE for both. Spring makes the state (44 characters of base64url with
padding) and the verifier, which the signed __Host-archsim_oauth cookie keeps as before. Google
signs in through OpenID Connect: Spring Security checks the ID token's signature, issuer,
audience and nonce (kept in the cookie too), where the hand-written client read userinfo with
the access token. Spring keeps a provider's access token for each person signed in; the success
handler drops it once the account is read, as the hand-written client did. SignInController
keeps the two sign-in paths, which Spring's filters answer for the providers set up here, so a
provider that is not set up still gets its 404 and the OpenAPI document still lists them. The
start's 422 for a long next and its 429 are answered as the API answers them. A callback
for a provider set up here is Spring's, so where a code or state too long was refused 422,
a long state lands on /signin?error=state and a long code on /signin?error=provider (the
provider refuses it). Slice 6 marked ADR-0037 superseded and kept the callback to GET and
HEAD, as providers send the browser back, so another method is 405 as before. The callback's
own argument resolver and its OpenAPI customizer, the last of the hand-written sign-in, were kept
while an annotated List parameter split a value at its commas; once web.WholeQueryValue kept
a value whole (the same day), SignInController declared the callback's code, state and
error as it declares next, and both went.
Decision Drivers#
- Security code maintained and reviewed by Spring, where it fits: ADR-0007 chose Spring Boot partly for it.
- A reference for engineers: a Spring Boot app that signs people in is expected to use Spring Security, and code that doesn't is read with suspicion.
- The contract above, with the black-box suite as its check; tokens keep working.
- Each step small, test-first and releasable, as the port's stages were.
Considered Options#
- Stay with plain Spring MVC (ADR-0037 as it is)
- Spring Security for the protocol only: its OAuth2 client classes, no filter chain (ADR-0037's third option)
- Spring Security's filter chain for authentication, CSRF and OAuth2 login, authorizing per endpoint as today
Decision Outcome#
Chosen option: "the filter chain for authentication, CSRF and OAuth2 login", recommended as its own short track after stage 6. ADR-0037's main reason, the second API, is gone. What is left to write ourselves is small adapters to the tables and cookies we keep, and Spring then owns the OAuth2 protocol, PKCE, the CSRF filter and the request firewall.
How, keeping the contract:
- Authenticate in filters, authorize per endpoint.
authorizeHttpRequestspermits every request. The filters only put who is asking in theSecurityContext, and a controller parameter (Principal,Person, read from the context) answers401when it needs someone and finds no one. So public endpoints, unknown paths (404) and body errors keep their order. - API tokens: the resource server's opaque-token support, with an
OpaqueTokenIntrospectorover thetokenstable, applied only to requests that carryAuthorization. AnAuthenticationEntryPointwrites the401the web app reads. - Sessions: a
SecurityContextRepositoryover thesessionstable. It keeps the hashed secret, the expiry and "sign out everywhere". It replaces neither the table nor the cookie, and Spring Session is not used: it stores session ids as they are. - CSRF: Spring's
CsrfFilterwithCookieCsrfTokenRepository(readable cookie, named__Host-archsim_csrf, headerX-ArchSim-CSRF) and the plainCsrfTokenRequestAttributeHandler, so the header carries the cookie's value as the web app sends it (the default handler's masked tokens are for pages that render the token), required only of requests a session cookie authenticates. The HMAC token (Csrf,SigningKeys' CSRF key) goes. The web app's code doesn't change, and a signed-in browser gets a new token at its next/auth/me. - OAuth2 login:
oauth2Loginwith GitHub and Google registrations, PKCE for both, and anAuthorizationRequestRepositorythat keeps the request in the signed__Host-archsim_oauthcookie, so any instance can finish a sign-in another started. ADefaultOAuth2UserServiceextension holds GitHub's verified-email rule. Success and failure handlers start the session and redirect tonextor to/signin?error=<reason>.OAuthClient(the code exchange) goes. - Security headers: Spring Security's
headers()writes the onesSecurityHeadersFilterwrites today, which then goes. - Local mode: an authentication filter that gives every request the local user, in place of the token and session filters.
Plan, each slice test-first with the black-box suite unchanged unless the slice says otherwise:
spring-boot-starter-securitywith a chain that permits everything and authenticates no one; the resolvers still decide. The security headers move into the chain. Nothing in the suite changes.- API tokens through the introspector and the entry point;
Principalread from the context for tokens. - Sessions through the context repository;
Principalread from the context for sessions; the resolvers keep only workspace roles. - CSRF through
CsrfFilter. The contract changes here: the token's format. The suite checks CSRF by behaviour (a change without the header is refused), so it should pass as it is; the app'sCsrfTests, which check the HMAC tokens the Python API made, go with that code. - OAuth2 login. The suite's
OAuthTestsrun against the stand-in GitHub, which must speak what Spring's client sends (client_secret_basicby default; setclient_secret_postas today). - Delete what is left of the hand-written sign-in, and update ADR-0037 to
superseded by ADR-0065, with the app's README anddocs/api.md.
Consequences#
- Good, because the OAuth2 protocol, PKCE, CSRF and the request firewall (encoded slashes, path traversal) are Spring's code, kept up to date with Spring Boot's.
- Good, because a Spring engineer finds sign-in where they look for it, and workspace roles could later use method security.
- Good, because tokens and sessions stay where they are, as SHA-256 hashes, and nobody loses a token.
- Bad, because it is about six slices of security work on code that works and is tested: a week or two of sessions, with its own reviews.
- Bad, because some adapters stay ours (the context repository, the introspector, the signed state cookie, GitHub's email rule, the entry point), about a third of today's sign-in code.
- Bad, because the CSRF token's format changes, and anyone signed in when slice 4 ships gets a new token, which the web app fetches by itself.
- Bad, because Spring Security's defaults (sessions, redirects to a login page,
403pages) must each be switched off, or they change answers the suite checks.
Confirmation#
The black-box suite (OAuthTests, TokensTests and the rest) passes after each slice, against
the same stand-in GitHub, and the app's HostedPrincipalTests and SignInTests keep their
checks; CsrfTests and StateCookiesTests change with the code they test. An ArchUnit rule keeps
controllers away from SecurityContextHolder: they read who is asking from a parameter.
Pros and Cons of the Options#
Stay with plain Spring MVC#
- Good, because nothing changes, and the code is small, uses only JDK primitives and is tested against a stand-in provider.
- Bad, because the OAuth2 exchange, PKCE, the CSRF scheme and their upkeep stay ours, in a project whose reason for Spring Boot included Spring Security.
- Bad, because it reads as hand-rolled security to the engineers this codebase is meant to teach.
Spring Security's OAuth2 client classes only#
- Good, because the protocol's two steps would be Spring's, with no filter chain to tune.
- Bad, because it saves about 100 lines and leaves sessions, tokens and CSRF hand-written: most of the cost, little of the gain.