
# All properties

Every property `spring_boot_starter_security` reads, grouped by prefix. Each row gives the key, its type, its default and what it does. The starter's metadata (`lib/spring_gen/spring_metadata.json`) lists the same 15 keys, so editors with completion offer them. Most of security is configured in code (`SecurityFilterChain` beans); these properties cover what Spring Boot configures with properties, plus a few additions.

## Why

The default user for development, the identity provider of an API and the key that signs cookies change between environments. They are properties so that the same build runs everywhere with different values, from files or environment variables.

## Example

A production API behind a load balancer: tokens from Keycloak, a shared cookie key, three sessions per user for its pages.

```yaml
# lib/resources/application.yml
spring:
  security:
    cookie:
      secret: ${SECURITY_COOKIE_SECRET}      # 32+ characters, the same on every instance
    session:
      maximum-sessions: 3
      max-sessions-prevents-login: false
    password-checks:
      max-concurrent: 2
      max-queued: 32
    oauth2:
      resourceserver:
        jwt:
          issuer-uri: https://login.example.com/realms/shop
          audiences: orders-api
          authorities-claim-name: roles
          authority-prefix: ROLE_
          principal-claim-name: preferred_username
```

The same in `.properties`:

```properties
# lib/resources/application.properties
spring.security.cookie.secret=${SECURITY_COOKIE_SECRET}
spring.security.session.maximum-sessions=3
spring.security.session.max-sessions-prevents-login=false
spring.security.password-checks.max-concurrent=2
spring.security.password-checks.max-queued=32
spring.security.oauth2.resourceserver.jwt.issuer-uri=https://login.example.com/realms/shop
spring.security.oauth2.resourceserver.jwt.audiences=orders-api
spring.security.oauth2.resourceserver.jwt.authorities-claim-name=roles
spring.security.oauth2.resourceserver.jwt.authority-prefix=ROLE_
spring.security.oauth2.resourceserver.jwt.principal-claim-name=preferred_username
```

And for development:

```properties
# lib/resources/application-dev.properties
spring.security.user.name=admin
spring.security.user.password=change-me
spring.security.user.roles=ADMIN,USER
```

Text values are trimmed, and a blank value counts as unset.

## spring.security.user: the default user

The user the starter makes when the application has no users of its own (see [Form login and HTTP Basic](form-login.md)).

| Key | Type | Default | Meaning |
|---|---|---|---|
| `spring.security.user.name` | `String` | `user` | The name of the default user. |
| `spring.security.user.password` | `String` | none: a random one, logged at startup | The password of the default user; for development only. Stored as `{noop}` unless it starts with an `{id}`; with a `PasswordEncoder` bean, stored as given (so already encoded). |
| `spring.security.user.roles` | `List<String>` | none | The roles of the default user, without the `ROLE_` prefix. |

The default user is not made when the application has a `UserDetailsService`, `AuthenticationProvider`, `AuthenticationManager` or `JwtDecoder` bean, sets `issuer-uri`, `jwk-set-uri` or `secret-key`, or has OAuth2 client registrations, unless `name` or `password` is set.

## spring.security.filter

| Key | Type | Default | Meaning |
|---|---|---|---|
| `spring.security.filter.order` | `int` | `-100` | The place of the security filter among the web starter's filters; a lower order runs first. |

## spring.security.session: sessions per user

Not in Spring Boot, where `maximumSessions` is set in code only. They apply to the chains that keep logins in sessions (form login, `oauth2Login()`); a chain's own `sessionManagement((s) => s.maximumSessions(...))` wins. See [Sessions](sessions.md).

| Key | Type | Default | Meaning |
|---|---|---|---|
| `spring.security.session.maximum-sessions` | `int` | `10` | The most sessions per user; `-1` for no limit. `0` and values below `-1` fail the start. |
| `spring.security.session.max-sessions-prevents-login` | `bool` | `false` | Whether a login over the limit is refused instead of ending the user's least recently used session. |

## spring.security.cookie

| Key | Type | Default | Meaning |
|---|---|---|---|
| `spring.security.cookie.secret` | `String` | a random key of the process | The key that signs the security cookies (the page to come back to after a login, the OAuth 2.0 authorization request); at least 32 characters, the same on every instance behind a proxy. Set it to keep those cookies valid across restarts and servers. |

