Attestation flow

1. RP sends the challenge to the client
2. Authenticator signs the challenge
   • optionally, the authenticator will confirm with the user about signing (this is usually just pressing a button on the key)
3. Client sends the signed challenge along with it's public key and the credential ID back to the RP
4. RP stores the information which it can then use later for authentication

Assertion flow

1. RP sends the challenge to the client
2. Authenticator signs the challenge
   • optional confirmation
3. Client sends the signed challenge back to the RP
4. RP uses the previously stored public key to check if the challenge was signed correctly

Here's a simple diagram of how everything works.

Attestation flow

1. RP sends the challenge to the client along with the user id of the user
2. Authenticator signs the challenge and stores the user id in it's memory
   • optional confirmation
3. Client sends the signed challenge along with it's public key and the credential ID back to the RP
4. RP stores the information which it can then use later for authentication

Assertion flow

1. RP sends the challenge to the client, but this time it's not linked to any user
2. Authenticator signs the challenge
   • optional confirmation
3. Client sends the signed challenge back to the RP along with the userHandle
4. RP uses the previously stored public key to check if the challenge was signed correctly

A thing to note about the userHandle:

• it should be a pseudo-random value
• it should not contain any personally identifiable information
• it must be a maximum of 64 bytes long (in JS, this is a 16 letter string)
  • if the string is longer, the authenticator will cut it off, so keep that in mind

Here's another diagram, very similar to the one above, but again with a few changes. Also this diagram describes the assertion process only because the attestation process the same as the one above.

Also, another popular way of doing usernameless + passwordless login today is via ✨ blockchain ✨ and ✨ Web 3.0 ✨. A colleague of mine, Luc van Kampen wrote a nice blog post about it.

Requesting a challenge

First thing we do is hit up the server and ask it to give us a challenge. Pretty simple stuff.

const attestation = await http.get("/webauthn/attestate/begin")
                            .then(res => res.data as PublicKeyCredentialCreationOptions);

Something like this, we wait for the server, and the returned data gets casted to PublicKeyCredentialCreationOptions. These names are insanely long, but hey, that's what IntelliSense is for.

The server response can be generated by simply invoking a function provided by fido2-lib. But it's not as easy as that, as I mentioned before, WebAuthn looooves ArrayBuffers. Get ready for encoding/decoding madness (encode and decode functions are imported from base64-arraybuffer).

const options = await fido2.attestationOptions();
options.user = { id: user.id, name: user.username, displayName: user.username };

const encoded = {
    ...options,
    challenge: encode(options.challenge)
};

// store the challenge to db
challenges[user.id] = encoded.challenge;

We first generate what's called attestationOptions that contain a challenge. Next step is to set the user we're setting up the key for. Keep in mind that user.id here is the userHandle used in the resident key process. The challenge is also given as an ArrayBuffer so we need to convert it to base64. Make sure to store the generated challenge in some database, we'll use it later for verification.

And now back in the browser we must decode it back to ArrayBuffers, aaaargh.

// cast to unknown because types, safe in this case
attestation.challenge = decode(attestation.challenge as unknown as string);
attestation.user.id = decode(attestation.user.id as unknown as string);

Authenticating

We can then pass our attestation options to CredentialsContainer (navigator.credentials). Since we're setting up the key, we call create, this will store the needed information on the authenticator. It will return a promise of type Credential, which may be null … or might error, so make sure to catch all that.

const credential: Credential | null | false = await navigator.credentials.create({ publicKey: attestation }).catch(() => false);
if(!credential)
    return;

Back to RP

Our credential now has everything needed for the server to know who we are. Simply pass it back

await http.post("/webauthn/attestate/end", encodeAttestationResponse(credential as PublicKeyCredential));

encodeAttestationResponse is simply a function that encodes rawId, response.attestationObject and response.clientDataJSON of the credential as base64. I'll let you have fun with this.

