WebAuthn Public Key Credential / User-Agent Hints

WebAuthn and passkeys are getting strong momentum and more and more adoption. Also, from a technical point of view, the WebAuthn standard is quickly evolving. WebAuthn public key credentials hints (also called User-agent Hints) are the latest addition to the Web Authentication API, aiming to enhance the way developers implement passkey authentication in their applications.

In this article, we'll answer the following questions?

• What are WebAuth Public Key Credential Hints?
• Why do you need WebAuthn Public Key Credential Hints?
• How do WebAuthn Public Key Credential Hints work?
• What are the limitations and recommended cases of WebAuthn Public Key Credential Hints for your projects?

Let’s start by looking at the motivation first.

Nowadays, there are different places where you can create and store a passkey:

• Third-party password manager (e.g. 1Password, Dashlane, Bitwarden, KeePassXC)
• Google Password Manager / Chrome Profile
• iCloud Keychain / Apple Passwords
• Windows Hello
• Another smartphone (iOS, Android) or tablet (iPadOS, Android)
• Hardware security key (e.g. YubiKey)

For the user, this can offer flexibility and freedom of choice. However, some applications and scenarios require to restrict some of these options, e.g. if you want to only allow hardware security keys due to increased security requirements.

To influence that passkey creation and storage, we had the authenticatorAttachment property.

Subscribe to our Passkeys Substack for the latest news.

Subscribe

The authenticatorAttachment allows relying parties to restrict where the passkey can be created on.

platform indicates an authenticator that is built into the device running WebAuthn. WebAuthn communicates with it using transport methods specific to that platform, such as platform-specific APIs. A public key credential linked to a platform authenticator is called a platform credentials. From the list above, the following credential managers / locations could store platform credentials:

• Third-party password manager (e.g. 1Password, Dashlane, Bitwarden, KeePassXC)
• Google Password Manager / Chrome Profile
• iCloud Keychain / Apple Passwords
• Windows Hello

Windows 11 and Chrome:

macOS 15 (Sequoia) and Chrome:

When clicking on Cancel, the following modal appears:

macOS 15 (Sequoia) and Safari:

cross-platform indicates an authenticator that is external to the device running WebAuthn (roaming authenticator) because it can be used across multiple devices. WebAuthn interacts with it using cross-platform transport protocols like Bluetooth or NFC. A public key credential associated with a roaming authenticator is called a roaming credential. From the list above, the following credential managers / locations could store cross-platform credentials:

• Another smartphone (iOS, Android) or tablet (iPadOS, Android)
• Hardware security key (e.g. YubiKey)

Windows 11 and Chrome:

macOS 15 (Sequoia) and Chrome:

macOS 15 (Sequoia) and Safari:

Not specified indicates that either a platform authenticator or a cross-platform authenticator can be used. Here, the user can choose where they would like to store the passkeys.

Windows 11 and Chrome:

macOS 15 (Sequoia) and Chrome:

macOS 15 (Sequoia) and Safari:

When clicking on Cancel, the following modal appears:

authenticatorAttachment was used for quite some time. However, it was also inflexible in regard to new developments like Cross-Device Authentication (via QR codes and Bluetooth). Here, a passkey is stored also e.g. in Google Password Manager (platform credential) but triggered with cross-platform by the relying party. Besides that, the control of a relying party to influence the kind of passkey that should be used in a login (not register) ceremony could only be done by modifying the transports value of a credential.

That’s where WebAuthn Public Key Credential Hints come into play.

Become part of our Passkeys Community for updates & support.

Join

WebAuthn public key credential hints are a new parameter introduced in the Web Authentication API (officially in WebAuthn Level 3). They provide guidance to browsers about the type of authenticator a user is likely to use during the authentication process. This helps in delivering a more streamlined and intuitive user experience by focusing the browser's UI on the most relevant options.

The Three Types of Hints

The hints come in three types:

1. security-key: Indicates that the user is expected to use a hardware security key (e.g. YubiKey).
2. client-device: Suggests that the user will use a platform authenticator attached to the client device ( like Touch ID on macOS, Face ID on iOS or Windows Hello on Windows).
3. hybrid: Implies that the user might use a smartphone or table for cross-device authentication via QR code and Bluetooth.

These hints are not strict requirements from the relying party but serve as guidance to enhance the user experience as hints to the browser.

In the following, you see screenshots for macOS Sequoia (Edge + Chrome) and Windows 10 (Chrome) with authenticatorAttachment not specified and WebAuthn User-agent Hint set to security-key.

Here, we see another limitation, that the security-key hint is not respected on Windows 10, at least not directly. The flow is basically the same as for the client-device hint.

When clicking on Cancel, the following modal appears:

In the following, you see screenshots for macOS Sequoia (Edge + Chrome) and Windows 10 (Chrome) with authenticatorAttachment not specified and WebAuthn User-agent Hint set to client-device.

