
# 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

```dart
http
    .authorizeHttpRequests((auth) => auth
        .requestMatchersFor(HttpMethod.get, ['/api/books/**']).permitAll()
        .anyRequest().authenticated())
    .formLogin()      // no Customizer.withDefaults()
    .build();         // CORS is on without .cors()
```

```java
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](filter-chain.md).

## 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

- [Overview](index.md)
- [spring_security_core differences](../spring-security-core/differences.md)
- [All properties](properties.md)