## spring.security.oauth2.resourceserver.jwt: bearer tokens

With `issuer-uri`, `jwk-set-uri` or `secret-key` set, the default chain needs a valid bearer token on every request, and there is no default user. See [JWT resource servers](jwt.md).

| Key | Type | Default | Meaning |
|---|---|---|---|
| `spring.security.oauth2.resourceserver.jwt.issuer-uri` | `String` | none | The issuer of the accepted bearer tokens; the keys come from its metadata. |
| `spring.security.oauth2.resourceserver.jwt.jwk-set-uri` | `String` | none | The address of the keys that sign the accepted bearer tokens. |
| `spring.security.oauth2.resourceserver.jwt.secret-key` | `String`, 32 bytes or more | none | The secret shared with a provider that signs with HS256, HS384 or HS512, as its UTF-8 bytes. Not with `jwk-set-uri`; an `issuer-uri` beside it is only compared with `iss`. Server only. |
| `spring.security.oauth2.resourceserver.jwt.jws-algorithms` | `List<String>`: `RS256`, `RS384`, `RS512`, `PS256`, `PS384`, `PS512`, `ES256`, `ES384`, `ES512`, `HS256`, `HS384`, `HS512` | `RS256`; `HS256` with `secret-key` | The signature algorithms accepted with `jwk-set-uri`, or the one HMAC algorithm (`HS256`, `HS384`, `HS512`) of `secret-key`; not used with `issuer-uri` alone. An unknown name fails the start. |
| `spring.security.oauth2.resourceserver.jwt.audiences` | `List<String>` | none | The audiences a bearer token must have one of; no audience check when empty. |
| `spring.security.oauth2.resourceserver.jwt.required-claims.<claim>` | `String` | none | The value a top-level claim of every bearer token must have (a number or a boolean as its text); otherwise a `401`. |
| `spring.security.oauth2.resourceserver.jwt.require-expiry` | `bool` | `false` | Whether a bearer token without an `exp` claim is refused (a `401`); otherwise such a token never expires, as in Spring Security. |
| `spring.security.oauth2.resourceserver.jwt.authority-prefix` | `String` | `SCOPE_` | Put before each authority read from the token. |
| `spring.security.oauth2.resourceserver.jwt.authorities-claim-name` | `String` | none: `scope`, else `scp` | The claim whose values are the user's authorities. Without a claim of exactly that name, a name with dots is a path into nested objects (`realm_access.roles`). |
| `spring.security.oauth2.resourceserver.jwt.authorities-claim-delimiter` | `String` | a space | The character that splits a text claim into authorities. |
| `spring.security.oauth2.resourceserver.jwt.principal-claim-name` | `String` | `sub` | The claim that names the user of a bearer token. |

## Read from other packages

| Key | Package | Default | Meaning |
|---|---|---|---|
| `spring.security.password-checks.max-concurrent` | [spring_security_core](../spring-security-core/properties.md) | half the processors | The most password hash checks at once. |
| `spring.security.password-checks.max-queued` | spring_security_core | eight times `max-concurrent` | The most checks waiting; above, `503`. |
| `spring.security.oauth2.client.registration.*`, `.provider.*` | [spring_boot_starter_oauth2_client](../spring-boot-starter-oauth2-client/index.md) | | The registrations of single sign-on. |
| `server.session.max-sessions` | [spring_boot_starter_web](../spring-boot-starter-web/properties.md) | `10000` | The most sessions in total. |
| `server.session.cookie.same-site` | spring_boot_starter_web | `lax` | Keep `lax` for single sign-on. |
| `server.forward-headers-strategy` | spring_boot_starter_web | | Needed behind a TLS proxy for HSTS and DPoP `htu`. |

## In Spring (Java)

`spring.security.user.*`, `spring.security.filter.order` and `spring.security.oauth2.resourceserver.jwt.*` keep Spring Boot's names and meanings. `spring.security.session.*`, `spring.security.cookie.secret`, `spring.security.password-checks.*`, and of the resource server `secret-key`, `required-claims`, `require-expiry` and a path in `authorities-claim-name` are additions. Not here yet: `spring.security.oauth2.resourceserver.jwt.public-key-location` and the opaque token keys.

## See also

- [The filter chain](filter-chain.md)
- [JWT resource servers](jwt.md)
- [Sessions](sessions.md)
