WebAuthn Conditional UI: Technical Explanation and Implementation

With the rapid adoption of passkeys (and the underlying WebAuthn protocol), authentication has become more secure and user-friendly for many users. One of the standout advancements of passkeys has been the integration of Conditional UI, often referred to as "passkey autofill" or Conditional Mediation (in the following, we stay with the term Conditional UI).

Despite its recent introduction and ongoing adoption by browsers, there’s a noticeable gap in technical documentation and implementation advice for Conditional UI. This article aims to bridge that gap by explaining what Conditional UI is, how it works, and how to tackle common challenges during its implementation.

What Is Conditional UI?

Conditional UI represents a new mode for passkeys/WebAuthn login processes. It selectively displays passkeys in a user interface (UI) only when a user has a discoverable credential (resident key), which is a type of passkey registered with the relying party (the online service) stored in their authenticator of a device (e.g., laptop, smartphone). The passkeys are displayed in a selection dropdown that is mixed up with auto-filled passwords, providing a seamless transition between traditional password systems and advanced passkey authentication, as users see both in the same context. This intelligent approach ensures that users aren't overwhelmed with unnecessary options and can navigate the login process more seamlessly.

The foundation of Conditional UI is built on three main pillars:

1. Respect user privacy: Ensuring user privacy by preventing disclosure of available credentials or lack of user consent to reveal these credentials.
2. Great user experience even if no passkey exists: Empowering relying parties to implement WebAuthn opportunistically, ensuring user experience remains good even if passkeys are not available.
3. Smooth transition from passwords to passkeys: Combining passkeys with password-based authentication to smooth the transition towards passwordless authentication methods, capitalizing on users' familiar UX paradigms.

Conditional UI Benefits and Drawbacks

Benefits

• Streamlined authentication: The process is more streamlined and efficient, removing the complexities often associated with multiple authentication methods.
• Reduction in user errors: By presenting only relevant options, users are less likely to make mistakes during the authentication process.
• Enhanced user satisfaction: Removing unnecessary steps means users can log in faster and more effortlessly, leading to improved user satisfaction.
• Simple frontend integration: One of the standout features of Conditional UI is its ease of integration. Developers can seamlessly incorporate it into the front end with a few lines of code (see below).
• Passwordless and usernameless login: One of the huge benefits is that Conditional UI promotes not only passwordless authentication but also a usernameless or accountless experience. Users are spared the mental load of recalling their specific email address or user handle from sign-up. Instead, they can rely on the browser’s suggestions, which include the email address/user handle paired with the appropriate passkey in the autofill menu.
• Solving the bootstrapping dilemma: Transitioning from traditional username-password systems to passkeys can be daunting. Conditional UI addresses this transition challenge. Websites can initiate a passkey / WebAuthn call alongside a conventional password prompt without fretting over potential modal dialog errors if a device lacks the needed credentials.

Drawbacks

• Learning curve for developers: Conditional UI introduces a new paradigm, which means there's a learning curve involved for developers unfamiliar with its intricacies.
• Device/browser dependency: Conditional UI’s success hinges on the user's device or browser compatibility. Given that not all browsers or devices support it currently, this can limit its application. To test the passkey-readiness of a website, one can make use of tools like the passkeys analyzer.
• No conditional passkey register: There’s no support for using Conditional UI in the account/passkey creation process. That means you need to create passkeys the regular way, either at the account creation stage by providing some dedicated passkey creation page or in the account settings. However, there's an ongoing discourse about the potential inclusion of Conditional UI for sign-ups as well.
• Password manager disable autocomplete: Some modern password managers and their browser extensions modify the website’s DOM and disable or overwrite the autocomplete tag in input fields in favor of their own autocomplete features. This can lead to an inconsistent and unsatisfying user experience. As standards for Conditional UI are relatively new, we hope that things improve so that, e.g., not two autofill menus are overlaid or the desired one is not shown at all.

How Does Conditional UI Work?

In the following, we provide a step-by-step breakdown of the single steps of an entire Conditional UI flow:

In general, the Conditional UI process flow can be partitioned into two phases. During the page load phase, conditional UI logic happens in the background, while in the user operation phase, the user has to do something actively.

1. Conditional UI availability checks: The client (browser) calls the isConditionalMediationAvailable() function to detect if the current browser/device combination supports Conditional UI.
   Only if the response is true does the process continue; otherwise, the Conditional UI process is aborted.
