Marsel Akhmetshin

Posted on Apr 15 • Edited on Apr 27

🔓 Webauth Unlocked: An In-Depth Exploration of Advanced Authentication Solutions

#webauthn #webdev #authentication #f

Introduction

What is WebAuthn?

WebAuthn (short for Web Authentication) is an open web authentication standard developed by the World Wide Web Consortium in collaboration with the FIDO Alliance. This standard allows users to log on to websites and applications without using passwords, making the process more secure and easy. Instead of conventional authentication methods such as passwords or one-time codes sent via short messages or emails, WebAuthn uses biometric data (e.g., fingerprints or facial recognition), hardware security keys (e.g., USB tokens), or PIN codes.

How does it work?

The core principle behind WebAuthn is asymmetric cryptography and interaction between the user device, browser, and server. The authentication process using WebAuthn consists of two main steps: registration and authentication.

Registration

When a user registers on a website or application, a pair of keys is created: a public and a private. Here's how it works:

Registration request: As a user registers or adds a new authentication method, the website sends a request to the user’s browser asking it to initiate WebAuthn registration.
Key generation: A pair of unique keys (public and private) for this website or app is created on the user’s device. The private key stays securely stored on the device and never leaves it; the public key is meant to be sent to the server.
Registration with the server: The public key, along with some extra information such as authentication device data, is sent back to the server for registration. The private key remains on the user's device and is never shared.

Authentication

When a user logs on to the website or app, the authentication process is initiated:

Auth challenge: The server initiates authentication through the browser by sending a challenge to be signed with the user's private key.
User confirmation: To confirm authentication, the user must perform an action using their authentication device, e.g. entering a PIN code, using biometrics, or pressing a button on a hardware key.
Call signing: The authentication device creates a signature with the user's private key, based on the received call.
Signature verification: The signed response is then sent to the server where it is verified against the public key associated with the user account. Successful signature verification proves that it was generated with the correct private key stored on the user's device.

This process guarantees a high level of security since successful authentication requires the physical presence and action of the user on the device on which their private key is stored. Keys are associated with a specific website, which prevents them from being used on other resources if compromised.

Formats Description

Registration

A user opens our website and enters an email or another user ID into the input field, then presses ‘Register’; after that, we make a request where we send to the backend this email or another user ID that they entered. In the backend response, we receive the following data:

const publicKey = {
    challenge: new Uint8Array([117, 61, 252, 231, 191, 241, ...]),
    rp: { id: "acme.com", name: "ACME Corporation" },
    user: {
      id: new Uint8Array([79, 252, 83, 72, 214, 7, 89, 26]),
      name: "jamiedoe",
      displayName: "Jamie Doe"
    },
    pubKeyCredParams: [ {type: "public-key", alg: -7} ],
  }

Let's look at the structure of our authorization data configuration:

challenge – a one-time token generated for our session by the backend. This token is necessary to prevent replay attacks or, in other words, to prevent attackers from intercepting our request and executing it again, pretending to be us. *rp – the relying party. The object contains:
- id – the relying party's domain; it cannot be different from the current page domain.
- name – a human-readable name of the relying party, e.g. a company name.
user – the object with user data:
- id – a unique ID generated for the user. It is not recommended to use email, login, and other identifiers that may be valid outside the service on which registration takes place.
- name – a human-readable account identifier; it can be email or login. Conventionally, there could be the line “marsel.akhmetshin@example.com (Some company)”
- displayName – a user-friendly account name, for example, username or surname: “Marsel Akhmetshin”. Designed to make it clear to the user what kind of account this is. Can be an empty string.
- pubKeyCredParams – an array of public key types and encryption algorithms supported by the server. The structure of an array element consists of two fields: type and alg, where type is always “public key”, and alg is one of the following values in this list, but it is recommended to use at least
  - 8 – (Ed25519)
  - 7 – (ES256)
  - 257 – (RS256)

Above, we broke down the minimum configuration for creating a valid user public key. Later in the article, we will look at additional fields.

💡 Please note that all configuration properties of the ArrayBuffer type are data in binary representation

Once we have created the public key on the client device, we send it to the backend. A little later we will look at how it is created on the client. The result will look like this:

