Password login:
  User sends shared secret to server.

WebAuthn login:
  Server sends challenge to user agent.
  Authenticator signs challenge with private key.
  Server verifies signature with stored public key.

No shared password secret crosses the network.
Private key does not leave authenticator.
Credential is scoped to relying party identity.
Authentication is origin-aware.

A credential is not registered until server verifies the registration response.

An assertion proves possession of a private key for a registered credential under a specific challenge and origin.

Origin: https://app.example.com
RP ID:  example.com

Use RP ID too broad without controlling all subdomains.

RP ID should represent a security boundary you control.

create table webauthn_registration_challenge (
    id uuid primary key,
    tenant_id uuid not null,
    account_id uuid not null,
    ceremony_id uuid not null,
    challenge_hash bytea not null,
    rp_id varchar(253) not null,
    origin varchar(512) not null,
    user_handle bytea not null,
    username varchar(320) not null,
    require_user_verification boolean not null,
    attestation_policy varchar(64) not null,
    issued_at timestamptz not null,
    expires_at timestamptz not null,
    consumed_at timestamptz,
    status varchar(32) not null
);

create table webauthn_credential (
    id uuid primary key,
    tenant_id uuid not null,
    account_id uuid not null,
    user_handle bytea not null,
    credential_id bytea not null,
    public_key_cose bytea not null,
    signature_count bigint,
    transports jsonb not null default '[]'::jsonb,
    backup_eligible boolean,
    backup_state boolean,
    user_verified_required boolean not null,
    attestation_type varchar(64),
    aaguid uuid,
    label varchar(128),
    status varchar(32) not null,
    created_at timestamptz not null,
    last_used_at timestamptz,
    disabled_at timestamptz,
    version bigint not null default 0
);

create unique index uq_webauthn_credential_id
    on webauthn_credential(tenant_id, credential_id)
    where status = 'active';

create index idx_webauthn_account
    on webauthn_credential(tenant_id, account_id, status);

create table webauthn_authentication_challenge (
    id uuid primary key,
    tenant_id uuid not null,
    account_id uuid,
    ceremony_id uuid not null,
    challenge_hash bytea not null,
    rp_id varchar(253) not null,
    origin varchar(512) not null,
    require_user_verification boolean not null,
    purpose varchar(64) not null,
    issued_at timestamptz not null,
    expires_at timestamptz not null,
    consumed_at timestamptz,
    status varchar(32) not null,
    risk_snapshot jsonb not null default '{}'::jsonb
);

Challenge is not as sensitive as password, but storing only hash reduces blast radius and enforces one-way verification discipline.

user_handle = alice@example.com

user_handle = random 32-byte stable id

create table account_webauthn_identity (
    tenant_id uuid not null,
    account_id uuid not null,
    user_handle bytea not null,
    display_name varchar(256) not null,
    created_at timestamptz not null,
    primary key (tenant_id, account_id),
    unique (tenant_id, user_handle)
);

public byte[] generateUserHandle() {
    byte[] bytes = new byte[32];
    secureRandom.nextBytes(bytes);
    return bytes;
}

POST /auth/webauthn/register/options
Authorization: session with step-up
Content-Type: application/json

{
  "label": "MacBook Pro",
  "purpose": "add_passkey"
}

{
  "ceremonyId": "...",
  "publicKey": {
    "challenge": "base64url...",
    "rp": {
      "name": "Example Regulatory Platform",
      "id": "example.com"
    },
    "user": {
      "id": "base64url-user-handle",
      "name": "alice@example.com",
      "displayName": "Alice"
    },
    "pubKeyCredParams": [
      { "type": "public-key", "alg": -7 },
      { "type": "public-key", "alg": -257 }
    ],
    "timeout": 60000,
    "attestation": "none",
    "authenticatorSelection": {
      "residentKey": "preferred",
      "userVerification": "preferred"
    }
  }
}

POST /auth/webauthn/register/finish
Content-Type: application/json

{
  "ceremonyId": "...",
  "credential": {
    "id": "...",
    "rawId": "...",
    "type": "public-key",
    "response": {
      "clientDataJSON": "...",
      "attestationObject": "..."
    }
  }
}