On the server side, we need to validate our response and store the credential ID and the public key in the database. We'll need it soon while doing assertion.

const result = await fido2.attestationResult({
    ...attestation,
    rawId: decode(attestation.rawId)
}, {
    rpId: "localhost",
    challenge: challenges[user.id], // get the previously stored challenge
    origin: "http://localhost:3000",
    factor: "either"
});

We of course need to decode the rawId back to an ArrayBuffer.

result will have clientData and authnrData maps containing some important data. What we need to store is "rawId" from clientData containing the credential ID and "credentialPublicKeyPem" from authnrData containing the public key in PEM format.

Requesting a challenge

This process is pretty similar to the one described above so I won't go as much in depth.

We start of by requesting a challenge. Exactly the same as above

const rawAssertion = await http.get("/webauthn/assert/begin")
                            .then(res => res.data as PublicKeyCredentialCreationOptions);

Again, fido2-lib provides us with another very simple function for generating this. But this time, the response will differ depending if you are using resident keys or not.

Normally

const options = await fido2.assertionOptions();

const encoded = {
    ...options,
    challenge: encode(options.challenge),
    allowCredentials: [{
        type: "public-key",
        id: user.credentialId,
        transports: ["usb", "ble", "nfc"]
    }]
};

challenges[user.id] = encoded.challenge;

As with attestation, we need to encode the challenge, but this time we also need to specify which credentials (keys) we want to allow the user to authenticate with. In this case, we only allow one, the one set up in attestation.

Make sure to store the challenge.

Using resident keys

const options = await fido2.assertionOptions(); // fido2 here has resident keys enabled

const encoded = {
    ...options,
    challenge: encode(options.challenge)
};

return encoded;

While using resident keys, this step is a lot easier, we just need to encode the challenge and thats it. Notice the challenge is not stored this time.

In the broser we need to decode our assertion again. This is mostly the same as in attestation, except we don't have to decode the user id, but on the other hand, all allowed credential IDs need to be decoded back to ArrayBuffers. In the example, I wrapped this in its seperate function that just loops over all allowed credentials, if they exist ofc (they wont if using resident keys), and decodes them.

const assertion = decodeAssertion(rawAssertion);

Authenticating

This step is exactly the same as described above, the only difference is that we no longer use create, but get instead.

Back to RP

We can now send this back to our server. Optionally, if using resident keys, we also must include the challenge our user signed.

await http.post("/webauthn/assert/end", { challenge: rawAssertion.challenge, ...encodeAssertResponse(credential as PublicKeyCredential) })

encodeAssertResponse is another function that encodes a bunch of stuff, specifically rawId, response.authenticatorData, response.clientDataJSON, response.signature and response.userHandle if it exists (it won't if not using resident keys). Encoded userHandle will return the user.id specified while attestating.

On the server, we just need to validate the response. Now this step is again different depending if you're using resident keys or not.

Normally

fido2.assertionResult({
    ...assertion,
    rawId: decode(assertion.rawId),
    response: {
        ...assertion.response,
        authenticatorData: decode(assertion.response.authenticatorData)
    }
}, {
    challenge: challenges[user.id], // get the previously stored challenge
    origin: "http://localhost:3000",
    factor: "either",
    publicKey: user.publicKey, // get the previously stored public key
    prevCounter: 0,
    userHandle: null
});

Notice we use the public key we stored before.

Using resident keys

// fido2 here has resident keys enabled
fido2.assertionResult({
    ...assertion,
    rawId: decode(assertion.rawId),
    response: {
        ...assertion.response,
        authenticatorData: decode(assertion.response.authenticatorData)
    }
}, {
    challenge,
    origin: "http://localhost:3000",
    factor: "either",
    publicKey: user.publicKey,
    prevCounter: 0,
    userHandle: null
});

Challenge is taken from the request we sent to the server and the user for the public key can be found using the userHandle

assertionResult returns a promise, if it resolves, the user authenticated correctly and if it doesn't, authentication failed.