8000 GitHub - jwcarman/who: Identity, sign-in and permissions for Spring Boot: passwordless email links and passkeys, Google, GitHub and OpenID Connect sign-in, JWTs and API keys, all mapped to one identity with roles and permissions · GitHub
[go: up one dir, main page]

Skip to content
jwcarmanPublic

About

Identity, sign-in and permissions for Spring Boot: passwordless email links and passkeys, Google, GitHub and OpenID Connect sign-in, JWTs and API keys, all mapped to one identity with roles and permissions

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

1 star

Watchers

0 watching

Forks

Latest commit

 

History

780 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Who owl logo

Who

CI License Java Maven Central OpenSSF Scorecard OpenSSF Best Practices

Maintainability Rating Reliability Rating Security Rating Vulnerabilities Quality Gate Status Coverage

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

Requirements

  • Java 25+
  • Spring Boot 4.1+ (built against 4.1.2)
  • PostgreSQL 14+ required. It is the database Who is tested against.

Quick Start

1. Add the dependency

<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.

2. Create the tables

Add spring-boot-starter-liquibase. who creates and upgrades its own tables with Liquibase at startup, before your own migrations. See Database Setup.

3. Check permissions

@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.

Try the examples

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-app

Its 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).

Agent skill

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.

Upgrading to 0.10.0

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.

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, 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

Building

# 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

License

Apache License 2.0

About

Identity, sign-in and permissions for Spring Boot: passwordless email links and passkeys, Google, GitHub and OpenID Connect sign-in, JWTs and API keys, all mapped to one identity with roles and permissions

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages

0