When clicking on Cancel, the following modal appears:

When clicking on Cancel, the following modal appears:

When clicking on Cancel, the following modal appears:

In the following, you see screenshots for macOS Sequoia (Edge + Chrome) and Windows 10 (Chrome) with authenticatorAttachment not specified and WebAuthn User-agent Hint set to hybrid.

With the introduction of hints, developers can now provide an array of preferences in order of decreasing priority, offering more flexibility.

The code snippet below tells the browser that the user is likely to authenticate using a hardware security key, focusing the UI accordingly.

For compatibility with older user agents, when this hint is used in PublicKeyCredentialCreationOptions, the authenticatorAttachment should be set to cross-platform.

const credential = await navigator.credentials.create({
  publicKey: {
    challenge: /* your challenge here */,
    hints: ['security-key'],
    authenticatorSelection: {
      authenticatorAttachment: 'cross-platform'
    }
  }
});

The security hint is particularly valuable in high-assurance cases where the website / relying party only wants to allow hardware security keys and pushes the user in this direction.

In this example, the hint suggests that the user might use the current device’s built-in platform authenticator.

For compatibility with older user agents, when this hint is used in PublicKeyCredentialCreationOptions, the authenticatorAttachment should be set to platform.

const credential = await navigator.credentials.create({
  publicKey: {
    challenge: /* your challenge here */,
    residentKey: true,
    hints: ['client-device'],
    authenticatorSelection: {
      authenticatorAttachment: 'platform'
    }
  }
});

Setting the client-device hint is beneficial if there are multiple passkeys associated with a user account and some of them might be available on the device logging in, whereas others are stored on different devices. If the system ( passkey intelligence) detects that the user trying to log in has with high probability a local passkey available, then this hint can be set in the PublicKeyCredentialRequestOptions saving the user one click to select the right passkey.

In this example, the hint suggests that the user might use a smartphone or a similar device for authentication.

For compatibility with older user agents, when this hint is used in PublicKeyCredentialCreationOptions, the authenticatorAttachment should be set to cross-platform.

const credential = await navigator.credentials.create({
  publicKey: {
    challenge: /* your challenge here */,
    residentKey: true,
    hints: ['hybrid'],
    authenticatorSelection: {
      authenticatorAttachment: 'cross-platform'
    }
  }
});

The hybrid hint can be helpful if the user has multiple keys and the system (passkey intelligence) detects that on the current device, there is probably no local passkey available. To improve the UX and save one click, you can set this WebAuthn User-agent hint and directly prompt the user for cross-device authentication (via QR code and Bluetooth). Moreover, if you try to build a mobile-first passkey system, then setting this hint makes a lot of sense.

To play around yourself with the different options, we recommend to take a look at the Passkeys Debugger.

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

Try for Free

It's crucial to understand how WebAuthn Public Key Credential Hints interact with other WebAuthn parameters like authenticatorAttachment and credential transports.

Firstly, it's important to note that these hints are not strict requirements. They do not bind the user-agent ( browser) but serve as guidance to provide the best experience by leveraging contextual information you have about the request. This means browsers may choose to consider the hints but are not obligated to follow them strictly.

Hints are provided as an array in order of decreasing preference. This order determines how the browser should prioritize them:

• First Hint Takes Precedence: If two hints are contradictory, the browser gives priority to the first one.
• Overlapping Hints: If a more specific hint might not be recognized by all browsers, you can include less specific ones afterward for broader compatibility.
• Duplicate Hints: If the same hint appears more than once, any subsequent appearances are ignored.

Example:

hints: ['security-key', 'hybrid', 'client-device']

In this array:

1. The browser first prioritizes security-key.
2. If not applicable, it considers hybrid.
3. Lastly, it looks at client-device (platform authenticators on the client device).

Hints can contradict information contained in authenticatorAttachment and credential transports. When this occurs, hints take precedence. This offers more flexibility compared to the previous strict usage of authenticatorAttachment, which limited the authenticator to either platform or cross-platform.

Example with Contradictory Parameters:

const credential = await navigator.credentials.create({
  publicKey: {
    challenge: /* your challenge here */,
    hints: ['hybrid'],
    authenticatorSelection: {
      authenticatorAttachment: 'platform' // Contradicts the hint
    }
  }
});

In this case:

• Hint: Suggests a preference for hybrid authenticators.
• authenticatorAttachment: Specifies platform, which normally limits authenticators to the client device.
• Outcome: The browser prioritizes the hint over authenticatorAttachment, focusing on hybrid options.

Currently, WebAuthn public key credential hints are only available in Chrome (since version 128). As of now, Edge and Safari have indicated plans to integrate this feature, while Firefox has not yet confirmed its release timeline.