PublicKeyCredential {
    id: 'ADSUllKQmbqdGtpu4sjseh4cg2TxSvrbcHDTBsv4NSSX9...',
    rawId: ArrayBuffer(59),
    response: AuthenticatorAttestationResponse {
        clientDataJSON: ArrayBuffer(121),
        attestationObject: ArrayBuffer(306),
    },
    type: 'public-key'
}

💡 Please note that the public key will be sent once and only upon registration.

Let's look at the structure of Credentials that will be sent to the backend:

id – this is the authorization data ID that will be transmitted to our service during authentication. Using this ID, we can match our authorization request with the public key on the backend.
rawId – the same as id, only in binary representation.
response
- clientDataJSON – JSON with client parameters.
  - type – a field that contains the line “webauthn.create”, which means that the user is being registered.
  - origin – a URL from which the user registration request was made. If the request was made from an iframe, then the iframe’s origin will be used.
  - challenge – one-time token preventing replay attacks.
- attestationObject – flags, authenticator certificate data, and the user’s public key, which will be needed to confirm the validity of the user’s signature during authorization. The data is transmitted in binary format CBOR (Concise Binary Object Representation). > 💡 Don't worry, we'll talk about flags and certificates later in this article.

Below is a diagram describing the registration process:

Source: https://w3c.github.io/webauthn/#sctn-usecase-registration

Authorization (authentication)

During authorization, the user enters a login, which is then sent to the server, and the server returns the credentialId for this login, if present. Next, on the client, we create a user signature request configuration for the previously registered public key:

const publicKeyCredentialRequestOptions = {
    challenge: Uint8Array.from(
        randomStringFromServer, c => c.charCodeAt(0))
}

Let's look at the structure of our configuration:

challenge – one-time token preventing replay attacks. Yes, only challenge is required, this is enough to start the authorization process.

Next, the following object will be sent to the backend:

PublicKeyCredential {
    id: 'ADSUllKQmbqdGtpu4sjseh4cg2TxSvrbcHDTBsv4NSSX9...',
    rawId: ArrayBuffer(59),
    response: AuthenticatorAssertionResponse {
        authenticatorData: ArrayBuffer(191),
        clientDataJSON: ArrayBuffer(118),
        signature: ArrayBuffer(70),
        userHandle: ArrayBuffer(10)
    },
    type: 'public-key'
}

What does it consist of:

id - the same as credentialId
rawId - the same as id only in binary representation
response
- authenticatorData contains rpID, flags, key usage counter (increases each time the key is used), and authenticator extensions.
- clientDataJSON - the same browser data as during registration: origin, challenge, and type – except that during authorization it contains the value “webauthn.get”
- signature – signature generated by the private key on the client/device side. It is needed to check whether it matches the public key.
- userHandle – an optional array that stores the user.id passed to the user object during registration.
type – always “public-key” Below is a diagram describing authorization: Source: https://w3c.github.io/webauthn/#sctn-usecase-registration
General Implementation

Registration

We've reviewed the formats, and now let's look at how registration and authentication are handled in code. Once we have received the configuration of our authorization credentials, we need to pass them to the navigator.credentials.create method

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

On the client we call navigator.credentials.create and we pass our credentials configuration to the publicKey property.

To check if the WebAuthn API is supported by the browser, you can access window and its PublicKeyCredential property, the value of which must not be undefined.
Next, having created our credentials, we must send them to the backend. On the backend we need to parse the received credentials:

First, we must perform a basic verification of the validity of the challenge – that it is relevant, the correctness of the domain from which the user creation request is being made, and at the very end, we must check if the request type is correct; in our case it is registration, and we expect that the type will be “webauthn.create"

// decode the clientDataJSON into a utf-8 string
const utf8Decoder = new TextDecoder('utf-8');
const decodedClientData = utf8Decoder.decode(
    credential.response.clientDataJSON)

// parse the string as an object
const clientDataObj = JSON.parse(decodedClientData);

console.log(clientDataObj)
/*
{
    challenge: "p5aV2uHXr0AOqUk7HQitvi-Ny1....",
    origin: "https://webauthn.guide",
    type: "webauthn.create"
}
*/

Example from https://webauthn.guide/

Next, we need to parse our attestationObject. The data is compressed in CBOR format, so we will need a CBOR decoder.

const decodedAttestationObj = CBOR.decode(
    credential.response.attestationObject);

