Passkey basics · Implementation

The WebAuthn registration flow: what to check in challenge, options, and verify

7 min read

Key points

  • Registration has three steps, in which the server builds options, the browser calls create(), and the server verifies and stores the result.
  • The key options are a single-use challenge, a user.id with no personal data, excludeCredentials listing existing keys, and the residentKey and userVerification settings.
  • Verification checks the type, challenge, origin, RP ID hash, flags, and algorithm, and confirms the credential ID isn't registered to anyone before storing it.

WebAuthn registration has three steps: your server builds options (including a challenge, the RP ID, and the user's ID), the browser has the authenticator create a passkey through navigator.credentials.create(), and your server verifies the response and stores the public key. Your server checks that the response is a registration, that the challenge is one it issued, that the origin and RP ID are right, the user presence and verification flags, the algorithm, and that the credential ID isn't already in use by another user. The procedure is defined in section 7.1, "Registering a New Credential," of W3C WebAuthn Level 3.

The overall flow

Browser                       Server (RP)                      Authenticator
   |  1. start registration -->  |                                 |
   |  <-- 2. options             | create and store a challenge    |
   |  3. create(options) ------------------------------------------>|
   |                             |      verify user, make key pair |
   |  <------------------------------------ 4. public key, signed data
   |  5. send response  ------>  | 6. verify and store public key  |

Registration normally happens for a signed-in user, because your server decides whose passkey it is from its own session.

1. The server builds options

Your server builds the PublicKeyCredentialCreationOptions that go to navigator.credentials.create().

json
{
  "rp": { "id": "example.com", "name": "Example" },
  "user": {
    "id": "<64 random bytes (base64url)>",
    "name": "taro@example.com",
    "displayName": "Taro Yamada"
  },
  "challenge": "<at least 16 random bytes (base64url)>",
  "pubKeyCredParams": [
    { "type": "public-key", "alg": -8 },
    { "type": "public-key", "alg": -7 },
    { "type": "public-key", "alg": -257 }
  ],
  "excludeCredentials": [
    { "type": "public-key", "id": "<existing credential ID>", "transports": ["internal"] }
  ],
  "authenticatorSelection": { "residentKey": "preferred", "userVerification": "preferred" },
  "attestation": "none",
  "timeout": 300000
}

What each field means:

Field Meaning
rp.id The RP ID: the page's domain or a parent domain. The passkey only works within this scope
rp.name The service name shown in the dialog
user.id The user handle, at most 64 bytes. The spec says it must not contain personally identifying information such as a username or email, and recommends 64 random bytes
user.name / displayName Names shown in the dialog and the user's passkey list
challenge A random value from your server. The spec recommends at least 16 bytes. Store it server-side and use it once
pubKeyCredParams Accepted signature algorithms. The spec recommends including at least -8 (EdDSA), -7 (ES256), and -257 (RS256)
excludeCredentials The user's existing credentials, so the same authenticator doesn't get a second one
authenticatorSelection.residentKey Whether to require a discoverable credential: required / preferred / discouraged
authenticatorSelection.userVerification Whether to require biometric or PIN verification: required / preferred / discouraged
attestation Whether to ask for proof of the authenticator's provenance. Defaults to none
timeout A wait time in milliseconds. The spec treats it as a hint the browser may override

Handling the challenge

The challenge proves the response was made for this registration. Store it server-side tied to the user (or session), delete it once used, and give it an expiry. Accepting the same challenge twice opens the door to replaying an old response.

Choosing residentKey and userVerification

  • If username-less sign-in or autofill (conditional UI) will be your main entry point, set residentKey to required.
  • Setting userVerification to required blocks registration on authenticators that can't do biometrics or a PIN. Alternatively, use preferred and record the UV flag at verification time.

Attestation

Attestation is an optional statement that lets the RP check an authenticator's make and provenance. With none, the browser replaces potentially identifying information with non-identifying values. Unless you need to allow only specific authenticators (for example, in an internal tool), none is enough.

2. The browser calls create()

Convert the server's JSON into what the browser API expects, then call it. PublicKeyCredential.parseCreationOptionsFromJSON() saves you from decoding base64url strings into ArrayBuffers yourself. MDN lists it as newly available across major browsers since March 2025, so for older browsers write the conversion yourself or use a library.

js
const publicKey = PublicKeyCredential.parseCreationOptionsFromJSON(optionsJSON);
const credential = await navigator.credentials.create({ publicKey });
await fetch('/api/passkey/register/verify', {
  method: 'POST',
  headers: { 'content-type': 'application/json' },
  body: JSON.stringify(credential.toJSON()),
});

The authenticator verifies the user (fingerprint, face, PIN) and creates a key pair for the RP ID. If it already holds a credential listed in excludeCredentials, it refuses.

The response mainly contains:

  • id / rawId: the credential ID
  • response.clientDataJSON: what the browser recorded, including the type (webauthn.create), challenge, and origin
  • response.attestationObject: authenticator data (RP ID hash, flags, signature counter, credential ID, and public key) plus the attestation
  • response.transports: how to reach the authenticator (internal, hybrid, usb, and so on)

3. The server verifies

Section 7.1 of W3C WebAuthn Level 3 lists the steps the RP performs, in order. In summary:

  1. clientDataJSON.type is webauthn.create.
  2. challenge matches the value you issued and stored for this session.
  3. origin is an origin you accept (and, inside an iframe, topOrigin is checked too).
  4. The authenticator data's rpIdHash equals the SHA-256 hash of your RP ID.
  5. The UP (User Present) flag is set (the spec's only exception is registration with mediation set to conditional).
  6. If you require user verification, the UV (User Verified) flag is set.
  7. BS (Backup State) is not set when BE (Backup Eligibility) is unset.
  8. The public key's algorithm is one of those you listed in pubKeyCredParams.
  9. The attestation is verified according to its format and accepted or rejected per your policy (accepting none is a valid policy).
  10. The credential ID is at most 1023 bytes.
  11. The credential ID isn't already registered to any user.

A library or an external API does this for you. Still, knowing what is checked makes errors easier to trace. Origin mismatches, for example, often come from mixing up RP ID or origin settings between test and production.

4. What to store

The spec lists the fields of the "credential record" the RP stores after a successful registration:

Field Used for
id (credential ID) Identifying the key at sign-in
publicKey Verifying signatures
signCount The signature counter, a signal of possible cloning
uvInitialized Whether the user was verified
transports Telling the browser how to reach the authenticator next time
backupEligible / backupState Whether it's syncable and currently backed up

Add the user ID, a name ("iPhone"), the registration time, and the last-used time, and you'll have what you need for a device list and recovery screens.

Common mistakes

  • Putting an email address in user.id: This violates the spec and leaves personal data inside the authenticator. Use a random value.
  • Not passing excludeCredentials: The same authenticator collects duplicate keys for one user, and they become indistinguishable in the list.
  • Reusing challenges: Always delete a challenge once it's been used for verification.
  • Mismatched RP ID and origin: Make sure the page's domain equals the RP ID or sits under it.

Implementing with SealGate

With SealGate, the API builds the options and does the verification. For a signed-in user, your server makes two calls:

  • POST /v1/register/options with an external_id (an opaque ID) and display_name returns challenge_id and options. options.excludeCredentials contains the existing keys, and authenticatorSelection.residentKey and userVerification come from the environment settings (resident_key, user_verification).
  • After the browser SDK (sg.register()) runs the authenticator, POST /v1/register/verify with challenge_id and response (RegistrationResponseJSON) returns 201 with credential_id and end_user_id. An optional name (up to 64 characters) becomes the device label.

Challenges expire after 5 minutes and can be used once (410 challenge_expired). A failed signature check returns 401 verification_failed, and a response from an origin you didn't allow returns 403 origin_not_allowed. Adding a passkey for a user who already has one requires signed_in: true or a recovery_token. A duplicate on the same authenticator is refused by the authenticator, and the SDK reports it as already_registered. You can see each key's aaguid, transports, backup_eligible, and backed_up through GET /v1/users/{external_id}/credentials.

See the registration section of the docs for details.

FAQ

How long should the challenge be?

The WebAuthn spec recommends at least 16 random bytes. Generate it from a cryptographically secure source and use it once.

Is attestation "direct" more secure?

For consumer services, none rarely causes problems. Request attestation and define a verification policy only if you need to restrict which authenticators are allowed.

How is user.id different from the credential ID?

user.id is the user ID chosen by the RP and is shared by all of that user's passkeys. The credential ID is created by the authenticator for each key and differs for every passkey.

Sources

Related posts

Back to the blog