Client Hints for Workforce Deployments

The benefit of WebAuthn client hints

WebAuthn client hints allow a relying party (RP) to express a preferred authenticator experience during passkey registration (create()) or authentication (get()) ceremonies.

Client hints are provided through the hints parameter in the WebAuthn request options to help guide the browser or operating system toward a preferred credential manager or authenticator experience.

Examples include:

• security-key — indicates a preference for security keys or roaming authenticators
• client-device — indicates a preference for platform authenticators available on the current device
• hybrid — indicates a preference for cross-device authentication flows

Client hints are advisory. Browsers and operating systems determine whether and how hints influence the user experience.

When available, client hints guide the end user to the preferred selection. This can make it easier to select the passkey option and reduce the number of choices that a user needs to make.

WebAuthn client hints and passkeys

Client hints are an optional WebAuthn feature intended to improve user experience and authenticator selection guidance. They are not required in order to support passkeys.

Passkey implementations should continue to function correctly even when client hints are unsupported, ignored, or only partially honored by the client platform.

Relying parties should design authentication and registration flows that work with both:

• Hint-aware clients
• Clients that use their default authenticator selection behavior

How browsers and operating systems use client hints

Support for client hints varies across browsers, operating systems, and WebAuthn implementations.

In general:

• Some platforms use client hints to influence authenticator prioritization or presentation order.
• Some platforms expose client hints only in limited scenarios.
• Some clients may ignore client hints entirely.

The WebAuthn specification does not require clients to honor client hints in a specific way. Platform behavior may evolve over time as implementations mature.

For current platform capability information, refer to:

• Client Hints
• Device Support

Considerations for enterprises deploying client hints

Enterprises should treat client hints as a user experience enhancement rather than a strict control mechanism. The default flow for FIDO is fairly simple and client hints can further simplify the user experience.

Recommended practices include:

• Ensure registration and authentication flows function correctly with and without client hints.
• Provide clear user guidance when multiple authenticator types are supported.
• Test flows across the organization's supported browser and operating system combinations.
• Consider fallback experiences for environments where client hints have limited effect.
• Validate behavior for both registration (navigator.credentials.create()) and authentication (navigator.credentials.get()).

Since authenticator selection behavior may differ between platforms, testing representative enterprise environments is recommended.

The difference between authenticatorSelection and client hints

Client hints are a newer and preferred mechanism for indicating the desired user experience to the client. When setting client hints, set authenticatorSelection.authenticatorAttachment to a complementary value, as described in WebAuthn, to maintain compatibility with older user agents.

The authenticatorSelection object is used during registration to express requirements or preferences related to authenticator capabilities, such as:

• Platform vs roaming authenticators
• Resident/discoverable credentials
• User verification behavior

The client hints parameter is intended to influence user experience and authenticator presentation behavior. Client hints do not override platform security policies or authenticator availability.

What happens if a client ignores a hint

If a browser or operating system does not honor a client hint, the client typically falls back to its default authenticator selection behavior.

Common default behaviors may include:

• Prioritizing platform authenticators
• Displaying recently used credential managers
• Presenting locally available passkeys first

Relying parties should ensure the resulting flow remains clear and functional even when hints are not applied.

Client hints and enterprise authenticator policy enforcement

Client hints are advisory and should not be used as an enforcement mechanism.

Organizations that require stronger policy enforcement should consider:

• Attestation policies
• Enterprise authenticator management
• Device management controls
• Credential binding requirements
• Server-side policy validation

Hints are best used to improve usability and guide users toward preferred authentication experiences.

How client hints interact with hybrid authentication

Hybrid client hints are intended to encourage cross-device authentication experiences, such as using a mobile device to authenticate on another device.

Support for hybrid experiences varies by platform and browser implementation. In some environments:

• Hybrid flows may appear automatically.
• QR code flows may be offered.
• The platform may prioritize local authenticators instead.

Relying parties should validate hybrid behavior within their supported deployment environments.

How enterprises should handle environments with mixed platform support

Since client hints are an optional feature, they are not available in all deployments and behavior may vary. For this reason, it is important for enterprises to test all the environments their users may work in to ensure the flows work as expected.

Many enterprise environments include a combination of:

• Operating systems
• Browser versions
• Managed devices
• Authenticator types

Recommended approaches include:

• Design flows that degrade gracefully.
• Provide contextual user guidance.
• Support multiple authenticator options.
• Validate platform-specific behavior during roll-out testing.

Browser and platform behavior should be reviewed periodically as support evolves over time.

Relying parties and client capabilities detection

WebAuthn Level 3 introduces capability detection APIs, such as PublicKeyCredential.getClientCapabilities(). These APIs may help relying parties understand whether a client supports certain WebAuthn capabilities before initiating a flow. Capability detection can help tailor user experiences while still maintaining compatibility with clients that do not expose the API.

note

Implementation details and support may vary by platform.

How to implement client hints

For implementation guidance and examples, refer to:

• Client Hints
• Web Authentication: An API for accessing Public Key Credentials - Level 3

Example registration snippet:

navigator.credentials.create({
  publicKey: {
    challenge,
    rp,
    user,
    pubKeyCredParams,
    hints: ["client-device"],
  },
});

Example authentication snippet:

navigator.credentials.get({
  publicKey: {
    challenge,
    allowCredentials,
    hints: ["security-key"],
  },
});

This example highlights how hints might contradict other information contained in a call. In this case, allowCredentials might contain a different credential transport. When this occurs, the client hints should take precedence as per the WebAuthn specification. (Enterprises may want to include transport information in case legacy systems do not recognize newer hints capabilities.)