console.log(decodedAttestationObject);
/*
{
    authData: Uint8Array(196),
    fmt: "fido-u2f",
    attStmt: {
        sig: Uint8Array(70),
        x5c: Array(1),
    },
}
*/

Example from https://webauthn.guide/

Of the attestationObject, we are most interested in the authData property; let's take a closer look at it. Below is a diagram of what contains authData: AuthData is a byte array containing the following data:
RP ID Hash: SHA-256 hash of the resource identifier (Relying Party ID, usually the domain) for which the key is created.
Flags: A byte indicating various attributes of the operation. We'll deal with this later.
Signature Counter: A 4-byte value that the authenticator increments by one each time it is used to generate a claim. This prevents replay attacks.
Attested Credential Data: This section is present if the AT flag is set. It contains the following elements:
- AAGUID (Authenticator Attestation GUID): A 16-byte identifier showing the authenticator model.
- L (key length): A 2-byte value indicating the length of the key following it.
- Key: The user's public key generated by the authenticator for this site. The key format depends on the cryptographic scheme used.

In this list, Attested Credential Data interests us the most. This is where our user’s public key is located, which must be kept on the backend.

Next, let's look at how we can extract this key:

const {authData} = decodedAttestationObject;

// get the length of the credential ID
const dataView = new DataView(
    new ArrayBuffer(2));
const idLenBytes = authData.slice(53, 55);

idLenBytes.forEach(
    (value, index) => dataView.setUint8(
        index, value));

const credentialIdLength = dataView.getUint16();

// get the credential ID
const credentialId = authData.slice(
    55, 55 + credentialIdLength);

// get the public key object
const publicKeyBytes = authData.slice(
    55 + credentialIdLength);

// the publicKeyBytes are encoded again as CBOR
const publicKeyObject = CBOR.decode(
    publicKeyBytes.buffer);

console.log(publicKeyObject)
/*
{
    1: 2,
    3: -7,
    -1: 1,
    -2: Uint8Array(32) ...
    -3: Uint8Array(32) ...
}
*/

Example from https://webauthn.guide

Below I describe in detail what is happening here, but there is no need to look into it too much since our main goal is to get the public key

So, what's happening in the code?

Extracting authData: The authData variable is obtained from the decoded attestation object, which is a byte array containing the authenticator data.
Obtaining Credential ID Length:
- A DataView is created on top of a new ArrayBuffer 2 bytes long. DataView is used to easily read and write typed data into ArrayBuffer.
- A 2-byte slice is extracted from authData, starting from the 53rd byte. The slice contains information about the length of the credential identifier.
- These bytes are written to the DataView, and then the length of the credential ID is obtained as a 16-bit unsigned integer (a value between 0 and 65,535) using getUint16.
Obtaining the Credential ID:
- Using the known length, the part containing the credential identifier itself is extracted from authData, starting from the 55th byte to 55 + credentialIdLength.
Obtaining the public key:
- The remainder of authData after the credential identifier is supposed to contain the public key, encoded using CBOR.
Decoding the public key:
- The resulting public key byte array (publicKeyBytes) is decoded from the CBOR format to obtain the public key object.
The public key object output:
- The console displays the public key object, where the keys denote the parameters of the key, for example, 1 for the key type, 3 for the algorithm, 1 for the curve (in the case of ECDSA), 2 and 3 for the X and Y coordinates of the public key in the case of ECDSA or the N and E components for RSA.

In the final output, publicKeyObject contains the decoded public key. Each key in the object denotes a specific public key attribute:

1 indicates the key type (for example, ECDSA),
3 denotes the encryption algorithm,
1 can indicate the elliptic curve used,
2 and 3 typically represent components of the public key, such as coordinates for ECDSA.

All that remains is to associate this credentialId, public key, with our internal userId and save it in the database.

Authorization

Now let’s talk about how authorization via WebAuthn is implemented.

It all starts with the backend sending us a challenge. This is the minimum set to obtain a signature and credentialId from the client and send it to the backend for authorization.

const publicKeyCredentialRequestOptions = {
    challenge: Uint8Array.from(
        randomStringFromServer, c => c.charCodeAt(0)),
}

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

