Differences from Spring
spring_boot_starter_security follows Spring Security 7.1 and Spring Boot 4.1: the same builder, filters, defaults and answers. The differences below are checked by sending the same requests to this starter and to a Spring Security application (a differential test), and each is on purpose.
Why
When you port a Spring application, you need to know where the behaviour is not the one you expect. Most differences come from three facts:
- The server is
dart:io, not a servlet container: no /error dispatch, paths normalized before the application.
- Dart has no overloading:
requestMatchersFor(HttpMethod, ...), optional customizers.
- Safer defaults where Spring leaves the choice to the application: CORS on, sessions limited, CSRF exemptions narrower.
Example
http
.authorizeHttpRequests((auth) => auth
.requestMatchersFor(HttpMethod.get, ['/api/books/**']).permitAll()
.anyRequest().authenticated())
.formLogin() // no Customizer.withDefaults()
.build(); // CORS is on without .cors()
http
.authorizeHttpRequests(auth -> auth
.requestMatchers(HttpMethod.GET, "/api/books/**").permitAll()
.anyRequest().authenticated())
.formLogin(Customizer.withDefaults())
.cors(Customizer.withDefaults())
.build();
Requests and errors
| Spring |
Here |
A 400 or 403 is re-dispatched to /error through the chain, where the request is anonymous: a client gets 401, and after a form login without a CSRF token the user lands on /error |
The 400 or 403 is the answer. |
| Errors in Spring Boot's error format |
ProblemDetail (application/problem+json), never the exception's message. |
| The firewall refuses the raw path |
dart:io normalizes paths (.., %2e%2e, \) first; the rules see the normalized path, as the router does. |
Two Authorization headers: the first is read |
Refused. |
A failed Basic login creates a session (through /error) |
No session. |
CORS
| Spring |
Here |
Needs .cors() |
On by default, with the router's rules. |
With a corsConfigurationSource bean that has no rule for a path, CorsFilter ends every pre-flight with a 200 without CORS headers, so the browser blocks what @CrossOrigin allows |
The pre-flight is answered from the handler's rules, as the actual request is. |
Sessions and CSRF
| Spring |
Here |
| The CSRF token, the saved request and the OAuth 2.0 authorization request live in the session |
Cookies (the last two signed): only a login makes a session. |
| No limit on sessions (Tomcat) |
server.session.max-sessions (10 000); at the limit a new login is refused with 503, as WebFlux's InMemoryWebSessionStore. |
| No limit per user by default |
10 sessions per user (spring.security.session.maximum-sessions). |
SessionCreationPolicy always, ifRequired, never, stateless |
ifRequired and stateless only. |
A token found by the BearerTokenResolver exempts from CSRF, including one in a form body |
Only a token in the header (Bearer, or DPoP with a proof). |
| The logout and login URLs are exempt with a token header (the logout filter logs the session out first) |
They keep their CSRF check (POST /logout with a Bearer token: 403 here). |
HttpSessionCsrfTokenRepository by default, header X-CSRF-TOKEN |
CookieCsrfTokenRepository by default, header X-XSRF-TOKEN. |
Tokens
| Spring |
Here |
Certificate-bound tokens (cnf.x5t#S256) checked against the client certificate |
Always refused: the web starter does not hand client certificates to the filters yet. |
DPoP needs oauth2ResourceServer(o -> o.dPoP(...)) |
On by default. |
DPoP htu compared as text |
After RFC 3986 normalization, without the query. |
DPoP htm ignores case |
Case-sensitive. |
DPoP requests need a CSRF token (only Bearer is exempt) |
Exempt like Bearer. |
DPoP jti recorded before the key check, kept until iat + skew |
Recorded after, kept 5 seconds longer. |
Single sign-on
| Spring |
Here |
A redirect back whose iss is not the issuer logs the user in |
Fails. |
| A redirect back to another registration's callback logs the user in |
Fails. |
An unknown registration id: 500, then the login through /error |
400. |
| A failed login keeps the exception in a new session |
No session. |
No response_mode setting; the callback reads any method |
response-mode=form_post per registration; a HEAD or PUT callback fails. |
TokenEndpointOidcIdTokenDecoder may be used |
ID token signatures are always checked. |
The default chain with OAuth2 clients has oauth2Login() only |
With a JwtDecoder too, it accepts bearer tokens as well. |
No apple provider, no JWT client secret |
Both are additions. |
Headers and other behaviour
headers((h) => h.defaultsDisabled()) makes later frameOptions, httpStrictTransportSecurity, contentTypeOptions, xssProtection and cacheControl calls do nothing (Spring adds them).
- Users given with
HttpSecurity.userDetailsService(...) never get their old password hashes upgraded at login; users of a UserDetailsService bean do.
- With only
issuer-uri, jws-algorithms is ignored.
fullyAuthenticated() is the same as authenticated() (no remember-me).
- Password checks are bounded (
spring.security.password-checks.*); above, 503.
- An authentication set outside every request is logged (a WARN, once per place in the code) and, with
management.health.securityContext.enabled=true, shown in the health as securityContext. Spring has neither. Nothing is refused, and the indicator is off by default. See The filter chain.
Not supported yet
- Logins:
rememberMe(), oneTimeTokenLogin(), passkeys (webAuthn()), x509(), pre-authentication by a proxy's header, switch user, multi-factor authentication.
- Sessions:
invalidSessionUrl, expiredUrl, a shared session store.
- OAuth 2.0:
oauth2Client() and @RegisteredOAuth2AuthorizedClient, back-channel logout (oidcLogout()), opaque tokens, several issuers in one chain, bearer tokens in a form body, certificate-bound tokens over mTLS, jwt.public-key-location.
- SAML 2.0: left out on purpose, it needs an XML signature stack.
- Other:
csrf.spa(), redirectToHttps(), hasIpAddress, web.ignoring(), PathRequest, Clear-Site-Data, observability, the oauth2Login() / oidcLogin() test post-processors and the authenticated() result matchers.
See also