Enrollment¶
Before a JWT can authenticate, a FederatedCredential row must exist for the (issuer, subject) pair and must be linked to an active Identity. Who does not auto-provision — access is denied for unknown credentials.
Take the issuer and subject from the authenticated redeemer's own validated JWT. Never take them from the request body.
Using WhoEnrollmentService¶
// 1. Create an identity via WhoService
Identity identity = whoService.createIdentity();
// 2. Issue an enrollment token and deliver token.value() to the user out of band
EnrollmentToken token = enrollmentService.createToken(identity);
notifyUser(token.value()); // email, admin console, etc.
// 3. The user logs in, then redeems the token. issuer and subject come from the
// redeemer's validated JWT. Do this in one @Transactional method: find the
// credential or create it, then enroll. A failed enroll then leaves no credential
// row behind, and a retry finds the existing one.
FederatedCredential credential = federatedCredentialRepository
.findByIssuerAndSubject(issuer, subject)
.orElseGet(() -> federatedCredentialRepository.save(FederatedCredential.create(issuer, subject)));
Identity enrolled = enrollmentService.enroll(token.value(), credential);
// To cancel a token before it is redeemed:
enrollmentService.revokeToken(token);
A token can be redeemed once, even if two requests race. enroll throws:
EnrollmentTokenNotFoundExceptionif the token does not exist,EnrollmentTokenExpiredExceptionif it has expired,EnrollmentTokenNotPendingExceptionif it was already redeemed or revoked,EnrollmentIdentityInactiveExceptionif the identity is not active,CredentialAlreadyLinkedExceptionif the credential is already linked to an identity.
Manual SQL (bootstrapping and tests)¶
-- Create identity
INSERT INTO who_identity (id, status, created_at, updated_at)
VALUES (gen_random_uuid(), 'ACTIVE', NOW(), NOW());
-- Create a federated (issuer, subject) credential
INSERT INTO who_federated_credential (id, issuer, subject)
VALUES (gen_random_uuid(), 'https://your-issuer.com', 'alice');
-- Link credential to identity
INSERT INTO who_credential_identity (credential_id, identity_id)
VALUES (<credential_id>, <identity_id>);