Identity, sign-in and permissions for Spring Boot applications. Who signs people in without passwords (by email, with a link or a typed code, by passkey, and with Google, GitHub or any OpenID Connect provider, with a session), and maps every credential a caller presents (a session, a JWT, an API key) to one stable internal identity. It resolves that identity's permissions and lets your controllers check permission strings without knowing which credential the caller used. Who formats no errors of its own: it throws, and your application answers in its own format.
📖 Documentation: jwcarman.github.io/who · API reference: jwcarman.github.io/who/api
- Java 25+
- Spring Boot 4.1+ (built against 4.1.2)
- PostgreSQL 14+ required. It is the database Who is tested against.
<dependency>
<groupId>org.jwcarman.who</groupId>
<artifactId>who-spring-boot-starter</artifactId>
<version>0.26.0</version>
</dependency>Add each sign-in method you use beside it (who-email-link, who-passkey, who-oidc,
who-apikey, who-jwt); its jar turns it on. With no SecurityFilterChain of your own, who's default chain
mounts them all. See Getting Started.
Add spring-boot-starter-liquibase. who creates and upgrades its own tables with Liquibase at
startup, before your own migrations. See
Database Setup.
@GetMapping("/tasks")
@RequiresPermission("task.read")
public List<Task> getTasks(@AuthenticationPrincipal WhoPrincipal principal) {
return taskService.findAll(principal.identity().id());
}Method security is on by default. Set up the credentials you accept with the JWT and API Keys guides, and link a user's credential to an identity with Enrollment.
who-examples/web-app is a server-rendered app that signs people in
with email links, passkeys and an identity provider on who's default chain. With Docker running,
Spring Boot starts its Postgres, Mailpit and Keycloak for you:
./mvnw install -DskipTests
./mvnw spring-boot:run -pl who-examples/web-appIts README says what to try.
who-examples/spa is the same app as a React single-page app over a JSON
backend, started the same way (-pl who-examples/spa); its README
covers Vite's dev server. who-examples/api is the board as a stateless JSON
API, called with Keycloak access tokens and who API keys (-pl who-examples/api); its
README walks through it with curl.
who-examples/web-and-api is one app that is both: a website with
sessions and an API with tokens and keys, each with a security chain of its own
(WhoSecurity.stateless() for the API).
who-examples/observability shows who's meters, traces and logs in
Grafana's LGTM stack, with a provisioned dashboard and a traffic generator
(-pl who-examples/observability).
who ships an Agent Skill for Claude Code and other coding agents, so an agent adding sign-in or permissions to your app follows who's guides instead of guessing. In Claude Code:
/plugin marketplace add jwcarman/who
/plugin install who@who
Other agents (Codex, Cursor, Gemini CLI, Copilot and more):
npx skills add https://github.com/jwcarman/who/tree/main/plugins/who/skills/who. See
Agent Skill.
0.10.0 is a security release with breaking changes: the API-key filter is no longer registered globally, method security is on by default, and existing databases need a foreign key and revoked pending enrollment tokens. See Upgrading to 0.10.0.
| Module | What it is |
|---|---|
who-core |
Domain types (Identity, WhoPrincipal), service and SPI interfaces. Needs no Spring at runtime; WhoService's @Transactional applies when Spring's transaction support is present (always, with who's starter) |
who-jdbc |
JDBC repositories, using Spring JdbcClient |
who-rbac |
RbacService and a PermissionsResolver backed by roles and permissions |
who-federated |
FederatedCredential, the (issuer, subject) credential that JWT and provider sign-in share, and FederatedCredentialService |
who-jwt |
WhoJwtAuthenticationConverter |
who-oidc |
Sign-in with Google, GitHub or any OpenID Connect provider, on Spring's oauth2Login: WhoSignUpPolicy decides who may sign up |
who-apikey |
ApiKeyAuthenticationFilter and ApiKeyService |
who-enrollment |
WhoEnrollmentService, for issuing and redeeming enrollment tokens |
who-admin |
Admin endpoints for identities, roles and invitations, guarded by who.identities.read and who.identities.manage; brings who-rbac |
who-email-link |
Email sign-in with a link or a typed code: EmailCredentialService, EmailLinkMessage, and the hooks for Spring's one-time-token login. Needs who-email and a sender |
who-email |
Renders who's emails from Mustache templates an application can override; subjects from its messages. See Email |
who-email-smtp |
Delivers who's emails over SMTP through Spring's JavaMailSender (who.email.from) |
who-turnstile |
Cloudflare Turnstile as the human check on who's email endpoints: TurnstileHumanCheck |
who-passkey |
Passkey sign-in: PasskeyService, PasskeyAddedNotifier, and the hooks for Spring's WebAuthn login |
who-spring-security |
@RequiresPermission, WhoSecurity.all(), WhoWebSecurity.passwordless(), WhoHumanCheck, GET /who/me and GET /who/sign-in |
who-autoconfigure |
Spring Boot autoconfiguration for all modules |
who-spring-boot-starter |
Starter with the base: who-core, who-spring-security, who-jdbc, who-rbac and the autoconfiguration. Add each sign-in module you use; its jar turns it on |
who-client |
@jwcarman/who-client on npm: a typed TypeScript client for the browser endpoints. See TypeScript Client |
# Compile and run tests
./mvnw clean verify
# Tests with code coverage
./mvnw clean verify -Pci
# Mutation testing (not part of CI; run it now and then to check test quality).
# Reports: <module>/target/pit-reports/index.html
./mvnw clean verify -Ppit
# Apply code formatting
./mvnw spotless:apply
# Build the docs site locally
pip install --require-hashes -r docs/requirements.txt
mkdocs serve