Skip to content

Events

who publishes an event for every sign-in (success and failure), sign-out, ended session, sign-in email, and every change to identities, credentials, enrollment tokens and roles. Use them for an audit log, alerts and metrics. who does not store events; your application decides what to keep. who already counts them as Micrometer meters; see Observability.

Events are ordinary Spring application events. Listen with @EventListener:

@Component
class AuditLog {

  private static final Logger log = LoggerFactory.getLogger(AuditLog.class);

  @EventListener
  void on(SignInFailed event) {
    log.info("sign-in failed: method={} reason={} identity={}",
        event.method(), event.reason(), event.identityId());
  }

  @EventListener
  void on(CredentialAdded event) {
    log.info("credential added: identity={} kind={} credential={}",
        event.identityId(), event.kind(), event.credentialId());
  }

  @EventListener
  void on(WhoEvent event) {   // receives every event, including the two above
    // keep it to counts and metrics: logging the event here would record the two above twice
    log.debug("who event: {}", event.getClass().getSimpleName());
  }
}

Every event is a Java record that implements WhoEvent, whose occurredAt() says when it happened. Events live in the module that publishes them. A module's events are published only when that module is on the classpath.

The events

All events have occurredAt. Fields marked "or null" can be null; every other field is set. identityId, credentialId, tokenId and roleId are UUIDs.

Sign-in and sessions

Event Module Fires when Fields
SignInSucceeded who-core A sign-in is complete: email link, email code or passkey, after the session is saved. API-key and JWT requests publish none; see Spring's own sign-in events. method, identityId, credentialId
SignInFailed who-core A sign-in attempt fails, for every method, including each refused API-key or JWT request. The client still gets the same 401. method, reason, address or null, identityId or null, credentialId or null
SignedOut who-core A caller signs out of a who session. identityId, credentialId
SessionEnded who-core who drops a session because its identity is no longer active or its credential was revoked, or a session is ended from another browser or through WhoSessions. identityId, credentialId, reason
EndedSessionsPurged who-core A batch of ended or abandoned session records was deleted, on sign-in or by WhoSessions.purgeEndedSessions(). Not published for an empty batch. count
SignInEmailRequested who-email-link A request to POST /who/email/send has been handled, once per request. address or null, outcome, identityId or null
EmailAddressConfirmationRequested who-email-link A request to POST /who/me/email-addresses has been handled, once per request, on the email thread. identityId, address or null, change, outcome (SENT, INVALID_ADDRESS, ADDRESS_TAKEN, RESEND_SUPPRESSED, SEND_FAILED)
HumanCheckPerformed who-spring-security A request to one of who's human-checked endpoints was checked, once per request, before the endpoint runs. The token is never published. check, action, clientIp, outcome (PASSED, REFUSED, ERROR when the check threw). Turnstile handles a Cloudflare outage itself, so an outage is REFUSED, or PASSED with fail-open, never ERROR; its WARN log names it. clientIp is unknown when the container reported no address.
PasskeyRegistrationRefused who-passkey A signed-in identity tries to add a passkey, but signed in longer ago than the registration window allows. identityId, reason

SignInMethod: EMAIL_LINK, EMAIL_CODE, PASSKEY, API_KEY, JWT, OIDC.

SignInFailureReason, as fine as each path can tell without an extra database call:

Method Reasons
EMAIL_LINK MALFORMED, INVALID_LINK (unknown, used or expired), INACTIVE_IDENTITY
EMAIL_CODE MALFORMED, NO_LIVE_CODE (unknown address, no code, expired, or attempts used up), WRONG_CODE, CODE_ALREADY_USED (the right code lost a race with another use or expiry), INACTIVE_IDENTITY
PASSKEY INVALID_ASSERTION (signature, origin or unknown credential; they cannot be told apart), INACTIVE_IDENTITY
API_KEY UNKNOWN_KEY (malformed, unknown, revoked, or linked to no identity), EXPIRED_KEY, INACTIVE_IDENTITY
JWT MISSING_CLAIMS, UNKNOWN_CREDENTIAL, INACTIVE_IDENTITY
OIDC PROVIDER_ERROR (cancelled, refused by the provider, a state mismatch, a bad ID token or one from the wrong issuer), LINK_REFUSED (a link started too long ago, or answered for another identity; the event names the identity that started it), MISSING_CLAIMS, UNKNOWN_CREDENTIAL, INACTIVE_IDENTITY, SIGN_UP_REFUSED (the sign-up policy said no)

A JWT that Spring rejects before who sees it (bad signature, expired) publishes no who event; Spring publishes its own. The same goes for a malformed passkey assertion that Spring rejects before who's provider runs: no SignInFailed.

SessionEndReason: IDENTITY_INACTIVE when the session's credential now resolves to another identity, or its identity is inactive; CREDENTIAL_REVOKED when the credential is no longer linked; REVOKED when the person, or your code, ended it. A session that times out, is replaced by a new sign-in in the same browser, or whose identity was deleted (deleting an identity deletes its session records), publishes nothing; signing out publishes SignedOut.