[ ] ceremony exists and is active
[ ] ceremony not expired
[ ] challenge matches
[ ] origin is expected
[ ] RP ID hash matches expected RP ID
[ ] credential type is public-key
[ ] user presence flag is set if required
[ ] user verification flag is set if required
[ ] attestation policy satisfied if required
[ ] credential id not already active
[ ] public key parsed and stored
[ ] sign count stored if available/applicable
[ ] ceremony consumed atomically
[ ] audit event emitted

update webauthn_registration_challenge
set consumed_at = now(), status = 'consumed'
where ceremony_id = :ceremony_id
  and tenant_id = :tenant_id
  and status = 'active'
  and consumed_at is null
  and expires_at > now();

identifier -> account -> credential ids -> navigator.credentials.get()

challenge -> authenticator selects account -> assertion -> server maps credential

[ ] ceremony exists and active
[ ] challenge matches stored challenge
[ ] origin matches expected origin
[ ] RP ID hash matches expected RP ID
[ ] credential id exists and is active
[ ] credential belongs to expected account/tenant if username-first
[ ] signature verifies with stored public key
[ ] user presence flag acceptable
[ ] user verification flag satisfies policy
[ ] sign count handled according to policy
[ ] ceremony consumed atomically
[ ] credential last_used_at updated
[ ] session created/upgraded
[ ] authentication event emitted

credential id / user handle maps to account after assertion verification.

@Configuration
@EnableWebSecurity
public class SecurityConfig {

    @Bean
    SecurityFilterChain security(HttpSecurity http) throws Exception {
        return http
                .authorizeHttpRequests(auth -> auth
                        .requestMatchers("/login", "/webauthn/**", "/assets/**").permitAll()
                        .anyRequest().authenticated()
                )
                .formLogin(Customizer.withDefaults())
                .webAuthn(webAuthn -> webAuthn
                        .rpName("Example Regulatory Platform")
                        .rpId("example.com")
                        .allowedOrigins("https://app.example.com")
                )
                .build();
    }
}

public final class WebAuthnRelyingPartyFactory {

    public RelyingParty create(TenantWebAuthnConfig config,
                               CredentialRepository credentialRepository) {
        return RelyingParty.builder()
                .identity(RelyingPartyIdentity.builder()
                        .id(config.rpId())
                        .name(config.rpName())
                        .build())
                .credentialRepository(credentialRepository)
                .origins(config.allowedOrigins())
                .build();
    }
}

public final class DatabaseCredentialRepository implements CredentialRepository {

    private final WebAuthnCredentialDao dao;

    @Override
    public Set<PublicKeyCredentialDescriptor> getCredentialIdsForUsername(String username) {
        Account account = dao.findAccountByUsername(username)
                .orElseThrow();

        return dao.findActiveCredentials(account.tenantId(), account.id()).stream()
                .map(c -> PublicKeyCredentialDescriptor.builder()
                        .id(new ByteArray(c.credentialId()))
                        .type(PublicKeyCredentialType.PUBLIC_KEY)
                        .build())
                .collect(Collectors.toSet());
    }

    @Override
    public Optional<ByteArray> getUserHandleForUsername(String username) {
        return dao.findUserHandleByUsername(username).map(ByteArray::new);
    }

    @Override
    public Optional<String> getUsernameForUserHandle(ByteArray userHandle) {
        return dao.findUsernameByUserHandle(userHandle.getBytes());
    }

    @Override
    public Optional<RegisteredCredential> lookup(ByteArray credentialId,
                                                 ByteArray userHandle) {
        return dao.findByCredentialIdAndUserHandle(
                        credentialId.getBytes(), userHandle.getBytes())
                .map(c -> RegisteredCredential.builder()
                        .credentialId(new ByteArray(c.credentialId()))
                        .userHandle(new ByteArray(c.userHandle()))
                        .publicKeyCose(new ByteArray(c.publicKeyCose()))
                        .signatureCount(c.signatureCount())
                        .build());
    }