To request authentication data from the user, we need to call navigator.credentials.get and pass our resulting publicKeyCredentialRequestOptions object there. Next, this assertion will need to be sent to the backend; it will contain the PublicKeyCredential (see the format description above).

On the backend, we need to get our signature from PublicKeyCredential. The signature is essentially proof that the device owns the private key.

An example of key decryption might look like this:

const storedCredential = await getCredentialFromDatabase(
    userHandle, credentialId);

const signedData = (
    authenticatorDataBytes +
    hashedClientDataJSON);

const signatureIsValid = storedCredential.publicKey.verify(
    signature, signedData);

if (signatureIsValid) {
    return "Hooray! The user is authenticated! 🎉";
} else {
    return "Verification failed. 😭"
}

What's going on here: First, we get the user's credentialId from the backend, and then we create signedData. To create signedData, first, we must hash our clientDataJSON using the SHA-256 algorithm and add it to authData. Next, we must take the resulting authData, signature, and public key and verify the signature.

Below is an example of solving the same problem using crypto in nodeJS:

const crypto = require('crypto');

// We assume that signature, signedData, and publicKey have already been received
// signature must be in Buffer format or string
// publicKey must be in a format suitable for use with the crypto module, such as PEM

const verifySignature = (publicKey, signature, signedData) => {
    const verifier = crypto.createVerify('SHA256');
    verifier.update(signedData);
    verifier.end();

    return verifier.verify(publicKey, signature);
};

const signatureIsValid = verifySignature(publicKey, signature, signedData);

if (signatureIsValid) {
    console.log("Signature is valid. User is authenticated.");
} else {
    console.log("Signature is invalid. Verification failed.");
}


} else {
    return "Verification failed. 😭"
}

💡 Please note that before checking the signature on the backend, we first need to make sure that the challenge is valid, the number of uses of this authorization data has increased, and the origin is correct and matches the domain from which we expect authorization and registration.

Additional Format Options

Registration

I already described the public key configuration format above in basic terms. Now, let's look at additional fields and public key configuration options:

const publicKey = {
    challenge: new Uint8Array([117, 61, 252, 231, 191, 241, ...]),
    rp: { id: "acme.com", name: "ACME Corporation" },
    user: {
      id: new Uint8Array([79, 252, 83, 72, 214, 7, 89, 26]),
      name: "jamiedoe",
      displayName: "Jamie Doe"
    },
    pubKeyCredParams: [ {type: "public-key", alg: -7} ],

    // additional fields
    timeout: 60000,
    excludeCredentials: [{
        id:  new Uint8Array([79, 252, 83, 72, 214, 7, 89, 26, 88]),
        type: "public-key",
    }],
    authenticatorSelection: {
           authenticatorAttachment: "platform" | "cross-platform",
               residentKey: "required" | "preferred" | "discouraged",
         userVerification = "required" | "preferred" | "discouraged"
    },
    attestation:"none" | "indirect" | "direct" | "enterprise"
    attestationFormats: []
  }

Now let's examine what these additional properties are and what they are needed for:

timeout is the time the device will wait for the user to respond, in milliseconds. If the user does not confirm registration/authorization within this time, the authorization and registration process will end with an error. It is also worth noting that for each authorization/registration attempt, you must generate a new challenge.
- excludeCredentials is an array of credentialIds. Needed to prevent re-registration of the user if the authenticator already contains a credentialId from the credentialId list for this user.id.
- authenticatorSelection – authenticator device settings:
- authenticatorAttachment - an authenticator type selector where:
  - platform means that the device authenticator (faceId or touchID) will be used or
  - cross-platform means that both the platform authenticator and, for example, YubiKey can be used.
- residentKey – a parameter responsible for whether the private key should be stored on the device or not. It has three possible values:
  - required – means the key must be stored on the device,
  - preferred – means that priority is given to storing the key on the device, but if this is not supported by the device, then it is also possible for the key not to be stored on it, and
  - discouraged – storing the key on the device is not required if possible and preference is given to keys stored not on the device if the device supports it.

💡 Simply put, in one case the authenticator device knows and stores the credentialId and the public key, while in the other case, both are provided by the server, and the device attempts to find a connected authenticator for this credentialId.

