Configuration Reference¶
| Property | Default | Description |
|---|---|---|
who.base-path |
/who |
The root of every who endpoint: <root>/sign-in, <root>/me/..., <root>/logout, <root>/email/..., <root>/passkey/..., <root>/oidc/... (including the provider callback), and who-admin's <root>/identities, <root>/roles and <root>/invitations. A path that starts with /, does not end with /, is not / alone, and holds no *{}?#; or whitespace; anything else fails startup. See Endpoints |
who.initialize-schema |
embedded |
When to run Who's bundled DDL scripts: always, embedded (H2/HSQLDB/Derby only), or never |
who.security.public-paths |
none | Paths of your app that who's default chain opens to signed-out requests, such as /signin and /assets/**. /error, <root>/sign-in, the sign-in methods' endpoints and Actuator's health endpoint are open already. A library or your app can add paths in code with a WhoPublicPathContributor bean (Collection<String> publicPaths(), patterns from the app's root, matched the same way; a null or blank one fails startup, naming the bean). Contributions only add: they cannot remove a path. All of them are in the WhoPublicPaths bean for a chain of your own. An application that defines its own WhoPublicPaths bean replaces who's, and with it every contribution |
who.email-link.enabled |
true |
Turns email-link sign-in off when false, with who-email-link still on the classpath |
who.passkey.enabled |
true |
Turns passkeys off when false, with who-passkey still on the classpath |
who.api-key.enabled |
true |
Turns API keys off when false, with who-apikey still on the classpath |
who.jwt.enabled |
true |
Turns JWT sign-in off when false, with who-jwt still on the classpath. When Spring Boot builds the decoder, spring.security.oauth2.resourceserver.jwt.audiences is required |
who.turnstile.enabled |
true |
Turns the Turnstile human check off when false, with who-turnstile still on the classpath |
who.oidc.enabled |
true |
Turns provider sign-in off when false, with who-oidc still on the classpath |
who.enrollment.enabled |
true |
Turns enrollment tokens off when false, with who-enrollment still on the classpath |
who.admin.enabled |
true |
Turns who's admin endpoints off when false, with who-admin still on the classpath |
who.enrollment.token-expiration |
24h |
How long a newly issued enrollment token is valid (ISO-8601 duration, e.g. PT12H) |
who.security.recent-sign-in |
10m |
How recently a browser session must have signed in to add or remove a way to sign in (a passkey, a provider account, an email address), to end another session, to make or rotate an API key, to change identities through the admin endpoints, and to call an action marked @RequiresRecentSignIn without a window of its own. Checked when the request starts and when it is confirmed; a started provider link lasts as long |
who.security.last-sign-in-cookie.enabled |
true |
Sets the who_last_sign_in cookie after a browser sign-in. See Sessions |
who.sessions.auto-purge |
true |
Each sign-in deletes one batch of ended or abandoned session records. Set to false to call WhoSessions.purgeEndedSessions() on a schedule of your own. See Sessions |
who.sessions.purge-batch-size |
100 |
The most session records one purge deletes. Positive, or startup fails |
who.sessions.last-seen-interval |
5m |
How often, at most, a session's last use is written. Positive, or startup fails. How long a session lasts without a request is spring.session.timeout with Spring Session, else server.servlet.session.timeout, read as Spring Boot reads them (a bare number is seconds, an empty value is unset). Since a busy session's last use can lag by up to this interval, who treats a record as abandoned only after the timeout plus this interval |
who.method-security.enabled |
true |
Enables method security so @RequiresPermission is enforced. Set to false to turn it off, for instance to configure @EnableMethodSecurity yourself. @RequiresRecentSignIn is enforced either way |
who.api-key.header-name |
X-API-Key |
HTTP header used to pass API keys |
who.api-key.prefix |
who_ |
Starts every new API key, so secret scanners can spot one. Letters, digits and _, 2 to 20 characters, ending in _, or startup fails. Changing it leaves existing keys working |
who.api-key.max-lifetime |
365d |
The longest lifetime a new API key may be given. Positive, or startup fails |
who.api-key.last-used-interval |
5m |
How often, at most, an API key's last use is written. Positive, or startup fails |
who.email.from |
none | The address every who email comes from. Required with who-email-smtp once a JavaMailSender exists; startup fails without it. See Email |
who.email.templates |
classpath:/templates/who/email/ |
Where your email templates are: a list of locations, searched in order before any library's and who's own. sign-in.txt there replaces who's sign-in text; sign-in.html adds HTML |
who.email.locale |
the JVM's | The locale emails are rendered in when no request's locale is known |
who.email.model.* |
none | Values every email template sees, as {{app.<name>}} |
who.email-link.link-base-url |
none | Page of your app that receives sign-in links. The token is appended as #token=.... Required with who-email-link: a missing or blank value fails startup. List the page in who.security.public-paths |
who.email-link.token-ttl |
5m |
How long a sign-in link stays valid |
who.email-link.resend-interval |
60s |
Minimum time between two links for the same address. Startup fails if it is longer than token-ttl |
who.email-link.address-confirmation-url |
link-base-url |
Page of your app that receives the link confirming an address being added or changed. The token is appended as #confirm-address=.... The person must be signed in there |
who.email-link.code-length |
6 |
Number of characters in the typed sign-in code. At least 6 |
who.email-link.code-max-attempts |
5 |
Wrong guesses a sign-in code survives before it is burnt. The link still works. At least 1 |
who.email-link.code-secret |
none | Secret that keys the code hash. Required with who-email-link, at least 32 characters, the same on every instance. Never stored in the database |
who.turnstile.secret-key |
none | The Turnstile widget's secret key. Required with who-turnstile: a missing, blank or unresolved value fails startup. See Human check |
who.turnstile.verify-url |
https://challenges.cloudflare.com/turnstile/v0/siteverify |
Where tokens are verified. Point it at a stand-in, such as WireMock, in tests. An absolute http or https URL; anything else fails startup |
who.turnstile.hostnames |
none | Hostnames a Turnstile token may be made on. Empty accepts any |
who.turnstile.timeout |
3s |
How long to wait for Cloudflare, to connect and, separately, to answer; a call can take up to twice this |
who.turnstile.fail-open |
false |
Lets requests through when Cloudflare cannot be reached or answers an error. A token Cloudflare refuses always fails |
who.passkey.rp-id |
none | The application's own host, such as app.example.com. Required with who-passkey: startup fails without it. Never use a registrable domain that other apps share |
who.passkey.rp-name |
who |
Name of the relying party, shown by authenticators. Must not be blank |
who.passkey.allowed-origins |
https://<rp-id> |
Origins a registration or sign-in response may come from: each a scheme (http or https), a host and an optional port, with no path, such as http://localhost:8080. Startup fails on anything else |
who.oidc.success-url |
/ |
Where a provider sign-in lands. A path on this site |
who.oidc.failure-url |
/ |
Where a pending sign-up lands, with pending=sign-up, and every failed provider sign-in, with error=already-linked, signed-in or signin-failed. A path on this site; list it in who.security.public-paths |
who.oidc.link-url |
success-url |
Where a link the signed-in person asked for lands: pending=link to confirm it, error=already-linked, or nothing for an account they already had. A path on this site, such as the account settings page |
who.oidc.sign-up-window |
10m |
How long a pending sign-up waits for the person to confirm it |
who.oidc.providers.<id>.enabled |
true |
Leaves one client registration out of sign-in when false |
who.oidc.providers.<id>.issuer |
none | The issuer, for an OpenID Connect provider configured by endpoints, or an OAuth 2 provider |
who.oidc.providers.<id>.subject-attribute |
none | The user-info attribute holding the account's immutable id, for an OAuth 2 provider other than github.com |
who.oidc.providers.<id>.trust-email |
true for Google and github.com, else false |
Whether a verified address from this provider reaches the sign-up policy |
See Email Links, Passkeys and Social Login for how these fit together.
Endpoints¶
Every who endpoint lives under who.base-path. With the default /who:
| Endpoint | Module | What it does |
|---|---|---|
GET /who/sign-in |
who-spring-security | Which sign-in methods are on, and the providers to draw buttons for. Public |
POST /who/logout |
who-spring-security | Sign out |
POST /who/email/send |
who-email-link | Email a sign-in link and code |
POST /who/email/sign-in |
who-email-link | Sign in with the link's token, or the address and code |
POST /who/passkey/sign-in/options, POST /who/passkey/sign-in |
who-passkey | Sign in with a passkey |
GET /who/oidc/authorize/{registrationId} |
who-oidc | Start a provider sign-in |
GET /who/oidc/callback/{registrationId} |
who-oidc | The provider's redirect URI |
GET /who/oidc/pending, POST /who/oidc/pending/sign-up, POST /who/oidc/pending/link |
who-oidc | Confirm a pending sign-up or link |
GET /who/me |
who-spring-security | The signed-in identity, its permissions, how it signed in and its credential counts |
GET /who/me/sessions, DELETE /who/me/sessions/{id}, DELETE /who/me/sessions?others=true |
who-spring-security | See and end your sessions |
GET /who/me/passkeys, DELETE /who/me/passkeys/{credentialId} |
who-passkey | List and remove your passkeys |
POST /who/me/passkeys/options, POST /who/me/passkeys |
who-passkey | Register a passkey |
GET /who/me/email-addresses, DELETE /who/me/email-addresses/{id} |
who-email-link | List and remove your email addresses |
POST /who/me/email-addresses, POST /who/me/email-addresses/confirmations |
who-email-link | Add or change an email address |
GET /who/me/accounts, DELETE /who/me/accounts/{id} |
who-oidc | List and unlink your provider accounts |
POST /who/me/accounts/{registrationId} |
who-oidc | Start linking a provider account |
GET /who/me/api-keys, POST /who/me/api-keys, POST /who/me/api-keys/{id}/rotations, DELETE /who/me/api-keys/{id}, GET /who/me/api-keys/current |
who-apikey | Manage your API keys |
GET /who/identities, GET /who/identities/{id}, PATCH /who/identities/{id} |
who-admin | List, read, deactivate and reactivate identities |
PUT /who/identities/{id}/roles/{role}, DELETE /who/identities/{id}/roles/{role} |
who-admin | Assign and remove roles |
GET /who/roles |
who-admin | The roles that exist |
POST /who/invitations |
who-admin, with who-email-link | Invite someone by email address |
Everything under /who/me acts on the caller's own data only; see Your Account for
who may call each one. The admin endpoints need who's own permissions; see Admin.
who's controllers and your Spring MVC setup¶
/who/me and everything under it, and the admin endpoints, are Spring MVC controllers. Your
application's MVC setup reaches them as it reaches your own controllers:
- A path prefix or servlet path fails startup. who's sign-in filters, logout, public paths and
error handling sit at
who.base-path, so aconfigurePathMatchprefix that matches who's controllers, aspring.mvc.servlet.pathother than/, or aWhoPathsbean whose root is notwho.base-pathis refused at startup, naming the endpoints that moved. Exclude who's controllers from a prefix (match on your own package) or setwho.base-pathinstead. - A
ResponseBodyAdvicechanges who's answers. One that wraps every body in an envelope wraps who's too, and who's client cannot read them. Limit it to your own packages (@ControllerAdvice(basePackages = ...)). who's errors are not affected: who writes them itself. - who's JSON shape relies on Jackson 3. Its answer types pin their names, nulls and instants
with Jackson annotations, so
spring.jacksonsettings do not change them. A Gson, JSON-B or Jackson 2 converter preferred over Spring's Jackson 3 one ignores those annotations. - Your interceptors and filters run for who's endpoints like any request.
Your own endpoints may live under the same root; who's rules apply only to its own paths, so yours still need whatever sign-in your chain asks for.