EmailLinkOutcome: SENT, UNKNOWN_ADDRESS, INACTIVE_IDENTITY, RESEND_SUPPRESSED, SEND_FAILED. SignInEmailRequested is published on the email thread, after the caller has been answered with 202.

PasskeyRegistrationRefusedReason: REAUTHENTICATION_REQUIRED.

Identities and credentials

Event Module Fires when Fields
IdentityCreated who-core WhoService.createIdentity, or a confirmed provider sign-up identityId
IdentityDeactivated who-core An active identity is deactivated. Nothing is published if it already was. identityId
IdentityReactivated who-core An inactive identity is reactivated. identityId
IdentityDeleted who-core WhoService.deleteIdentity identityId
IdentityInvited who-email-link InvitationService.invite (and so POST /who/invitations) has created the identity, registered its address and assigned its roles. Published inside that transaction, before it commits: see below. identityId, address, roles (role names; empty if none)
OrphanedCredentialsPurged who-core Credentials linked to no identity are purged, including when registering an email address replaces an orphaned credential (count 1). count
CredentialAdded who-core A credential is linked to an identity: an email address registered, a passkey registered, an API key created, a provider account linked or signed up with, or an enrollment completed. identityId, credentialId, kind, label or null
CredentialRevoked who-core A credential is removed: an email address, passkey or API key revoked (by your code or through /who/me), a provider account unlinked, or an identity deleted (one event for each of its credentials). identityId, credentialId, kind, label or null

CredentialKind: EMAIL, PASSKEY, API_KEY, FEDERATED, OTHER. The label is the email address, the passkey's label, the API key's name, or the issuer of an (issuer, subject) credential.

Events fire only on a real change. Two concurrent calls that deactivate the same identity publish one IdentityDeactivated, and registering an email address the identity already owns publishes no CredentialAdded.

Removals that cascade publish nothing of their own: the parent event implies them. Deleting a role removes its permissions and assignments, and deleting an identity removes its role assignments and enrollment tokens, with only RoleDeleted or IdentityDeleted (and a CredentialRevoked for each credential of the identity).

To link (issuer, subject) credentials so that events fire, use FederatedCredentialService.link and unlink (JWT). Saving through FederatedCredentialRepository directly publishes nothing. unlink takes the credential's id.

Enrollment

Event Module Fires when Fields
EnrollmentTokenCreated who-enrollment WhoEnrollmentService.createToken identityId, tokenId
EnrollmentTokenRevoked who-enrollment A token is revoked, by request or because a newer token for the identity replaced it. identityId, tokenId

The token's value is never in an event. Completing an enrollment publishes CredentialAdded.

Roles

Event Module Fires when Fields
RoleCreated who-rbac A role is created. roleId, roleName
RoleDeleted who-rbac A role is deleted. roleId, roleName
RolePermissionAdded who-rbac A permission is granted to a role. roleId, roleName, permission
RolePermissionRemoved who-rbac A permission is revoked from a role. roleId, roleName, permission
RoleAssigned who-rbac A role is assigned to an identity. identityId, roleId, roleName
RoleUnassigned who-rbac A role is removed from an identity. identityId, roleId, roleName

Like identity changes, these fire only when something changed.

When listeners run

who publishes an event after the surrounding transaction commits. With no transaction (every sign-in, for example), it publishes at once. A change that is rolled back publishes nothing. So a listener always sees who's work as final, and it cannot roll that work back.

You do not need @TransactionalEventListener: a plain @EventListener already runs after commit. Listeners run synchronously on the thread that made the change, which is the request thread for sign-ins and admin calls. A sign-in's events are published after its response is decided, so no listener can change the answer.