    @Override
    public Set<RegisteredCredential> lookupAll(ByteArray credentialId) {
        return dao.findAllByCredentialId(credentialId.getBytes()).stream()
                .map(c -> RegisteredCredential.builder()
                        .credentialId(new ByteArray(c.credentialId()))
                        .userHandle(new ByteArray(c.userHandle()))
                        .publicKeyCose(new ByteArray(c.publicKeyCose()))
                        .signatureCount(c.signatureCount())
                        .build())
                .collect(Collectors.toSet());
    }
}

public final class WebAuthnRegistrationService {

    private final RelyingPartyProvider relyingParties;
    private final CeremonyRepository ceremonies;
    private final WebAuthnCredentialRepository credentials;
    private final Clock clock;
    private final AuditLogger audit;

    public RegistrationOptionsResponse start(StartPasskeyRegistrationCommand command) {
        requireFreshStepUp(command.authentication());

        TenantWebAuthnConfig config = resolveConfig(command.tenantId(), command.origin());
        RelyingParty rp = relyingParties.forTenant(command.tenantId(), config);

        StartRegistrationOptions options = StartRegistrationOptions.builder()
                .user(UserIdentity.builder()
                        .name(command.username())
                        .displayName(command.displayName())
                        .id(new ByteArray(command.userHandle()))
                        .build())
                .authenticatorSelection(AuthenticatorSelectionCriteria.builder()
                        .residentKey(ResidentKeyRequirement.PREFERRED)
                        .userVerification(UserVerificationRequirement.PREFERRED)
                        .build())
                .build();

        PublicKeyCredentialCreationOptions creationOptions = rp.startRegistration(options);

        ceremonies.saveRegistration(command.tenantId(), command.accountId(),
                command.origin(), config.rpId(), creationOptions, clock.instant());

        audit.passkeyRegistrationStarted(command.accountId(), command.tenantId());

        return RegistrationOptionsResponse.from(creationOptions);
    }

    public void finish(FinishPasskeyRegistrationCommand command) {
        RegistrationCeremony ceremony = ceremonies.findActive(command.ceremonyId())
                .orElseThrow(() -> new InvalidWebAuthnCeremonyException());

        RelyingParty rp = relyingParties.forTenant(ceremony.tenantId(), ceremony.config());

        RegistrationResult result = rp.finishRegistration(FinishRegistrationOptions.builder()
                .request(ceremony.creationOptions())
                .response(command.credential())
                .build());

        credentials.insert(WebAuthnCredentialRecord.from(ceremony, result, clock.instant()));
        ceremonies.consume(ceremony.id(), clock.instant());
        audit.passkeyRegistrationSucceeded(ceremony.accountId(), ceremony.tenantId());
    }
}

public final class WebAuthnAuthenticationService {

    private final RelyingPartyProvider relyingParties;
    private final CeremonyRepository ceremonies;
    private final WebAuthnCredentialRepository credentials;
    private final SessionService sessions;
    private final AuditLogger audit;
    private final Clock clock;

    public AuthenticationOptionsResponse start(StartPasskeyAuthenticationCommand command) {
        TenantWebAuthnConfig config = resolveConfig(command.tenantId(), command.origin());
        RelyingParty rp = relyingParties.forTenant(command.tenantId(), config);

        StartAssertionOptions.StartAssertionOptionsBuilder builder = StartAssertionOptions.builder()
                .userVerification(UserVerificationRequirement.PREFERRED);

        command.username().ifPresent(builder::username);

        AssertionRequest request = rp.startAssertion(builder.build());

        ceremonies.saveAuthentication(command.tenantId(), command.accountId().orElse(null),
                command.origin(), config.rpId(), request, command.purpose(), clock.instant());

        return AuthenticationOptionsResponse.from(request);
    }