2. Call the conditional UI endpoint: Next, the client calls the server Conditional UI endpoint in order to retrieve the PublicKeyCredentialRequestOptions.
3. Receive PublicKeyCredentialRequestOptions: The server returns the PublicKeyCredentialRequestOptions which contain the challenge and more WebAuthn server options (e.g., allowCredentials, extensions, userVerification).
4. Start the local authentication: By calling credentials.get() with the received PublicKeyCredentialOptions and the mediation property is set to be “conditional, the process for the local authentication on the device starts.
5. Show autofill selection: The autofill menu for passkeys pops up. The specific styling is dependent on the browser and device (e.g., some require the user to place the cursor in the input field, and some automatically display the menu on page load; see below).
6. Local user authentication: The user selects the passkey from the autofill menu that they want to use and authenticate via the authentication dialog of their device (e.g., via Face ID, Touch ID, Windows Hello).
7. Send authenticator response to server: If the local user authentication was successful, the authenticator response is sent back to the server.
8. User is logged in and redirected: Once the server receives the authenticator response, it validates the signature against the corresponding user account’s public key in the database. If the verification is successful, the user is granted access, logged in, and redirected to the logged-in page.

By following this process flow, Conditional UI offers a seamless and user-friendly authentication experience.

Technical Requirements for Conditional UI

General

To get Conditional UI working, some general aspects need to be considered:

• Credential specifications: Conditional UI is specifically designed to operate only with resident keys/discoverable credentials. The reason behind this is that authenticators do not store user-specific data (e.g., name, display name) for non-resident keys/non-discoverable credentials. As a result, using the latter for passkey autofill is not possible.
• Credential filtering: The allowCredentials feature remains supported, facilitating websites that are already aware of the user's identity (for instance, if a username was sent in the initial mediation call because it might be stored in the browser’s LocalStorage) to refine the list of credentials showcased to users during autofill.

Client-Side

To get Conditional UI working on the client side, the following requirements must be fulfilled:

• Compatible browser: Ensure that the user uses a modern browser that supports Conditional UI (see State of Passkeys for the latest browser coverage).
• Enabled JavaScript: JavaScript must be enabled to facilitate Conditional UI operations.
• Test conditional UI availability: The relying party (the server side) should have the certainty that Conditional UI is available on the client side when it receives the WebAuthn mediation call to avoid triggering any user-visible errors in scenarios where Conditional UI isn't supported. To address this, it’s recommended to use the isConditionalMediationAvailable() method and check for the technical availability of Conditional UI.
• HTML input field required: For Conditional UI to work, you need to have an HTML input field on your web page. If you do not have one, you need to provide support for the regular passkey/WebAuthn login process that is triggered with a user interaction, like a button click.
• Remove timeout protocols: Timeout parameters (e.g., the user is taking a very long time to decide on a passkey in the autofill menu) should be disregarded in this setup.

Server-Side

To get Conditional UI working, some requirements on the server side must be fulfilled as well:

• Running WebAuthn server: As we are still in the context of passkeys / WebAuthn, it’s required to have a WebAuthn server running that manages the authentication procedures.
• Provide mediation start endpoint: Compared to regular WebAuthn login endpoints, it’s useful to provide another endpoint that has similar functionality but can deal with an optional user handle (e.g., email address, phone number, username).

Practical Coding Tips

Since the official rollout of Conditional UI in late 2022 and earlier beta versions, we’ve been testing and working extensively with it. In the following, we want to share practical tips that helped during the implementation of Conditional UI with you.

A useful tool to debug WebAuthn registration and authentication responses is the passkeys debugger.

Full Conditional UI Example

A full, minimalistic code example for a Conditional UI method would look like this:

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Conditional UI</title>
</head>
<body>

<input type="text" id="username" autoComplete="username webauthn" />
<button onclick="passkeyLogin()">Login via passkey</button>

</body>
</html>

Browser Compatibility Check

Implement Conditional UI detection that ensures that Conditional UI is only employed when the current device/browser combination supports it. This should work without presenting user-visible errors in the absence of Conditional UI support. Incorporating the isConditionalMediationAvailable() method within the user interface addresses this concern. If Conditional UI support is given, the Conditional UI login process can be started.

// source: https://developer.mozilla.org/en-US/docs/Web/API/PublicKeyCredential/isConditionalMediationAvailable#examples