userVerification – this parameter determines how involved the user should be in authorization:
- required – authentication must be done with user verification. This means that the authentication device must require additional action from the user, such as entering a PIN, using biometrics (e.g. a fingerprint or facial recognition), or another method that verifies that the user is the actual owner of the device.
- preferred – the authenticator should verify the user if possible. In this case, if the device supports user verification, it will be used. If the device does not support sufficient verification methods, authentication can be performed without this step.
- discouraged - user verification is not required. The system may allow authentication without explicitly confirming the user's identity. This can be used in situations where user convenience is a priority or where a simplified login procedure is required. > 💡User verification is not required means that the user, for example, simply inserted a key/signature token without any passwords or biometrics.
attestation is a kind of root certification authority for the authenticator or data by which you can determine on the server how much you can trust the authenticator. Supports the following values:
- none – attestation type none means that no attestation data is provided. In other words, we don't want to validate the authenticator.
- indirect – with indirect attestation, the authentication device can use intermediate certificates to create a chain of trust back to the root certificate. This is a kind of anonymous certificate. For example, we trust the authenticator’s certificate, but we do not know what kind of device was used as an authenticator. In the case of FaceID, we will not know that it is FaceID, but we can look at the certificate confirming the authenticity of the device.
- direct – attestation means that the authentication device directly provides attestation data, including a certificate signed by the device's root certificate or enterprise certificate. In the case of FaceID, we will receive both a certificate confirming the authenticity of the device and the type of authenticator device itself.
- enterprise attestation allows organizations to use their own attestation methods that can be integrated into the enterprise security infrastructure.
- attestationFormats - the preferred certificate format that can be requested from the client, e.g., “apple” (faceId, touchId). The list is here.

Now let's look at the authorization configuration format:

const publicKeyCredentialRequestOptions = {
    challenge: Uint8Array.from(
        randomStringFromServer, c => c.charCodeAt(0)),

    // additional fields
    timeout: 600000,
    rpId: 'example.com'
    allowCredentials: [{
         id:  new Uint8Array([79, 252, 83, 72, 214, 7, 89, 26, 88]), // credenitalId
         type: "public-key",
         transports: [ 
         "usb",
           "nfc",
       "ble",
       "smart-card",
       "hybrid",
       "internal"
       ]
    }]

}

The structure of the authorization configuration is much simpler than that of registration. We are already familiar with timeout, so let's take a closer look at rpId and allowCredentials.

rpId is a domain, needed to indicate to the client which domain the authorization is being performed for. For example, if it turns out that the domain where authorization is performed does not match rpId, then authorization will end with an error. If this parameter is not specified during authorization, the domain from the browser context or the current webpage’s domain will be substituted instead.
allowCredentials – here it is worth considering contexts. If the key is stored on the authenticator device (see the residentKey property) then allowCredentials is optional. However, if the authenticator does not store the key and credentialId, then allowCredentials are mandatory – otherwise, the client won’t be able to find the required authentication data.

Attestation object

In the context of WebAuthn, an attestation object is structured data generated by an authenticator during user registration. This object contains the information necessary to confirm the authenticity and reliability of the authentication device from the server side. Here are the key components of a certification object:

The fmt byte group in the WebAuthn attestation object denotes the Attestation Statement Format. This string value defines how the data in the attestation statement is structured and should be interpreted. Here are some standard attestation formats that can be specified in the fmt field:

packed is one of the most common attestation formats that supports both self-attestation and certification authority (CA) attestation. An attestation statement in this format contains a signature generated by the authentication device, covering the authentication data and the client data.
fido-u2f - this format is used by devices compatible with the FIDO Alliance U2F (Universal 2nd Factor). The attestation statement in U2F format contains a signature generated using the device's private key and an authentication device certificate.
tpm (Trusted Platform) - a format used for authentication devices that support TPM. The attestation statement for a TPM contains the signature generated by the TPM device, as well as information about the public key and certificate generated by the TPM.
android-key is an Android-specific format used when credentials are created and managed by the Android Keystore. The attestation statement contains a signature and certificate confirming that the key was generated and stored in the secure Android Keystore environment.
android-safetynet - this format uses Google SafetyNet services to confirm that the device and operating system are in a safe state. An attestation statement in this format includes a JWT signed by Google.
apple is an attestation format used in Apple devices. This format is often associated with the concept of privacy, where attestation data minimizes the amount of user and device information transmitted.
none - used when no attestation data is provided. This format may be chosen for scenarios where device attestation is not required or when user privacy needs to be maximized. attStmt bytes consist of:
alg is the encryption algorithm used to create the cryptographic signature sig
sig is the authenticator certificate’s signature; it is used during registration to verify that the data was signed by this authenticator. To do this, you need to extract the public key of the authenticator – it’s located in the x5c field and must be the first certificate in this chain, – take sig and repeat the same signature verification procedure (see above) as during authentication, only use sig as as signature and use the first key from x5c as the public key
x5c is an X.509 certificate chain that is typically used to establish trust in the certificate's public key. May be missing, depending on the authenticator's certificate.

