Who¶
Identity and permissions for Spring Boot applications.
Java 25+ · Spring Boot 4.1+ · PostgreSQL 14+
Who maps the credentials a caller presents (a JWT, an API key) to one stable internal identity, and resolves that identity's permissions. Your controllers check permission strings. They do not know which credential the caller used.
@GetMapping("/tasks")
@RequiresPermission("task.read")
public List<Task> getTasks(@AuthenticationPrincipal WhoPrincipal principal) {
return taskService.findAll(principal.identity().id());
}
How it works¶
Every request goes through this pipeline:
HttpRequest → Credential → Identity → Set<String> permissions → WhoPrincipal
- A credential is something a caller presents: the
(iss, sub)pair of a validated JWT, or an API key. Who stores credentials and links each one to an identity. - An identity is a UUID with a status. One identity can have many
credentials. Only
ACTIVEidentities authenticate. - A permissions resolver loads the identity's permission strings. With
who-rbac, permissions come from the roles assigned to the identity. - The resulting
WhoPrincipalgoes into the Spring Security context, and@RequiresPermissionchecks it.
Who does not auto-provision. A credential that is not linked to an identity is denied. You link credentials with an enrollment flow, or by creating them yourself.
What you get¶
-
JWT resource servers
WhoJwtAuthenticationConverterturns a validated JWT into aWhoPrincipal. See JWT. -
Social login
Sign in with Google, GitHub or any OpenID Connect provider. Sign-up is closed until your policy opens it, and nothing links by email. See Social Login.
-
API keys
Keys expire, hold only the permissions they were scoped to, record their last use, and rotate with an overlap. They are hashed before storage and shown once. See API Keys.
-
Enrollment
Single-use, expiring tokens that link a user's credential to an identity you created. See Enrollment.
-
Roles and permissions
RbacServicemanages roles.@RequiresPermissionis enforced by default. See RBAC and Method Security.
Examples¶
Runnable apps, one for each kind of app built on who, in
who-examples. Each starts what it needs
with Spring Boot's Docker Compose support.
- Web app: server-rendered pages with email links, passkeys and social login on who's default chain.
- Single-page app: the same app in React and TypeScript over a JSON backend, built by Maven into the jar or run on Vite's dev server.
- API: the board as a stateless JSON API, called with access tokens from Keycloak and with API keys, which people make and revoke through it.
- Website and API: one app
that is both, with a security chain for each: sessions and CSRF for the pages,
WhoSecurity.stateless()for/api/**. People manage their API keys on the website. - Observability: who's meters, traces and logs in Grafana's LGTM stack, with a provisioned dashboard, a traffic generator, and a page whose every request links to its trace and log lines.
Modules¶
| 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, WhoEmailSender, EmailLinkMessage, and the hooks for Spring's one-time-token login |
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(), 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 |