    public LoginResult finish(FinishPasskeyAuthenticationCommand command) {
        AuthenticationCeremony ceremony = ceremonies.findActive(command.ceremonyId())
                .orElseThrow(() -> new InvalidWebAuthnCeremonyException());

        RelyingParty rp = relyingParties.forTenant(ceremony.tenantId(), ceremony.config());

        AssertionResult result = rp.finishAssertion(FinishAssertionOptions.builder()
                .request(ceremony.assertionRequest())
                .response(command.assertion())
                .build());

        if (!result.isSuccess()) {
            audit.passkeyAuthenticationFailed(ceremony.tenantId(), "assertion_failed");
            throw new InvalidWebAuthnCeremonyException();
        }

        Account account = credentials.resolveAccount(
                ceremony.tenantId(),
                result.getCredentialId().getBytes(),
                result.getUserHandle().map(ByteArray::getBytes).orElse(null)
        );

        credentials.updateAfterSuccessfulAssertion(
                ceremony.tenantId(),
                result.getCredentialId().getBytes(),
                result.getSignatureCount(),
                clock.instant()
        );

        ceremonies.consume(ceremony.id(), clock.instant());

        AuthenticationEvidence evidence = AuthenticationEvidence.passkey(
                account.id(),
                ceremony.tenantId(),
                clock.instant(),
                result.isUserVerified()
        );

        audit.passkeyAuthenticationSucceeded(account.id(), ceremony.tenantId(), evidence);
        return sessions.create(account, evidence);
    }
}

For passwordless login: prefer or require user verification depending risk.
For admin step-up: require user verification.
For high-risk transaction: require user verification and transaction binding if available.
For MFA after password: user presence may be acceptable for some lower-risk cases, but user verification is stronger.

What kind of authenticator created this credential?

attestation = none

attestation may be required for approved hardware keys.

Requiring strict attestation for all users can break passkey adoption.
Not requiring attestation for privileged operators can allow unmanaged authenticators.

If counter increases: update stored counter.
If counter unexpectedly decreases or repeats for counter-capable credential: raise risk event.
Do not blindly lock all passkey users because counter semantics vary.

public void handleCounter(WebAuthnCredential credential, long newCounter) {
    Long old = credential.signatureCount();

    if (old != null && old > 0 && newCounter > 0 && newCounter <= old) {
        audit.possibleCredentialClone(credential.accountId(), credential.id(), old, newCounter);
        riskEngine.raiseSignal(credential.accountId(), "webauthn_counter_anomaly");
    }

    credentialRepository.updateSignatureCount(credential.id(), Math.max(old == null ? 0 : old, newCounter));
}

User clicks “Sign in with passkey”.
Browser presents account picker.
Authenticator signs challenge.
Server verifies assertion.
Server creates session.

Password verified -> WebAuthn assertion -> full session

Password + WebAuthn required every login, but recovery via email only.

Effective security = min(primary login, MFA, recovery)

RP ID: app.example.com or example.com
Credential table includes tenant_id.
Credential can be associated with one tenant account.

One passkey authenticates person.
Authorization chooses tenant membership after login.

Compromise/recovery affects all tenant memberships.

Your app delegates login to tenant IdP via OIDC/SAML.
Tenant IdP owns WebAuthn/passkey policy.
Your app consumes acr/amr.

tenant-a.customer.com

Never accept a WebAuthn assertion under a tenant different from the configured RP/origin/account mapping.

async function registerPasskey() {
  const optionsResponse = await fetch('/auth/webauthn/register/options', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ label: 'My device' })
  });

  const options = await optionsResponse.json();
  options.publicKey.challenge = base64urlToBuffer(options.publicKey.challenge);
  options.publicKey.user.id = base64urlToBuffer(options.publicKey.user.id);

  const credential = await navigator.credentials.create({
    publicKey: options.publicKey
  });

  const payload = publicKeyCredentialToJSON(credential);

  await fetch('/auth/webauthn/register/finish', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      ceremonyId: options.ceremonyId,
      credential: payload
    })
  });
}

async function authenticateWithPasskey() {
  const optionsResponse = await fetch('/auth/webauthn/authenticate/options', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({})
  });

  const options = await optionsResponse.json();
  options.publicKey.challenge = base64urlToBuffer(options.publicKey.challenge);

  if (options.publicKey.allowCredentials) {
    options.publicKey.allowCredentials = options.publicKey.allowCredentials.map(c => ({
      ...c,
      id: base64urlToBuffer(c.id)
    }));
  }

  const assertion = await navigator.credentials.get({
    publicKey: options.publicKey
  });

  await fetch('/auth/webauthn/authenticate/finish', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      ceremonyId: options.ceremonyId,
      assertion: publicKeyCredentialToJSON(assertion)
    })
  });
}