authData is the most important block of bytes. It contains the public key, various flags, and the authentication data identifier. Let's take a closer look at its structure:

rpIdHash – a domain hashed using the SHA-256 algorithm
flags are boolean values where each bit has a value of 0 or 1:
- UP (User Presence) – this flag indicates whether a physical user action was recorded during the authentication process, such as pressing a button on the authenticator. This serves as proof that the user is actually present during the authentication operation.
- UV (User Verified) – this flag indicates whether the user has been verified by the authenticator, e.g., through biometrics or a PIN. If the flag is set, this means that additional user authentication has been performed.
- BE (Backup Eligibility) – the flag shows whether it is allowed to create a backup copy of the key, which is relevant if the authorization data can be transferred to another device. However, as the authenticator’s certificate is received only during registration, there is no way to find out that the key is being used on another device within the WebAuthn standard.
- BS (Backup State) - the flag shows if the authorization data was copied, that is, if a backup copy was created. Note that you can rely on this flag only if the BE bit is set to 1! The fifth bit in the structure is reserved for the future
- AT (Attested Credential Data Included) – the flag indicates that attested credential data is included in authData. This means that the authentication data contains additional elements such as AAGUID (device identifier), credential ID, and public key.
- ED (Extension Data Included) – this flag indicates that extension data is present in authData. This means that specific extensions were used during the authentication process, and the corresponding data of these extensions is included in the authentication data. counter is a 32-bit number that stores the number of times the authenticator has used these credentials. With each authorization, this counter is increased by one. This number must be saved for each authorization and checked to ensure that the number of authorizations in this field is greater than the number stored in the database.

Attested credential data:

AAGUID (Authenticator Attestation GUID) is a unique identifier for the authenticator model that helps determine the type of authentication device.
Credential ID – a unique credential identifier created by the authenticator and used to identify the account to which it belongs.
Credential Public Key – the public credential key created by the authenticator. This key will be used to authenticate the user during login attempts.

Autocomplete

To improve the user experience during authorization, you can also use autocomplete. Input and textarea support username values for the autocomplete attribute, with the value webauthn. If the user interacts with the input / textarea with autocomplete=”username webauthn” then the browser will return the user’s username at the onChange event, for which we should get the credentialId and pass it to the allowCredentials array.

Iframe

The Webauthn standard partially supports work in iframes; to do this, you need to pass the value publickey-credentials-get to the allow attribute for authorization via the iframe. If the iframe is loaded from a top-level context other than the domain (the domain in the browser’s bar), two additional fields topOrigin and crossOrigin will be sent to clientDataJSON. topOrigin is the domain from the address bar, and crossOrigin is a boolean flag indicating whether the request was cross-domain.

Extensions

While reading the article, you probably noticed a field/byte array called extensions. You can say this is a list of additional authenticator settings, and the full list of extensions can be found here.

CBOR

CBOR (Concise Binary Object Representation) is a data representation format that is structurally similar to JSON, but optimized for a more compact binary representation.

Conclusion

In conclusion, WebAuthn is revolutionizing digital authentication by offering a secure, user-friendly solution that transcends the limitations of traditional passwords. Throughout this article, various explanation formats, such as diagrams and real-world examples, were used to clarify the sophisticated technology behind WebAuthn, making it accessible to a broader audience.

Looking forward, the evolution of WebAuthn will be influenced by emerging technologies and cybersecurity trends. Embracing these changes and employing innovative educational techniques will be crucial for fostering understanding and adoption. As WebAuthn continues to develop, it promises to enhance security and user experience, positioning itself as an essential component of future cybersecurity strategies.