It is important to remember that in Chrome, the authenticatorAttachment parameter continues to be respected for now. This means that today the authenticatorAttachment is the decisive factor, no matter which hint is set. However, we expect that in future Chrome versions, the public key credential hints will be becoming the preferred and only approach.

Even though the latest Chrome version support WebAuthn User-agent Hints, these hints are not respected by Windows 11 and Windows Hello / Windows Security. The underlying reason is that the UI is controlled by the operating system (Windows Hello / Windows Security) itself.

Moreover, a passkey which is stored in Google Password Manager and synced to Windows 11, the WebAuthn User-agent Hints are not respected, as the final local authentication on Windows 11 happens with Windows Hello / Windows Security. With the upcoming sync of passkeys on Windows 11 via Microsoft accounts, we also expect improvements for Windows 11 and WebAuthn User-agent Hints.

On Windows 10, WebAuthn User-agent Hints are respected though, as the WebAuthn UI is handled by Chrome and not by Windows Hello / Windows Security. However during our tests, we didn't see an effect for security-key. When this hint was set, the flow looked liked the one for client-device.

WebAuthn public key credential (user-agent) hints bring a range of benefits to both developers and users. The feature is still new and not rolled out to all browsers and operating systems yet (as of October 2024).

It’s important to be aware of the current limitations that especially come with Windows 11. In Windows 11, the passkey UI is handled by Windows Hello (Windows Hello security modal) and this currently rules over Chrome’s / Edge’s support for WebAuthn User-agent hints. This also applies to passkeys being synced from Google Password Manager to Windows (here, hints also have no effect yet).

This means WebAuthn public key credential hints really work only on macOS and Windows 10 (from the major desktop operating systems).

Moreover, as of October 2024, even if Chrome / Edge is used on these operating systems, if the authenticatorAttachment is set, then this also rules over the WebAuthn User-agent hints (as stated by Google).

From a use case perspective, we see the following recommended use cases to get the most value of this new feature.

When building your backend and passkey intelligence, try to include the right usage of public key credential hints to facilitate the login and save the user of unnecessary clicks. For example, if your system detects that a user logs in on a device where probably a local passkey is available, use the client-device hint.

If the user accesses the website from a new device and your passkey intelligence knows that a passkey might be available at a mobile device of the user, set the hint to hybrid, so that the user can quickly scan the QR code and make use of the hybrid passkey.

The main goal here is to provide a more seamless and intuitive user experience. By guiding browsers on which authenticators are likely to be used, developers can reduce user confusion and friction during the login process. Instead of users being overwhelmed with unnecessary authentication options, hints allow browsers to focus on the most relevant choices, which leads to a faster, more straightforward experience.

High-assurance enterprises or governmental organizations that have standardized on hardware security keys for user authentication will find passkey credential hints particularly useful. By using the security-key hint, they can ensure that browsers prominently display the hardware security key option.

This is especially useful for large organizations where employees have been issued hardware security keys and where other authentication methods (such as platform authenticators) are not permitted. The security-key hint enables enterprises to lock down their authentication flows without limiting their flexibility for future improvements.

The hybrid hint shines in scenarios where cross-device authentication and thus a mobile-first approach is desired or when users frequently move between devices or platforms.

An example of this use case would be a consumer-facing app that anticipates most of its users will use their smartphones for authentication, either through biometric methods or web-based authenticator apps (mobile-first passkeys). By specifying hybrid as a hint, developers ensure that the browser's UI encourages smartphone use, improving convenience and accessibility.

WebAuthn public key credential hints offer a flexible way to enhance the user experience during passkey authentication. Let’s revisit the questions from the introduction with the insights we've gathered:

1. What are WebAuthn Public Key Credential Hints?

   They are optional suggestions provided by the website / app to guide clients on the most likely authentication method a user will use – whether it's a hardware security key, platform authenticator, or a hybrid solution like cross-device authentication.

2. Why do you need WebAuthn Public Key Credential Hints?

   They streamline the authentication process by narrowing down the options presented to users, reducing unnecessary friction / clicks and improving the overall experience.

3. How do WebAuthn Public Key Credential Hints work?

   Developers specify hints such as security-key, client-device, or hybrid based on the context, allowing browsers to prioritize the relevant authentication method for the user. While these hints aren't strict requirements, they help optimize the UI flow during authentication.

4. What are the limitations and recommended use cases?

   Currently, full support for these hints is limited to Chrome and Edge, with other browsers and operating systems like Windows 11 showing varying levels of compatibility. The most effective use cases include improving login UX, enforcing hardware security key usage in high-security environments, and enabling cross-device authentication in mobile-first applications.

In conclusion, WebAuthn Public Key Credential Hints allow developers to create more intuitive, user-friendly authentication processes by guiding browsers to the most appropriate options for each user scenario. While still evolving, this feature can significantly enhance both security and user experience in passkey implementations.