Phase 1: Add passkey as optional MFA for employees/admins.
Phase 2: Require phishing-resistant MFA for privileged roles.
Phase 3: Offer passkey-first login for normal users.
Phase 4: Introduce passwordless accounts with robust recovery.
Phase 5: Reduce password dependency for users with multiple strong authenticators.

Consumer: require at least one backup method before passwordless-only.
Admin: require two phishing-resistant authenticators if possible.
Break-glass: controlled hardware keys in vault process.

Create production API key

auth_webauthn_registration_started_total{tenant,rp_id}
auth_webauthn_registration_succeeded_total{tenant,rp_id,uv,attestation}
auth_webauthn_registration_failed_total{tenant,reason}
auth_webauthn_authentication_started_total{tenant,rp_id,mode}
auth_webauthn_authentication_succeeded_total{tenant,uv,discoverable}
auth_webauthn_authentication_failed_total{tenant,reason}
auth_webauthn_counter_anomaly_total{tenant}
auth_webauthn_credential_disabled_total{tenant,reason}
auth_webauthn_recovery_started_total{tenant}

{
  "event": "webauthn.authentication.succeeded",
  "tenantId": "...",
  "accountId": "...",
  "credentialIdHash": "...",
  "rpId": "example.com",
  "origin": "https://app.example.com",
  "userVerified": true,
  "purpose": "login",
  "assuranceLevel": "PHISHING_RESISTANT",
  "ipHash": "...",
  "userAgentHash": "...",
  "createdAt": "2026-07-03T10:00:00Z"
}

No passkey can be added without fresh authentication.
No disabled credential can authenticate.
No assertion under wrong origin is accepted.
No ceremony can be reused.
No credential from tenant A maps to tenant B.
No fallback recovery bypasses admin policy.

Works in dev, fails in prod/subdomain/custom domain.

RP ID/origin configuration does not match deployment reality.

Resolve RP config explicitly per environment/tenant.
Test with real domains over HTTPS.

Client sends origin or rpId in request; server uses it for verification.

Server determines allowed origin/RP ID from tenant/app config.

Passkey login is strong, but account recovery is email-only with no delay/audit.

Recovery policy must match account risk.

User starts registration under account A, browser/session changes, credential stored under account B.

Bind ceremony to account, tenant, session, and purpose.

High-risk admin action accepts assertion without user verification.

Require UV for admin/step-up/passwordless policy.

Password success creates full session before passkey assertion.

Use partial auth session or only create full session after WebAuthn success.

A credential id is globally unique but query omits tenant_id.

Every credential lookup includes tenant/security boundary.

Many normal users cannot enroll passkeys.

Use attestation none for normal users; enforce attestation only for managed high-risk roles.

Synced passkey counter behavior triggers mass lockout.

Treat counter anomaly as risk signal unless policy clearly supports hard block.

[ ] RP ID represents a domain/security boundary you control.
[ ] Allowed origins are explicit per environment/tenant.
[ ] Registration requires fresh authentication/step-up.
[ ] Registration challenge is stored, expires, and is consumed atomically.
[ ] Authentication challenge is stored, expires, and is consumed atomically.
[ ] Credential id and public key are stored correctly.
[ ] User handle is stable, opaque, non-PII.
[ ] Credential lookup includes tenant/account boundary.
[ ] Origin and RP ID are verified server-side.
[ ] User verification policy is explicit.
[ ] Attestation policy is explicit and risk-based.
[ ] Disabled credentials cannot authenticate.
[ ] Duplicate credential id cannot be active.
[ ] Passkey recovery policy is as strong as account risk requires.
[ ] Users are encouraged/required to register backup authenticators.
[ ] Admins require phishing-resistant MFA/passkeys/security keys.
[ ] Step-up can use WebAuthn and is max-age/action-bound where needed.
[ ] WebAuthn events are audited without leaking sensitive payloads.
[ ] Browser compatibility is tested.
[ ] Rollout metrics and support process exist.

The server no longer verifies a reusable secret typed by the user.
The server verifies a signature over a challenge under an RP-bound credential.

We added passkeys.

We know exactly which security boundary the credential is scoped to,
which account it binds to,
which ceremonies can create/use it,
which fallback can recover it,
and which actions require fresh phishing-resistant proof.