// Availability of `window.PublicKeyCredential` means WebAuthn is usable.
if (
  window.PublicKeyCredential &&
  PublicKeyCredential.isConditionalMediationAvailable
) {
  // Check if conditional mediation is available.
  const isCMA = await PublicKeyCredential.isConditionalMediationAvailable();
  if (isCMA) {
    // Call WebAuthn authentication start endpoint

    let options = await WebAuthnClient.getPublicKeyRequestOptions();

    const credential = await navigator.credentials.get({
      publicKey: options.publicKeyCredentialRequestOptions,
      mediation: "conditional",
    });
    /*
    ...
    */
  }
}

WebAuthn Autocomplete Token in Input Fields

The input field should receive a “webauthn” HTML autofill token. This signals the client to populate passkeys to the ongoing request. Besides passkeys, other autofill values might be showcased as well. These autofill tokens can be paired with other existing tokens, e.g.:

• autocomplete="username webauthn": Besides displaying passkeys, this also suggests username autofill.
• autocomplete="current-password webauthn": Besides displaying passkeys, this further prompts for password autofill.

<label for="name">Username:</label>
<input type="text" name="name" autocomplete="username webauthn">
<label for="password">Password:</label>
<input type="password" name="password" autocomplete="current-password webauthn">

Mediation Property in WebAuthn API Get Call

To retrieve available passkeys after having received the PublicKeyCredentialRequestOptions object, the navigator.credentials.get() function should be called (which serves both passkeys and passwords). The PublicKeyCredentialRequestOptions object needs to have the mediation parameter set to “conditional” to activate Conditional UI on the client.

const credential = await navigator.credentials.get({
  publicKey: options.publicKeyCredentialRequestOptions,
  mediation: "conditional"
});

Cancellation of Conditional UI Flow

If there's no available passkey, or the user neglects the suggested passkeys and enters their email, the Conditional UI flow is stopped. This underscores the importance of always supporting the standard passkey / WebAuthn login via a modal as well.

A critical point to emphasize here is the potential need to halt an ongoing Conditional UI request. Contrary to modal experiences, autofill dropdowns lack a cancellation button. As per WebAuthn's design, only a single active credential request should be in progress at any given moment. The WebAuthn standard suggests utilizing an AbortController to cancel a WebAuthn process, applicable to both regular and Conditional UI login processes (see WebAuthn's Docs for details).

The Conditional UI login process gets activated as soon as a user lands on the page. The initial task should be to create a globally-scoped AbortController object. This will act as a signal for your client to terminate the autofill request, especially if the user decides to do the regular passkey login process. Reassure that the AbortController can be invoked by other functions and is reset if the Conditional UI process has to restart. Employ the signal property within the navigator.credentials.get() call, incorporating your AbortController signal as its value. This signals to the passkey / WebAuthn function that the request must be halted if the signal gets aborted. Remember to set up a fresh AbortController each time you trigger Conditional UI. Using an already-aborted AbortController will lead to an instant cancellation of the passkey / WebAuthn function. The remaining steps align with a regular passkey login process. In the following, you see a code example of the mentioned steps:

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Conditional UI</title>
</head>
<body>

<input type="text" id="username" autoComplete="username webauthn" />
<button onclick="passkeyLogin()">Login via passkey</button>



</body>
</html>

In the absence of Conditional UI support, direct users towards the regular passkey login process. Offering this path is important for users relying on hardware security keys (e.g., YubiKeys) or those compelled to use non-resident keys / non-discoverable credentials due to authenticator constraints.

Conditional UI in Native Apps

When you develop a native app, e.g., for iOS or Android, Conditional UI works as well. It doesn’t matter if you implement it natively in Flutter, Kotlin, or Swift or if you decide to go with Chrome Custom Tabs CCT or SFSafariViewController or SFAuthenticationSession / ASWebAuthenticationSession. Both approaches support Conditional UI.

Conditional UI Examples in Different Devices/Browser

To illustrate how Conditional UI looks like for the end user, we added several screenshots of a Conditional UI autofill menu using https://passkeys.eu.

Conditional UI in Windows 11 (22H2) + Chrome 118

Conditional UI in macOS Ventura (13.5.1) + Chrome 118

Conditional UI in macOS Ventura (13.5.1) + Safari 16.6

Conditional UI in Android 13 + Chrome 118

Conditional UI in iOS 17.1 + Safari 17.1

Conclusion

Passkeys, with its Conditional UI/passkey autofill capability, are the new way to authenticate online. As we transition to an era where passwords are more and more replaced by passkeys, the need for robust and user-friendly transition mechanisms is undeniable. We hope this article has helped you to understand how to correctly implement Conditional UI, handle the transition process, and which aspects to pay special attention to.