Two limits to know:

  • A listener that throws. who catches a RuntimeException from publishing and logs a WARN, A listener failed on {}: {}, with the event's simple name and the exception's class name. The sign-in or change is not affected. Spring stops at the first listener that throws, so later listeners do not see that event. Handle your own failures inside the listener.
  • A listener that writes. A listener for an event from a transactional who change runs right after the commit, while that transaction's resources are still bound to the thread. A listener that writes to a database or calls a who service should run in its own transaction (@Transactional(propagation = Propagation.REQUIRES_NEW)) or @Async. Without that, whether its writes are committed depends on the transaction manager. With plain JDBC they may happen to be committed as a side effect of the connection being released. Spring documents that, in an after-commit callback, changes made through the finished transaction's resources (a JPA EntityManager, for example) are not committed (TransactionSynchronization#afterCommit), and a who service call that joins with REQUIRED runs in the already-finished transaction.
  • An event published from another listener's after-commit callback can be lost. This is the same limit @TransactionalEventListener has: the transaction is over by then. Do not make changes through who services from inside an after-commit callback and expect their events.

IdentityInvited runs inside the invitation

IdentityInvited is the one exception to the rules above. InvitationService.invite publishes it through Spring's ApplicationEventPublisher directly, synchronously, inside the transaction that creates the identity, registers its address and assigns its roles, before that transaction commits. So a listener can react in the same transaction, with a plain @EventListener and no REQUIRES_NEW. It is for cross-cutting reactions such as auditing; your application's own data for the new person (a profile row, a team membership) comes from the request, so it goes through the callback of InvitationService.invite(email, roleNames, callback), which runs in the same transaction, on the caller's thread, before this event is published:

@EventListener
void on(IdentityInvited event) {
  audit.record("invited", event.identityId(), event.roles());   // joins the invitation's transaction
}

A listener (or the callback) that throws rolls the whole invitation back: no identity, address or role remains, no sign-in link is sent, and the exception reaches the caller of invite. Through POST /who/invitations it is not one who maps, so the request fails as a server error; throw only when the invitation must not stand. who's own events from the same steps, such as IdentityCreated and CredentialAdded, are published only after the commit, so a rolled-back invitation publishes none of them. The link is sent only after the commit.

This is also why invite must be called outside any transaction of yours (it throws IllegalStateException otherwise): attach your data from the callback, not from code around the call. See Admin.

A listener with its own transaction

A database-backed audit listener, with its own transaction:

@Component
class AuditTrail {

  private final JdbcClient jdbc;

  AuditTrail(JdbcClient jdbc) {
    this.jdbc = jdbc;
  }

  @EventListener
  @Transactional(propagation = Propagation.REQUIRES_NEW)
  public void on(IdentityDeactivated event) {
    jdbc.sql("INSERT INTO audit (kind, identity_id, at) VALUES ('DEACTIVATED', :id, :at)")
        .param("id", event.identityId())
        .param("at", Timestamp.from(event.occurredAt()))
        .update();
  }
}

The method is public so that Spring's transactional proxy applies to it.

Personal data and untrusted text

  • SignInFailed, SignInEmailRequested, IdentityInvited and email CredentialAdded and CredentialRevoked carry an email address. That is deliberate: "40 failed codes for one address" is the most useful signal of an attack. Treat it as personal data when you store it.
  • Addresses are normalized (trimmed, lower-cased). An address is in an event only when it is safe to carry (bounded length, no control characters, EmailAddresses.isSafe). Otherwise the field is null, and a failed sign-in's reason is MALFORMED.
  • A passkey's label, an API key's name and a JWT issuer label are text that callers supply, and are not validated. A role name or permission may also come from your own admin screens. Treat these as untrusted when you log them: escape them, or log them as structured fields.
  • No event ever carries a link token, a code, an API key, an enrollment token value or a hash.

Reading the actor and the client

Events do not carry the acting identity or the client's address. Listeners run on the request thread, so read them there:

@EventListener
void on(RoleAssigned event) {
  Authentication actor = SecurityContextHolder.getContext().getAuthentication();
  String client = null;
  if (RequestContextHolder.getRequestAttributes() instanceof ServletRequestAttributes attributes) {
    client = attributes.getRequest().getRemoteAddr();
  }
  log.info("role {} assigned to {} by {} from {}",
      event.roleName(), event.identityId(), actor == null ? "nobody" : actor.getName(), client);
}

getRemoteAddr() is the proxy's address unless your application is configured for forwarded headers; who never reads X-Forwarded-For itself.

SignInEmailRequested is the exception: it is published on the email thread, where the request is gone. With a ContextPropagatingTaskDecorator, the trace context is still there (Tracing the send).

Slow listeners

A listener that does slow work slows the request it runs on, and work that differs by failure reason could make some failures take longer than others. Keep listeners quick, and move slow work (a network call, a large write) off the request thread:

@Async
@EventListener
void on(SignInFailed event) {
  // ship to a log service
}

Enable @Async with @EnableAsync. An asynchronous listener no longer has the actor or the client; read them first or leave that to a synchronous listener.

Spring's own sign-in events

Spring Security publishes AuthenticationSuccessEvent and AbstractAuthenticationFailureEvent for email, passkey and API-key sign-ins, among others. They do not carry who's reason or credential, and a sign-in can produce more than one. Use who's events for an audit trail and leave Spring's alone, or you will record each sign-in twice.

API keys and JWTs authenticate every request, so who publishes no SignInSucceeded for them: it would be one event per API call, not a sign-in. Refusals still publish SignInFailed with the reason. To see each authenticated API request, listen for Spring's AuthenticationSuccessEvent (API keys) or use Spring Security's request observations.

Compatibility

Events are public API. New event types, and new values in the enums above, may appear in a minor release, so a listener must tolerate values it does not know (a switch needs a default, and a catch-all WhoEvent listener should ignore what it cannot handle). Removing or renaming an event, a field or an enum value is a breaking change and comes with an upgrade note.

New record components may also be added to events in a minor release. Read fields through their accessors, and do not construct who's events or take them apart with record deconstruction patterns, which break when a component is added.

Sign-in events and custom handlers

SignInSucceeded for email links, email codes and passkeys is published by who's JSON success handler. If your application defines its own JsonAuthenticationHandlers bean with the old two-argument constructor, it publishes no SignInSucceeded. See Upgrading. API keys and JWTs publish only SignInFailed, from their authentication provider and converter, so they are not affected.