Getting Started¶
Requirements¶
- Java 25+
- Spring Boot 4.1+ (Who is built against 4.1.2)
- PostgreSQL 14+ required. It is the database Who is tested against.
Run the example app¶
To see every browser sign-in method working together, run the
web app example: with Docker
running, ./mvnw spring-boot:run -pl who-examples/web-app starts it with its Postgres, Mailpit and
Keycloak. The single-page app example
is the same app in React over a JSON backend.
The API example is the same board as a stateless JSON API, called with access tokens from Keycloak and with who API keys. Clone the repository and start it:
git clone https://github.com/jwcarman/who
cd who
./mvnw install -DskipTests
./mvnw spring-boot:run -pl who-examples/api
Its README gets a token with curl and walks through the calls, as alice (an admin), bob (a
member) and carol (who has a Keycloak account but no who identity, so her token gets 401).
Add the dependency¶
Import the BOM so that every who module uses the same version:
<dependencyManagement>
<dependencies>
<dependency>
<groupId>org.jwcarman.who</groupId>
<artifactId>who-bom</artifactId>
<version>0.24.0</version>
<type>pom</type>
<scope>import</scope>
</dependency>
</dependencies>
</dependencyManagement>
Then add the starter, each sign-in method you use, and who-test for your tests, with no
versions:
<dependency>
<groupId>org.jwcarman.who</groupId>
<artifactId>who-spring-boot-starter</artifactId>
</dependency>
<dependency>
<groupId>org.jwcarman.who</groupId>
<artifactId>who-email-link</artifactId>
</dependency>
<!-- email-link sign-in sends email: who-email renders it, who-email-smtp delivers it -->
<dependency>
<groupId>org.jwcarman.who</groupId>
<artifactId>who-email</artifactId>
</dependency>
<dependency>
<groupId>org.jwcarman.who</groupId>
<artifactId>who-email-smtp</artifactId>
</dependency>
<dependency>
<groupId>org.jwcarman.who</groupId>
<artifactId>who-test</artifactId>
<scope>test</scope>
</dependency>
The starter brings the base: identities, sessions, permissions and the autoconfiguration. Each sign-in method is its own module, and adding its jar turns it on:
| Sign-in method | Module | Guide |
|---|---|---|
| Emailed link or typed code | who-email-link, with who-email and a sender |
Email Links, Email |
| Passkey | who-passkey |
Passkeys |
| API key | who-apikey |
API Keys |
| JWT from your authorization server | who-jwt |
JWT |
| Google, GitHub or any OpenID Connect provider | who-oidc |
Social Login |
who-enrollment adds enrollment tokens, and who-admin endpoints for managing identities, roles and invitations. The BOM manages only who's own
artifacts, not Spring Boot's versions.
A module that needs settings fails startup until it has them, and the report says what to set, for example:
***************************
APPLICATION FAILED TO START
***************************
Description:
who cannot start: who.email-link.link-base-url must be set to the page that receives sign-in links.
Action:
Set it to the URL of your sign-in page, such as https://app.example.com/signin. Or turn email-link sign-in off with who.email-link.enabled=false.
who.<module>.enabled=false turns a module off without removing its jar. See the
Configuration Reference.
Secure the app¶
With no SecurityFilterChain of your own, who registers one in place of each default chain
Spring Boot would register (form login, the resource server's, Actuator's, oauth2Login's). It mounts
every sign-in method on the classpath and answers a signed-out request with 401 (as a
NotSignedInException, so your @RestControllerAdvice can shape it; see Errors).
There is no login page and no redirect. Signed-out requests may reach only:
/error;GET /who/sign-in, which tells a sign-in page which methods are on;- each sign-in method's endpoints, such as
/who/email/sendand/who/email/sign-in; - Actuator's health endpoint, if Actuator is present;
- the paths you list in
who.security.public-paths, and those anyWhoPublicPathContributorbean adds (see Configuration).
List your own sign-in page and the assets it loads there, including the page
who.email-link.link-base-url points at:
who:
security:
public-paths:
- /signin
- /assets/**
When a browser sign-in method (email link or passkey) is present, the chain protects against
CSRF with Spring's csrf.spa(). A request with a bearer token or an API key and no session is
exempt: the token or key signs it in or it gets 401. A request with a session ignores the token
or key and keeps its CSRF check. With only API keys or JWTs, who gives no request
a session, so the chain checks CSRF only on requests that bring one, and a signed-out client can
post to a public path.
Your own chain¶
Define any SecurityFilterChain and who's chain backs off; Spring Boot's rule. To keep who's
sign-in methods in a chain of your own, mount them all with WhoSecurity.all(), and open the same
paths with WhoPublicPaths:
@Bean
SecurityFilterChain chain(HttpSecurity http, WhoPublicPaths publicPaths) {
http.with(WhoSecurity.all(), Customizer.withDefaults())
.authorizeHttpRequests(a -> a
.requestMatchers(publicPaths.patterns()).permitAll()
.anyRequest().authenticated());
return http.build();
}
Or wire one method at a time, as each method's guide shows: WhoWebSecurity.passwordless() for
email links and passkeys, WhoApiKeySecurity.apiKey() for API keys, and Spring's
oauth2ResourceServer() with WhoJwtAuthenticationConverter for JWTs.
A website and an API¶
The most common reason for chains of your own is an app that is both a website for people and an API for machines. The website needs sessions and CSRF; the API needs neither, and must not accept a browser's session cookie. Give each its own chain, the API's first:
@Bean
@Order(1)
SecurityFilterChain api(HttpSecurity http) {
http.securityMatcher("/api/**")
.with(WhoSecurity.stateless(), Customizer.withDefaults())
.authorizeHttpRequests(a -> a.anyRequest().authenticated());
return http.build();
}
@Bean
@Order(2)
SecurityFilterChain web(HttpSecurity http, WhoPublicPaths publicPaths) {
http.with(WhoWebSecurity.passwordless(), Customizer.withDefaults())
.authorizeHttpRequests(a -> a
.requestMatchers(publicPaths.patterns()).permitAll()
.anyRequest().authenticated());
return http.build();
}
WhoSecurity.stateless() mounts only who's token and key sign-in (who-jwt, who-apikey), never
a browser method, into a chain that:
- never reads or creates a session, so a session cookie, who's or Spring's own, signs nothing in on the API and a signed-out call starts none;
- has no CSRF protection, because nothing it accepts rides along with a request by itself: a forged cross-site request cannot add the header a token or key travels in;
- answers a signed-out request with
401and a denied one with403, through your@RestControllerAdvicelike every who error; the401carriesWWW-Authenticate: Bearerwhen JWTs are on.
With neither who-jwt nor who-apikey on, startup fails. The
web-and-api example is this
app, runnable.
Create an identity¶
WhoService is the entry point for creating identities. Do not write to
IdentityRepository directly.
@Autowired WhoService whoService;
// A new ACTIVE identity with a generated UUIDv7
Identity identity = whoService.createIdentity();
UUID identityId = identity.id();
Everything else (enrolling credentials, assigning roles, issuing API keys) takes an identity created this way.
Deleting an identity¶
Delete identities through WhoService too:
boolean deleted = whoService.deleteIdentity(identityId); // false if there is no such identity
In one transaction, it deletes each of the identity's email, JWT and API key credentials, unlinks them, and deletes the identity. Its role assignments, enrollment tokens and passkeys go with it.
Do not run DELETE FROM who_identity yourself. Credential rows do not reference
their identity, so a raw delete removes only the links and leaves the credential
rows behind. EmailCredentialService.register lets the next identity register
such an orphaned address: it deletes the old credential, with any sign-in link
sent to the deleted user, and registers a new one. To clean them up, call:
int removed = whoService.purgeOrphanedCredentials();
It deletes every credential linked to no identity, including credentials that are unlinked only for now. A JWT credential saved for enrollment is unlinked until the user enrolls, and a credential being registered (an API key, say) is unlinked between being saved and being linked. Run the purge when no enrollment or registration is in flight.
If you replace one of who's credential repository beans, deleteIdentity and
the purge skip that module's rows unless your bean also implements
CredentialRemover (and is declared with a type that includes it).
Next steps¶
- Database Setup: create Who's tables.
- Email Links, Passkeys, API Keys or JWT: set up each sign-in method you added.
- Enrollment: link a user's credential to an identity.
- RBAC and Method Security: grant permissions and check them.