Upgrading¶
Upgrading to 0.25.0¶
Contributed beans end in Contributor¶
A bean that adds to who's configuration is named *Contributor. Two records are renamed; their
components are unchanged:
WhoEmailTemplatesis nowWhoEmailTemplatesContributor.WhoEmailMessagesis nowWhoEmailMessagesContributor.
Update any class name written as a string too, such as
@ConditionalOnClass(name = "org.jwcarman.who.email.WhoEmailMessages"): the compiler does not catch
it, and a condition that stops matching silently drops your templates or subjects.
@Bean
WhoEmailTemplatesContributor acmeEmailTemplates() {
return new WhoEmailTemplatesContributor("classpath:/com/acme/email/", "com/acme/email-messages");
}
Upgrading to 0.24.0¶
Email template locations are a list¶
who.email.templates is a list of locations, searched in order. A single value still binds, so an
existing setting keeps working; WhoProperties.Email#getTemplates() returns a List<String>.
MustacheWhoEmailRenderer's constructor takes a List<String> of template locations instead of
one location. Only a renderer you build by hand changes:
new MustacheWhoEmailRenderer(resources, List.of("classpath:/templates/who/email/"), messages, app, contributors);
Subjects are templates¶
who.email.<template>.subject is rendered as Mustache. A subject with no {{ renders as before. A
rendered subject is put on one line.
Upgrading to 0.23.0¶
0.23.0 sends every who email through one seam, renders them from templates an application can
replace, and splits sending out of the feature modules. An application that sends who's emails over
SMTP adds two dependencies and moves its from and subject settings; one with its own
WhoEmailSender rewrites it as pure delivery.
Add who-email and a sender¶
who-email-link no longer sends mail itself. Add the renderer and the SMTP sender beside it:
<dependency>
<groupId>org.jwcarman.who</groupId>
<artifactId>who-email</artifactId>
</dependency>
<dependency>
<groupId>org.jwcarman.who</groupId>
<artifactId>who-email-smtp</artifactId>
</dependency>
who-email-smtp brings spring-boot-starter-mail, so you can drop that dependency. Without both,
email-link sign-in fails startup, and the message says which is missing.
One sending address¶
who.email.from replaces who.email-link.from and who.passkey.from:
who:
email:
from: no-reply@example.com
The old properties are gone, with no aliases. With who-email-smtp and a mail host, a missing
who.email.from fails startup.
Subjects are messages¶
The four subject properties are now message keys, read from your MessageSource (such as
src/main/resources/messages.properties):
| 0.22 property | 0.23 message key |
|---|---|
who.email-link.subject |
who.email.sign-in.subject |
who.email-link.invitation-subject |
who.email.invitation.subject |
who.email-link.address-confirmation-subject |
who.email.address-confirmation.subject |
who.email-link.address-changed-subject |
who.email.address-changed.subject |
The passkey-added email's subject is who.email.passkey-added.subject. The defaults are unchanged.
A custom WhoEmailSender delivers only¶
WhoEmailSender moved to org.jwcarman.who.core.email and takes a rendered OutgoingEmail
(to, subject, text, an optional html, and the source it was rendered from) instead of a
WhoEmail. A sender that switched over who's emails to word them itself becomes a few lines of
delivery, and its wording moves into templates:
@Bean
WhoEmailSender whoEmailSender(MyMailer mailer) {
return email -> mailer.send(email.to(), email.subject(), email.text(), email.html());
}
With your own sender, leave out who-email-smtp, but keep who-email to render.
who answers its own errors¶
Under who's base path, who now answers every error itself, as RFC 9457 Problem Details
(application/problem+json) with a code member, whatever your @RestControllerAdvice says.
A handler of yours for who's exceptions no longer runs for who's endpoints; it still runs for
your own endpoints, which who's exceptions reach as before. A client that read your advice's body
for who's endpoints reads who's now; see Errors.
invalid-admin-request, invalid-api-key-request and invalid-invitation are now
invalid-request.
who's endpoints are controllers¶
/who/me, the session, passkey, email-address, linked-account, API-key and admin endpoints are
Spring MVC controllers now, not servlet filters. That changes three things:
- Your authorization rules apply to them. With who's default chain and the documented
WhoPublicPathsplusanyRequest().authenticated(), nothing changes. A rule of yours that refuses/who/**, or demands a role there, now refuses who's endpoints too. - The
*Endpointsbeans are gone:EmailAddressEndpoints,LinkedAccountsEndpoints,ApiKeyEndpoints,WhoAdminEndpointsandWhoInvitationEndpoints. A chain of your own that applied one drops that call; the controllers are on with their module. To replace an endpoint, define a bean of the controller's type. - A controller of yours at one of who's paths fails startup as an ambiguous mapping, where before who's filter answered first and yours never ran.
- Your Spring MVC setup reaches them. A controller path prefix that matches who's
controllers, or a
spring.mvc.servlet.path, now fails startup; aResponseBodyAdvicethat wraps every body wraps who's answers too; your interceptors run for them. See who's controllers and your Spring MVC setup.
WhoJson is gone too: who's answer types carry their JSON shape themselves, so your
spring.jackson settings still do not change them.
Other changes¶
WhoEmailmoved toorg.jwcarman.who.core.email, is no longer sealed, and hastemplate(). The email records stay inorg.jwcarman.who.emaillink.EmailLinkMessage,InvitationMessageandEmailAddressConfirmationMessagegain avalidForcomponent, afterexpiresAt, andexpiresIn(). Code that constructs them passes the duration.MailWhoEmailSenderis gone;SmtpWhoEmailSenderinwho-email-smtpreplaces it.MailPasskeyAddedNotifieris gone. The passkey-added email now goes through the same setup as sign-in links, and is sent whenever email-link sign-in is on.WhoEmails.sendrefuses inside a transaction. who's own callers already send after commit;InvitationService.invitealready refused one.
The emails' wording is unchanged.
Upgrading to 0.21.0¶
0.21.0 makes who's HTTP surface REST-shaped. A person's own sessions, passkeys, email addresses,
linked accounts and API keys live under /who/me; who-admin adds
endpoints for identities, roles and invitations; and removing a sign-in credential can no longer
leave an identity locked out. Most applications change their front end's paths and client calls,
and check that they have one transaction manager.
Moved endpoints¶
The old paths reach no who endpoint, and who keeps no redirects. Change your front end's calls,
and any requestMatchers, proxy rules or links that name them:
| 0.20 | 0.21 |
|---|---|
GET /who/sessions |
GET /who/me/sessions |
DELETE /who/sessions/{id} |
DELETE /who/me/sessions/{id} |
DELETE /who/sessions?others=true |
DELETE /who/me/sessions?others=true |
POST /who/passkey/register/options |
POST /who/me/passkeys/options |
POST /who/passkey/register |
POST /who/me/passkeys |
DELETE /who/passkey/register/{id} |
DELETE /who/me/passkeys/{credentialId} |
POST /who/email/addresses |
POST /who/me/email-addresses |
POST /who/email/addresses/confirm |
POST /who/me/email-addresses/confirmations |
POST /who/oidc/link/{registrationId} |
POST /who/me/accounts/{registrationId} |
POST /who/oidc/sign-up |
POST /who/oidc/pending/sign-up |
POST /who/oidc/link |
POST /who/oidc/pending/link |
Request and answer bodies are unchanged, except:
- Removing a passkey is who's own endpoint now. It needs a browser session signed in within
who.security.recent-sign-in, answers404for a passkey that is someone else's (Spring's answered403), and409when it is the identity's last way to sign in. A page that removed passkeys right after any sign-in may now need to ask the person to sign in again. - A session cookie with an API key or a bearer token beside it is not a browser session on
any of these endpoints: it gets
403. The email-address POSTs and starting a link answered a signed-in caller that was not a browser401; they answer403now.
The TypeScript client¶
Calls for the person's own account moved under who.me:
| 0.20 | 0.21 |
|---|---|
who.me() |
who.me.get() |
who.sessions.list(), end(id), endOthers() |
who.me.sessions.list(), end(id), endOthers() |
who.passkeys.register(label) |
who.me.passkeys.register(label) |
who.passkeys.remove(credentialId) |
who.me.passkeys.remove(credentialId) |
who.email.addAddress(address, replaces?) |
who.me.emailAddresses.add(address, replaces?) |
who.email.confirmAddress(proof) |
who.me.emailAddresses.confirm(proof) |
who.email.confirmAddressFromLocation() |
who.me.emailAddresses.confirmFromLocation() |
who.oidc.startLink(registrationId) |
who.me.accounts.link(registrationId) |
me.passkeys.removefails with'signed-out','reauthentication-required','sign-in-required','not-found'or'last-credential';'refused'is gone. Aswitchover its reasons needs the new cases.me.emailAddresses.confirmanswers{ credentialId }instead of nothing.Mehas three more fields,signInMethod,recentSignInUntilandcredentials.
The compiler finds every call that moved. See TypeScript Client.
One transaction manager¶
Removing a passkey, an email address or a linked account counts the identity's credentials and
removes one in a transaction that locks the identity's row. who-passkey, who-email-link and
who-oidc therefore need the LastCredentialGuard bean, which who builds when the application
has who-jdbc and exactly one PlatformTransactionManager. Spring Boot makes that one for a
single DataSource, so most applications need nothing.
An application with two or more transaction managers fails startup with
NoSuchBeanDefinitionException for LastCredentialGuard. Mark the one for who's DataSource
@Primary, or define a LastCredentialGuard bean yourself. who-admin needs the same single
manager for its LastAdminGuard and fails startup without it, and InvitationService, behind
POST /who/invitations, needs it too. The manager must manage the DataSource of who's
JdbcClient; see Transactions and locks.
Code that builds who's pieces itself¶
Only an application that implements who's interfaces or constructs its classes by hand needs to change:
- Repositories.
IdentityRepositoryhas three new methods,lockById,findPageandcount;EmailCredentialRepositoryandFederatedCredentialRepositoryeach havefindAllByIdentityId. who's JDBC repositories have them all. - Constructors.
PasskeyLoginMethodtakes aPasskeyServiceand aLastCredentialGuard;OidcLoginMethodaFederatedCredentialServiceand aLastCredentialGuard;EmailAddressEndpointsanEmailCredentialServiceand aLastCredentialGuard. WhoMeControllertakes(WhoSessionSecurityContextRepository, RecentSignInAuthorizationManager, ObjectProvider<LastCredentialGuard>), andmetakes(HttpServletRequest, HttpServletResponse, Authentication)and writes the answer itself, with who's own JSON mapper. An application that@Imports it needs aRecentSignInAuthorizationManagerbean.WhoMeResponsehas three more components.SessionEndpointsno longer takes aJsonMapper.WhoSessionSecurityContextRepositoryhas one constructor, which also takes aRequestMatcherfor the requests that present a stateless credential (an API key or a bearer token). An application that builds it by hand with no stateless sign-in method passes_ -> false; with one, a matcher for the requests that carry its credential. The four-argument constructor is gone. ItsisLoaded,presentsStatelessCredentialandbrowserSessionmethods, added in this release's development, are not public: usecaller.WhoPublicPathshas one constructor,(WhoPaths, methods, configured, contributed). PassList.of()forcontributed. Every pattern must be non-blank. To add public paths from a library, declare aWhoPublicPathContributorbean instead of replacingWhoPublicPaths: replacing the bean drops every contribution.- A
StatelessLoginMethodof your own. ItscarriesCredential()should not match a request thatStatelessLoginMethod.alreadySignedIn(), so a session cookie never rides along without its CSRF token. If it configures Spring's resource server, wrap the bearer-token converter so it answersnullon such a request, asJwtLoginMethoddoes: Spring's resource server exempts from CSRF any request its converter reads. - API-key filter order.
ApiKeyAuthenticationFilteris now added beforeExceptionTranslationFilter, not beforeAuthorizationFilter.
who's JSON ignores your Jackson settings¶
who writes GET /who/me, GET /who/sign-in, everything under /who/me/ and the admin and
invitation answers with its own Jackson mapper. spring.jackson.* settings (a naming strategy,
dates as numbers, leaving nulls out) no longer reach them: names are camelCase, instants are
ISO-8601 strings and a null is written. A client that read /who/me in the application's own
naming reads who's names now.
Bearer tokens beside a session¶
On a chain that signs browsers in, a request with a session cookie and a bearer token is signed in by the session; the token is ignored, as an API key already was, and the request needs its CSRF token. Before, the token signed it in and skipped CSRF. A client that sends both should send only one.
Endpoints your app may now drop¶
who now serves what many applications wrote themselves: a passkey list, linked-account
unlinking, API-key management, a providers list for the sign-in page (GET /who/sign-in), member
lists and invitations. Endpoints of your own over PasskeyService.revoke,
FederatedCredentialService.unlink or ApiKeyService.revoke should check that the id is the
caller's; who's do, and apply the last-credential rule too.
InvitationService.invite must be called outside any transaction: store your own data for the
invited person with the callback of invite(email, roleNames, callback), which runs inside the
invitation's transaction. An IdentityInvited
listener is for cross-cutting reactions such as auditing.
Rename: EmailLinkSender is WhoEmailSender¶
A custom sender implements WhoEmailSender (it was EmailLinkSender), and MailEmailLinkSender is MailWhoEmailSender; there is no alias, so rename the type and the bean method.
Invitations now arrive as an InvitationMessage, a fourth kind of WhoEmail, so a custom sender must handle it. A sender written with instanceof EmailLinkMessage checks, or with a switch that has a default -> branch, still compiles but silently drops every invitation, and who still reports the link as sent. Use an exhaustive switch without default, so the compiler flags the new kind. MailWhoEmailSender's constructor gained the invitationSubject parameter, before the clock (property who.email-link.invitation-subject).
Upgrading to 0.20.0¶
0.20.0 adds a human check on who's email endpoints, with
Cloudflare Turnstile in the new who-turnstile module, and a
startup log of the sign-in methods each chain accepts. Two
changes can break an application.
The email-address endpoints are not a sign-in method¶
EmailAddressEndpoints, which serves /who/email/addresses, now implements
BrowserEndpoints instead of PasswordlessLoginMethod. WhoWebSecurity.passwordless() applies
every BrowserEndpoints bean after its sign-in methods, so a chain built with it, or who's
default chain, changes nothing.
Code that applies PasswordlessLoginMethod beans to a chain itself no longer gets the
email-address endpoints that way. Apply BrowserEndpoints beans as well:
@Bean
SecurityFilterChain web(HttpSecurity http, List<PasswordlessLoginMethod> methods,
List<BrowserEndpoints> endpoints) throws Exception {
// ...apply the methods, then:
endpoints.forEach(e -> e.configure(http));
return http.build();
}
The TypeScript client's email.send answers a result¶
email.send returns a WhoResult instead of void, so a page can see a refused
human check. A page that only awaits it still compiles and works
as before until the application adds a human check; from then on a refusal comes back as
'human-check-failed' instead of throwing, so check ok:
const result = await who.email.send(address, { humanCheck: token });
if (!result.ok && result.reason === 'human-check-failed') {
return showWidgetAgain();
}
Other failures still throw a WhoError. To have the refusal throw too, use
unwrap(await who.email.send(address)).
Upgrading to 0.19.0¶
0.19.0 adds @RequiresRecentSignIn, lets people
see and end their sessions, and moves every who endpoint
under one root.
Every endpoint under one root¶
Update the redirect URI registered at each provider to
https://<your-host>/who/oidc/callback/<registration-id>.
Every who endpoint now lives under who.base-path, /who unless you set it. Change your
front end's calls, and any requestMatchers or proxy rules that name them:
| Before | From 0.19.0 |
|---|---|
POST /ott/generate |
POST /who/email/send |
POST /login/ott |
POST /who/email/sign-in |
POST /logout |
POST /who/logout |
POST /webauthn/register/options |
POST /who/passkey/register/options |
POST /webauthn/register |
POST /who/passkey/register |
DELETE /webauthn/register/{id} |
DELETE /who/passkey/register/{id} |
POST /webauthn/authenticate/options |
POST /who/passkey/sign-in/options |
POST /login/webauthn |
POST /who/passkey/sign-in |
GET /oauth2/authorization/{id} |
GET /who/oidc/authorize/{id} |
GET /login/oauth2/code/{id} |
GET /who/oidc/callback/{id} |
/who/me, /who/sessions, /who/email/addresses and /who/oidc/... keep their paths under the
default root, and move with it if you set another.
- The old paths are gone. who answers none of them, and keeps no redirects.
- A registration's
redirect-uri. Leave it unset and who sets its callback. An explicit one must end with/who/oidc/callback/{registrationId}(under your root); any other fails startup, namingspring.security.oauth2.client.registration.<id>.redirect-uri. - Code that builds who's pieces itself.
PendingSignUpFilter'sPENDING_URL,SIGN_UP_URLandLINK_URLare gone.PendingSignUpFilter,OidcLoginMethod,EmailLinkLoginMethod,EmailAddressEndpoints,PasskeyLoginMethodandPasskeyRegistrationGuardFiltertake aWhoPathsfirst (WhoPaths.defaults()for/who). - Passkeys no longer go through Spring's
webAuthn(). who adds Spring's passkey filters to its chain itself, at its own paths. It no longer needs aUserDetailsService, and no longer shares its passkey repositories with the chain. An application's ownwebAuthn()chain is untouched and keeps Spring's paths.
Signed-in sessions¶
- A new table,
who_session. Withwho.initialize-schema=alwayswho creates it. With Liquibase,who-changelog-all.xml(orwho-jdbc-changelog.xml) has a new changeSet,who-session-1. Otherwise create it fromwho-jdbc-schema.sql. - Everyone signs in once more. A browser session saved before 0.19 has no record behind it, so its next request is signed out. Sessions that sign in from 0.19 on keep working.
WhoSessiongains a fifth component,sessionId, the id of its record. The four-argument constructor makes a session with none, which is signed out on its next request.WhoSessionSecurityContextRepositorytakesWhoSessions. Its constructor is now(WhoService, WhoSessions, Clock, WhoEventPublisher); the two- and three-argument ones are gone. Only an application that builds the repository itself needs to change.- A new sign-in must say how it signed in. Saving a
WhoAuthenticationTokenbuilt without aSignInMethodas a new sign-in throwsIllegalStateException. who's own sign-ins all set it. - Test helpers take
WhoSessions.WhoTestSessions.signedIn(identityId, credentialId)is nowsignedIn(whoSessions, identityId, credentialId), with an overload that also takes the sign-in time; autowireWhoSessionsin the test.WhoMockMvcBrowser.signedInAsis unchanged, but needs aMockMvcbuilt from the application context.who-testaddsInMemorySessionRecordRepositoryfor tests without a database. - New endpoints on every browser chain:
GET /who/sessions,DELETE /who/sessions/{id}andDELETE /who/sessions?others=true. They need a signed-in browser session. - Use
WhoSessions.endAllto sign someone out everywhere. The Spring Session recipe from earlier versions still works, but misses sessions in the container's own store.
Recent sign-in¶
Nothing you have needs to change, but a few things look different:
- Every signed-in caller has one more authority. Beside the permissions,
getAuthorities()holds a Spring SecurityFactorGrantedAuthorityfor how the person signed in (FACTOR_OTT,FACTOR_WEBAUTHN,FACTOR_AUTHORIZATION_CODE, orFACTOR_BEARERfor a JWT withauth_time). Code that lists authorities as permissions should listWhoPrincipal.permissions()instead. - Sessions remember how they signed in.
WhoSessiongains a fourth component,signInMethod. A session saved by 0.18 still loads, without it: it signs in as before, but an action marked@RequiresRecentSignInasks it to sign in again.WhoTestSessions.signedInandWhoMockMvcBrowser.signedInAsrecord an email-code sign-in. - A sign-in exactly
who.security.recent-sign-inold is too old, as Spring Security's factor check has it; it was just recent enough before.
Upgrading to 0.18.0¶
0.18.0 makes who work like any Spring Boot starter: add a module's jar and it is on, and an application with no security configuration of its own gets a working chain. It adds social login, and renames the JWT credential, and its table, so JWT and provider sign-in can share it.
-
The starter no longer brings every module.
who-spring-boot-starternow brings the base only: identities, sessions, permissions (who-core,who-spring-security,who-jdbc,who-rbac) and the autoconfiguration. Add each sign-in method you use, with no version under the BOM:You use Add Email links and codes who-email-linkPasskeys who-passkeyAPI keys who-apikeyJWTs who-jwtGoogle, GitHub or OpenID Connect sign-in who-oidcEnrollment tokens who-enrollment -
A module on the classpath is on. Setting
who.email-link.link-base-urlorwho.passkey.rp-idno longer turns a method on; the jar does. A module whose required settings are missing now fails startup, and the report names the property to set and the switch that turns the module off:Module Fails startup without who-email-linkwho.email-link.link-base-url,who.email-link.code-secret, and anEmailLinkSenderbean, orspring-boot-starter-mailwithspring.mail.hostandwho.email-link.fromwho-passkeywho.passkey.rp-idwho-jwt(when who mounts it)spring.security.oauth2.resourceserver.jwt.issuer-uri,jwk-set-uri,public-key-location, or aJwtDecoderbean; and, unless the decoder is your own bean,spring.security.oauth2.resourceserver.jwt.audienceswho-oidca spring.security.oauth2.client.registrationwith theauthorization_codegrantTo keep a module's jar but turn it off, set
who.email-link.enabled,who.passkey.enabled,who.api-key.enabled,who.jwt.enabled,who.oidc.enabledorwho.enrollment.enabledtofalse. -
An application with no
SecurityFilterChaingets who's chain instead of Spring Boot's. Boot's default chains (form login and HTTP Basic, and the resource server's, Actuator's, andoauth2Login's) are replaced by who's: every sign-in method on the classpath,401for a signed-out request, and no redirect to/login. Only/error, the sign-in endpoints, Actuator's health endpoint and the paths inwho.security.public-pathsare open to signed-out requests. List your own sign-in page and its assets there, including the pagelink-base-urlpoints at:who: security: public-paths: - /signin - /assets/** -
An application with its own
SecurityFilterChainis unchanged. who's chain backs off for any chain of yours, andWhoWebSecurity.passwordless()andWhoApiKeySecurity.apiKey()work as before. To mount every method in your own chain in one call, useWhoSecurity.all()withWhoPublicPaths; see Getting Started. - who no longer publishes an
AuthenticationConverterbean. The email-linkjsonOneTimeTokenAuthenticationConverterbean is gone: Spring's resource server took it as its own, so an application with email links and its ownoauth2ResourceServerrefused every bearer token. If you replaced that bean, replace theEmailLinkLoginMethodbean instead. who-jwtrequires the audience. When Spring Boot builds the decoder, startup fails untilspring.security.oauth2.resourceserver.jwt.audiencesis set: without it, a token the same issuer minted for any other application, such as a provider's ID token, would sign in. Set it to the audience your API's tokens carry. AJwtDecoderbean of your own owns that check. See JWT.JwtCredentialis nowFederatedCredential, in the newwho-federatedmodule.JwtCredential,JwtCredentialRepository,JdbcJwtCredentialRepositoryandJwtCredentialServicebecomeFederatedCredential,FederatedCredentialRepository,JdbcFederatedCredentialRepositoryandFederatedCredentialService, in packageorg.jwcarman.who.federated.who-jwtbringswho-federated, so no dependency changes. The methods are the same.-
The table
who_jwt_credentialis renamedwho_federated_credential. Same columns, same rows. The bundled schema script and the Liquibase changelog rename it for you when the old table exists. With Flyway, add a migration:ALTER TABLE who_jwt_credential RENAME TO who_federated_credential;The rename is not compatible with a rolling upgrade: stop every instance on 0.17 before the first 0.18 instance starts.
-
CredentialKind.JWTis nowFEDERATED.CredentialAddedandCredentialRevokedfor an(issuer, subject)credential carryFEDERATED, and thekindtag onwho.credentials.addedandwho.credentials.revokedisfederated, notjwt. Update listeners and dashboards.SignInMethod.JWTis unchanged. - New enum values.
SignInMethod.OIDC, andSignInFailureReason.SIGN_UP_REFUSED,PROVIDER_ERRORandLINK_REFUSED. An exhaustiveswitchover either needs the new cases. - who sets the
who_last_sign_incookie after every browser sign-in, naming the method used. Turn it off withwho.security.last-sign-in-cookie.enabled=false. See Sessions. - One recent sign-in setting.
who.passkey.registration-windowandwho.oidc.link-windoware gone.who.security.recent-sign-in(default10m) is how recently the browser session must have signed in to register a passkey, link a provider account, or add or change an email address. Starting a provider link (POST /who/oidc/link/{registrationId}) now checks it too. EmailLinkSender.sendtakes aWhoEmail. It is sealed: the sign-inEmailLinkMessage, and the newEmailAddressConfirmationMessageandEmailAddressChangedMessage. A custom sender switches over the three; see Email Links.- A new table,
who_email_address_request, for adding or changing an address. The bundled schema and the Liquibase changelog create it; Flyway users copy it from Database Setup. - API keys need a lifetime and scopes.
ApiKeyService.create(identity, name)is nowcreate(identity, name, lifetime, scopes)and answers aNewApiKey; the raw key is itskey(). The lifetime is required and at mostwho.api-key.max-lifetime(default365d), and each scope must be a permission the owner holds. A key signs in with its scopes intersected with its owner's permissions, so a key no longer carries everything its owner can do. See API Keys.- New:
findByIdentitylists an identity's keys,rotatereplaces one with an overlap, andSignInFailureReason.EXPIRED_KEY. - New keys look like
who_plus 36 base62 characters, the last 6 a checksum. A header that is not shaped like a key is refused without a database lookup. - New settings:
who.api-key.prefix,max-lifetimeandlast-used-interval. ApiKeyServiceandApiKeyAuthenticationProvidertake new constructor arguments: aPermissionsResolver, anApiKeyFormatand the maximum lifetime for the service; anApiKeyFormatand the last-used interval for the provider. Apps that use the autoconfigured beans change nothing.ApiKeyCredentialRepositoryhas two new methods,touchandexpireBy, for a custom implementation to add.
- New:
- The API-key tables change, and existing keys are deleted.
who_api_key_credentialgainscreated_at,expires_atandlast_used_at, and a new table,who_api_key_scope, holds each key's scopes. Keys made before have no lifetime or scopes, so the Liquibase changelog deletes them before adding the columns; issue new ones. With the bundled schema, dropwho_api_key_credentialand let who create both tables again. Flyway users delete the rows and copy the new columns and table from Database Setup. - The "passkey added" startup warning moved logger. It is now logged by
org.jwcarman.who.autoconfigure.WhoPasskeyAutoConfiguration, notWhoAutoConfiguration.
Upgrading to 0.17.0¶
0.17.0 adds security events. There are no schema or property changes. One behavior change breaks clients, and a few things affect applications that build who's services themselves.
- API keys: a bad key is a
401, even on public endpoints. A request whose key header is unknown, revoked, or belongs to an inactive identity now gets the uniform401at once, even on an endpoint that permits anonymous access. Before, it continued as anonymous. A client that sends a stale key to a public endpoint must drop the header or use a valid key. No header, or a blank header, behaves as before. See API Keys.- A database fault during the key check now surfaces as the original
RuntimeExceptionrather than aServletException. The answer is still a500. - When a valid key signs in, an anonymous HTTP session's id is rotated.
- Each request with an unknown, revoked or inactive key publishes
SignInFailed; a valid key publishes no who event (Spring'sAuthenticationSuccessEventstill fires). - A filter you pass to
WhoApiKeySecurity.apiKey(filter)has its authentication manager and failure handler set by who.
- A database fault during the key check now surfaces as the original
- Link JWT credentials with
JwtCredentialService.linkandunlinkpublishCredentialAddedandCredentialRevoked; saving throughJwtCredentialRepositorydirectly does not.unlinktakes a JWT credential id. See JWT. - Application tests that mock
WhoServicemust stubresolveDetailed. who's sign-in and session code now callsWhoService.resolveDetailedinstead ofresolve, so a mock that stubs onlyresolveanswersnullfromresolveDetailed, which who treats as "not linked". StubresolveDetailedto return the outcome you mean.Resolutionmay gain outcomes in a minor release, so aswitchover it should have adefault. - Use the autoconfigured
RbacService.RbacServiceis a@Service, so a component scan that finds it builds a second one without a publisher, which publishes no role events. Use the autoconfigured bean and keep it out of your scan. - Apps that build who's services themselves get events by passing a publisher. Each public
constructor you already use still works and publishes nothing. To get events, use the
constructor that takes a
WhoEventPublisher(and aClock). With the autoconfiguration, nothing to do.JsonAuthenticationHandlers: an application that defines its own bean with the old two-argument constructor publishes noSignInSucceededfor email link, email code or passkey sign-ins. Use the constructor that takes the publisher and a clock.
- New default methods on repository SPIs.
CredentialRemover.find,IdentityRepository.changeStatus,ApiKeyCredentialRepository.findById,JwtCredentialRepository.findById,EnrollmentTokenRepository.revokePendingForIdentityand the RBAC...IfAbsentand...IfPresentmethods have defaults, so existing implementations still compile. A custom implementation that keeps the defaults publishes less: credential events carry anulllabel, and noEnrollmentTokenRevokedis published for a token that a newer one replaced. Override them to get the full detail. - Listeners and logging. Spring's
AuthenticationSuccessEventalso fires for API-key sign-ins now. Use who's events for audit; see Spring's own sign-in events.
Upgrading to 0.16.0¶
0.16.0 has no schema or property changes. One small break:
WhoAuthenticationTokenandSignInFailedExceptionarefinal. Both called an inherited method from their constructor, which a subclass could observe half-built. If you extended either one, wrap it or keep the extra data beside it instead.
Optional: to keep sign-in emails in the request's trace, register a TaskDecorator such as
Spring's ContextPropagatingTaskDecorator; see
Tracing the send.
Upgrading to 0.15.0¶
0.15.0 adds a typed sign-in code to every sign-in email. It changes the schema, a required property, and several signatures.
- Upgrade the
who_email_link_tokentable. It gainedcode_hash VARCHAR(64) NOT NULLandcode_attempts INTEGER NOT NULL. Sign-in links that are outstanding during the upgrade are dropped; people request a new one.- Liquibase: nothing to do. The new changeSet
who-email-link-token-2runs at startup. -
Flyway, or the bundled scripts (
who.initialize-schema): run this once, for example as a Flyway migration. The bundled script does not change a table that already exists.- This is not a rolling upgrade. Stop the 0.14.0 instances first, and apply the schema change (Liquibase or the SQL) before or as 0.15.0 starts. If the columns are missing, sign-in emails silently stop:DELETE FROM who_email_link_token; ALTER TABLE who_email_link_token ADD COLUMN code_hash VARCHAR(64) NOT NULL, ADD COLUMN code_attempts INTEGER NOT NULL;/ott/generatestill answers202, and only a WARN is logged. - Setwho.email-link.code-secret. It is required when email-link sign-in is on, at least 32 characters, and the same on every instance. Startup fails without it. See Code secret. -EmailLinkSendertakes anEmailLinkMessage. The method is nowsend(EmailLinkMessage message)instead ofsend(String address, String link). The message carriesaddress,link,codeandexpiresAt, andformattedCode()gives the grouped code. Update custom senders to include the code. See Turn it on. -POST /login/otttakes two body shapes.{"token": "..."}as before, or{"email": "...", "code": "..."}. - New properties.who.email-link.code-length(default 6),code-max-attempts(default 5) andcode-secret. The default subject is nowYour sign-in link and code. - Changed signatures. Code that implements or calls these must change: -EmailLinkTokenRepository:issuetakes the code hash, andattemptCodeandconsumeCodeare new; -EmailLinkAuthenticationProvideris built with(repository, settings, whoService, clock); -WhoOneTimeTokenServiceis built with(clock, tokenTtl); -WhoOneTimeTokenService.consumenow throwsUnsupportedOperationException. who'sEmailLinkAuthenticationProviderredeems sign-ins, so an application that reuses that bean with Spring's default OTT provider must switch to who's provider.
- Liquibase: nothing to do. The new changeSet
Upgrading to 0.14.0¶
0.14.0 stops who from writing error responses. who now throws exceptions and your application formats them (see Errors). There are no schema changes.
- No more
{"error": …}bodies. Sign-in failures, passkey registration errors, signed-out requests and denied requests no longer answer with{"error":"invalid_token"},{"error":"invalid_credential"},{"error":"reauthentication_required"}or{"error":"invalid_registration"}. Each becomes an exception that reaches your@RestControllerAdvice. Without an advice, the status stays the same (401, 400 or 403) and the body is your application's default error body. A client that readerrorshould switch to your application's format. - Your advice now sees who's errors. Errors raised inside Spring Security's filters used to bypass your
@RestControllerAdvice; now they reach it. An advice with a catch-all@ExceptionHandler(Exception.class)would answer every signed-out request and failed sign-in with its own status, often a 500. Map who's exceptions (see Errors) before upgrading, or keep the catch-all from matching them. An advice limited bybasePackages,assignableTypesorannotationsnever sees them; who's errors need a global advice. - New entry point and access-denied handler.
WhoWebSecurity.passwordless()now installs an entry point and an access-denied handler that hand offNotSignedInExceptionandAccessDeniedException. They replace the bare 401 and Spring's empty 403. A chain that set its ownexceptionHandlingafter applyingpasswordless()keeps its own. JsonAuthenticationHandlers. The constructor is now(JsonMapper, WhoExceptionHandoff), andfailure(String)is gone;failure()hands off aSignInFailedException.PasskeyRegistrationGuardFilter. Its constructor takes aWhoExceptionHandoffinstead of aJsonMapper.WhoMeController.GET /who/methrowsNotSignedInExceptionwhen no one is signed in, instead of answering a bare401.
Upgrading to 0.13.0¶
0.13.0 is additive: WhoService.deactivate(identityId) and reactivate(identityId) take an identity
out of service and put it back, and who-test gains WhoMockMvcBrowser.performWithoutCsrf. Nothing
needs to change, and there are no schema changes.
Upgrading to 0.12.0¶
0.12.0 makes sessions ready for Spring Session, adds RBAC lookups and a test module, and has five changes that can affect existing code. There are no schema changes.
- No saved requests.
WhoWebSecurity.passwordless()now uses aNullRequestCache. A request denied with401is no longer saved in the session, so sign-in no longer leads to a redirect to a saved request. An SPA never relied on it, because it receives a plain401. If your chain redirected to the saved request, keep the target in your app instead. See Sessions. EmailLinkIssuer.issuereturns a value. It returns anEmailLinkOutcomeinstead ofvoid. Source that calls it still compiles, but code built against 0.11 must be recompiled, because the method's signature in the class file changed. A subclass or a mock that overridesissuemust change its return type. See Sending a link from your own code.RoleAlreadyExistsException. Creating a role whose name is taken now throwsRoleAlreadyExistsExceptioninstead of a plainIllegalArgumentException, with a message that does not name the role. It extendsIllegalArgumentException, so existingcatchblocks keep working.- New RBAC repository methods.
RoleRepositorygainsfindAll()andIdentityRoleRepositorygainsfindIdentityIdsByRoleId(UUID). An app with its own implementation of either interface must implement them, or it will not compile. The JDBC repositories who ships already do. - A new session attribute. The session now also holds the identity id (as a string) under Spring Session's principal-name index attribute. With Spring Session,
FindByIndexNameSessionRepository.findByPrincipalName(identityId.toString())finds the sessions of an identity. A test that asserts the exact attributes of a session must expect it. Sessions created before the upgrade have no such attribute until the user signs in again. See Sessions. - New.
RbacService.findRole,listRolesandfindIdentityIdsWithRole; thewho-testmodule (Testing); native serialization hints for sessions, so apps that added their own can drop them (Native Images).
Upgrading to 0.11.0¶
0.11.0 adds email-link sign-in, passkeys and sessions. It also changes every timestamp column to TIMESTAMP WITH TIME ZONE.
Convert the timestamp columns first¶
Existing databases created by 0.10.0 or earlier must run these statements before the upgrade. Who 0.11.0 reads and writes timestamps as UTC values, and reading the old TIMESTAMP columns may fail. The CREATE TABLE IF NOT EXISTS schema does not change existing tables.
The old columns hold local time without a zone. Use the time zone the JVM ran in, here UTC:
ALTER TABLE who_identity
ALTER COLUMN created_at TYPE timestamptz USING created_at AT TIME ZONE 'UTC',
ALTER COLUMN updated_at TYPE timestamptz USING updated_at AT TIME ZONE 'UTC';
ALTER TABLE who_enrollment_token
ALTER COLUMN created_at TYPE timestamptz USING created_at AT TIME ZONE 'UTC',
ALTER COLUMN expires_at TYPE timestamptz USING expires_at AT TIME ZONE 'UTC',
ALTER COLUMN redeemed_at TYPE timestamptz USING redeemed_at AT TIME ZONE 'UTC';
Replace UTC with the zone of the JVM (for example Europe/Berlin) if it was not UTC. These statements are for PostgreSQL. New schemas spell the type TIMESTAMP WITH TIME ZONE, which H2 and PostgreSQL both accept.
Other changes¶
- New tables. Email-link sign-in adds
who_email_credentialandwho_email_link_token. The bundled schema creates them. If you manage the schema with Flyway, copy them from Database Setup. - Passkeys are opt-in. The new
who-passkeymodule adds the tableswho_passkey_userandwho_passkey_credential. The bundled schema creates them. If you manage the schema with Flyway, copy them from Database Setup. Passkey storage is PostgreSQL only. Nothing changes until you setwho.passkey.rp-id. See Passkeys. - Schema files renamed. Each bundled schema file now starts with its module name. If you point
spring.sql.init.schema-locationsor your own tooling at them, update the paths:org/jwcarman/who/jdbc/who-jdbc-schema.sqlorg/jwcarman/who/rbac/who-rbac-schema.sqlorg/jwcarman/who/jwt/who-jwt-schema.sqlorg/jwcarman/who/enrollment/who-enrollment-schema.sqlorg/jwcarman/who/apikey/who-apikey-schema.sqlorg/jwcarman/who/emaillink/who-email-link-schema.sqlorg/jwcarman/who/passkey/who-passkey-schema.sql(new)
- Liquibase. The long YAML changelog in the old guide is gone. Include
classpath:org/jwcarman/who/db/who-changelog.xmlinstead. See Liquibase. Do not run it over tables that were created by hand withoutchangelog-syncfirst. - Email links are opt-in. Nothing changes for an application that uses only JWT or API keys. To turn them on, see Email Links.
- Sessions.
WhoWebSecurity.passwordless()is new and applies only to chains that call it. Other chains are unchanged.
Upgrading to 0.10.0¶
0.10.0 is a security release. Some changes break existing code or data.
- API key filter wiring.
ApiKeyAuthenticationFilteris no longer registered globally with the servlet container. Add it to each chain that should accept API keys:http.with(WhoApiKeySecurity.apiKey(), Customizer.withDefaults()). The filter skips requests that are already authenticated. See Wiring the filter. - Method security is on by default.
@RequiresPermissionis now enforced without any setup. Setwho.method-security.enabled=falseto turn it off. An@EnableMethodSecurityin your own configuration is respected. ApiKeyCredentialRepository.deleteByIdreturnsboolean. It returnstrueif a key was deleted. Update custom implementations. To revoke a key, callApiKeyService.revoke(UUID).- New key and token format. New API keys are
who_plus 43 URL-safe characters (256 random bits). Enrollment tokens use the same random source. Existing API keys keep working. Pending enrollment tokens issued before 0.10.0 are predictable (the token value followed from its id), so revoke them and issue new ones:
UPDATE who_enrollment_token SET status = 'REVOKED' WHERE status = 'PENDING';
enroll throws EnrollmentIdentityInactiveException for an identity that is not active, and CredentialAlreadyLinkedException for a credential that is already linked. A token is single use, even under concurrent requests. EnrollmentTokenNotFoundException no longer contains the token value, and EnrollmentToken.toString() masks the value.
- JWT claims. A token with no iss or no sub claim now gets 401 instead of 500. Validate the issuer too. See Configure JWT.
- Foreign key on who_identity_role. who_identity_role.identity_id now references who_identity(id) with ON DELETE CASCADE. Deleting an identity removes its role assignments, and assigning a role to an identity that is not in who_identity now fails. The CREATE TABLE IF NOT EXISTS schema does not change existing tables, so on an existing database run this yourself. Delete orphan rows first, or the constraint fails:
DELETE FROM who_identity_role
WHERE identity_id NOT IN (SELECT id FROM who_identity);
ALTER TABLE who_identity_role
ADD CONSTRAINT fk_identity_role_identity
FOREIGN KEY (identity_id) REFERENCES who_identity(id) ON DELETE CASCADE;