WebAuthn Conditional UI (Passkeys Autofill) Technical Explanation

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.

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 autofilled 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.

Ben Gould

Head of Engineering

I’ve built hundreds of integrations in my time, including quite a few with identity providers and I’ve never been so impressed with a developer experience as I have been with Corbado.

10,000+ devs trust Corbado & make the Internet safer with passkeys. Got questions? We’ve written 150+ blog posts on passkeys.

Join Passkeys Community

• 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 frontend 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 browsers 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.

Subscribe to our Passkeys Substack for the latest news, insights and strategies.

Subscribe

• 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 UIs 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.
• Password Manager Disable Autocomplete: Some modern password managers and their browser extensions modify the websites 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.

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 in two phases. During the page load phase, Conditional UI logic happens in the background, while in the user operation phase, the user has to actively do something.

1. Conditional UI Availability Check: The client (browser) calls the isConditionalMediationAvailable() function to detect if the current browser / device combination supports Conditional UI. Only if the response is true, the process continues, otherwise the Conditional UI process is aborted.
2. Call the Conditional UI Endpoint: Next, the client calls the servers 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 PublicKeyCredentialRequestOptions and the mediation property 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, 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 accounts public key in the database. If the verification success, 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.

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 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 browsers LocalStorage) to refine the list of credentials showcased to users during autofill.

Become part of our Passkeys Community for updates and support.

Join

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 here 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 avoid triggering any user-visible errors in scenarios where Conditional UI isn't supported. To address this, its recommend to use the isConditionalMediationAvailable() method and check for the technical availability of Conditional UI ( see below for more details).
• HTML Input Field Required: For Conditional UI to work, you need to have an HTML input field in 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 for a passkey in the autofill menu) should be disregarded in this setup.

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, its 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).

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 with you practical tips that helped during the implementation of Conditional UI.

Want to experiment with passkey flows? Try our Passkeys Debugger.

Try for Free

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"/>
 
<script>
    async function passkeyLogin() {
        try {
            // retrieve the request options (incl. the challenge) from the WebAuthn server
            let options = await WebAuthnClient.getPublicKeyRequestOptions();
 
            const credential = await navigator.credentials.get({
                publicKey: options.publicKeyCredentialRequestOptions,
                mediation: "conditional",
            });
 
            const userData = await WebAuthnClient.sendSignedChallenge(credential);
            window.location.href = '/logged-in';
        } catch (error) {
            console.log(error);
        }
    };
 
    passkeyLogin();
</script>
 
</body>
</html>

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",
        });
        /*
        ...
        */
    }
}

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">

For further details, we recommend to read this blog post which provides more details on autofill / autocomplete tokens for passkeys and passwords.

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"
});

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 here 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"/>
 
<script>
    async function passkeyLogin() {
        try {
            // retrieve the request options (incl. the challenge) from the WebAuthn server
            let options = await WebAuthnClient.getPublicKeyRequestOptions();
 
            const credential = await navigator.credentials.get({
                publicKey: options.publicKeyCredentialRequestOptions,
                mediation: "conditional",
            });
 
            const userData = await WebAuthnClient.sendSignedChallenge(credential);
            window.location.href = '/logged-in';
        } catch (error) {
            console.log(error);
        }
    };
 
    passkeyLogin();
</script>
 
</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.

Want to find out how many people can use passkeys?

View Adoption Data

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.

In general, we found almost no documentation on how to implement Conditional UI support for iOS apps. During our research, however, we discovered two ways of adding Conditional UI support to an iOS app, as the user experience will also differ.

Type A: Overlay / Popup over Almost Entire Screen

The first type A shows an overlay / popup that spans almost over the entire screen. Here, you'll see all available passkeys for this relying party. A prominent example that implements Conditional UI this way is KAYAK. The overlay / popup emerges automatically, when the user opens the right screen.

Type B: Keyboard Autofill

The second type B displays a suitable passkey in the autofill section of the keyboard (where also passwords are suggested for autofill). Clicking on the suggest value will perform the Face ID authentication and lets you log in. In the current iOS app version of the Corbado developer panel, we have implemented it this way (see the Sign in with passkey for <relying party ID> message together with the WebAuthn username). To show up, the user needs to tap into the input field:

This passkey autofill feature in the keyboard section might have issues when the iOS is freshly installed as apparently some kind of caching happens in the background that looks up all the available passkeys for this relying party.

Clicking on the key icon on the right of the suggested passkey leads to the known site for choosing passwords / passkeys in iOS:

Please note that we have not found official documentation, and our insights are based on our experiences and hypotheses rather than concrete proof of the proper implementation.

In Android, the story for Conditional is a bit clearer, as there is only one type for Conditional UI / passkey autofill that leverages the Android Credential Manager API (see the documentation here).

Opening the page where Conditional UI is implemented shows the following screen, where you'll find different ways to sign in:

Clicking on More saved sign-ins provides more options to choose for the sign-in (including cross-device authentication and the selection of a different passkey sync platform, e.g. Samsung Pass or 1Password):

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.

Want to try passkeys yourself? Check our Passkeys Demo.

Try Passkeys

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. This article has helped to understand how to correctly implement Conditional UI, a great help in the transition process, and which aspects to pay special attention to.