|
| 1 | +--- |
| 2 | +title: "Client Hints" |
| 3 | +description: "The WebAuthn Client Hints feature allows a Relying Party to request a more specific credential manager or passkey selection experience from the WebAuthn client." |
| 4 | +date: 2025-09-24T05:07:38.473Z |
| 5 | +type: docs |
| 6 | +layout: docs |
| 7 | +--- |
| 8 | + |
| 9 | +## Overview |
| 10 | + |
| 11 | +When creating a passkey, WebAuthn Clients display a credential manager selection screen asking users to choose where to store their new passkey. The selector typically defaults to local credential managers because they offer immediate availability and support for synced passkeys, the default credential type in unmanaged, consumer contexts. |
| 12 | + |
| 13 | +During a sign in flow, the WebAuthn client will do its best to help the user select a passkey which is immediately available, and fall back to an external authenticator selection screen. This typically shows an option for [FIDO Cross-Device Authentication](../reference/terms/#cross-device-authentication-cda) and security keys. In environments where only security keys are allowed, having additional options can confuse users and lead to unnecessary steps. |
| 14 | + |
| 15 | +The WebAuthn Client Hints feature allows a Relying Party to request a more predictable experience based on their requirements. It is important to note that this is only a hint, and is not used to enforce security policy. |
| 16 | + |
| 17 | +## Use Cases and Usage |
| 18 | + |
| 19 | +NOTE: Additional use cases will be added in the future. |
| 20 | + |
| 21 | +### Security Keys |
| 22 | + |
| 23 | +The primary use case for WebAuthn Client Hints is in workforce and high assurance consumer scenarios where creating passkeys on security keys is required by policy for all or a specific group of users. In these scenarios, if a user were to attempt to create a passkey on a different type of authenticator/credential manager (ex: using cross-device and saving to their personal credential manager on their phone), the Relying Party would reject the passkey, creating confusion for the user, and leaving them somewhat stranded. |
| 24 | + |
| 25 | +There are three primary scenarios which will be referenced throughout this page: |
| 26 | + |
| 27 | +1. Passkeys on security keys are required for all users in the organization |
| 28 | +2. Passkeys on security keys are required for a limited set of users in the organization (e.g. tied to a directory group) |
| 29 | +3. Passkeys on security keys are not required for any users but are encouraged |
| 30 | + |
| 31 | +#### Passkey Creation |
| 32 | + |
| 33 | +Below is a mapping of the scenarios from the beginning of this article and their solutions. |
| 34 | + |
| 35 | +| **SCENARIO** | **SOLUTION** | |
| 36 | +|---------------------------|--------------------------------------------------------------------------------| |
| 37 | +| **1** (required for all) | Use Client Hints with your existing enrollment experience | |
| 38 | +| **2** (required for some) | Use Client Hints with your existing enrollment experience | |
| 39 | +| **3** (required for none) | Use Client Hints with a dedicated button | |
| 40 | + |
| 41 | +##### Scenarios 1 & 2 |
| 42 | + |
| 43 | +In both scenarios 1 and 2, Client Hints is used to prefer the security key experience during passkey creation for all users. |
| 44 | + |
| 45 | +Simply adapt your existing passkey creation flow to use the hints parameter as shown in the sample code below: |
| 46 | + |
| 47 | +```html |
| 48 | +-- snip -- |
| 49 | + |
| 50 | +<button type="button" onclick="createPasskeyOnSecurityKey()">Create passkey</button> |
| 51 | + |
| 52 | +-- snip -- |
| 53 | + |
| 54 | +<script> |
| 55 | + async function createPasskeyOnSecurityKey() { |
| 56 | + const credential = await navigator.credentials.create({ |
| 57 | + publicKey: { |
| 58 | + challenge: "challenge-from-server", |
| 59 | + rp: { }, // omitted |
| 60 | + user: { }, // omitted |
| 61 | + pubKeyCredParams: [], // omitted |
| 62 | + timeout: 60000, |
| 63 | + hints: [ "security-key" ], // this is the WebAuthn Client Hints parameter |
| 64 | + authenticatorSelection: { |
| 65 | + residentKey: "required", |
| 66 | + userVerification: "preferred", |
| 67 | + authenticatorAttachment: "cross-platform" |
| 68 | + } |
| 69 | + } |
| 70 | + }); |
| 71 | + // omitted |
| 72 | + }; |
| 73 | +</script> |
| 74 | +``` |
| 75 | + |
| 76 | +{{< video src="hints-create-seckey.mp4" autoplay="true" loop="true" >}} |
| 77 | + |
| 78 | +##### Scenario 3 |
| 79 | + |
| 80 | +For scenario 3, it is recommended to use dedicated buttons for "This device" vs "Security Key". This can help give the user a more predictable experience based on their selection. |
| 81 | + |
| 82 | +Sample code: |
| 83 | + |
| 84 | +```html |
| 85 | +-- snip -- |
| 86 | + |
| 87 | +<h1>Create a passkey!</h1> |
| 88 | + |
| 89 | +<p>Would you like to create your passkey on this device or an external USB security key?</p> |
| 90 | + |
| 91 | +<button type="button" onclick="createPasskeyOnLocalDevice()">This device</button> |
| 92 | + |
| 93 | +<button type="button" onclick="createPasskeyOnSecurityKey()">USB Security Key</button> |
| 94 | + |
| 95 | +-- snip -- |
| 96 | + |
| 97 | +<script> |
| 98 | + async function createPasskeyOnSecurityKey() { |
| 99 | + const credential = await navigator.credentials.create({ |
| 100 | + publicKey: { |
| 101 | + challenge: "challenge-from-server", |
| 102 | + rp: { }, // omitted |
| 103 | + user: { }, // omitted |
| 104 | + pubKeyCredParams: [], // omitted |
| 105 | + timeout: 60000, |
| 106 | + hints: [ "security-key" ], |
| 107 | + authenticatorSelection: { |
| 108 | + residentKey: "required", |
| 109 | + userVerification: "preferred", |
| 110 | + authenticatorAttachment: "cross-platform" |
| 111 | + } |
| 112 | + } |
| 113 | + }); |
| 114 | + // omitted |
| 115 | + }; |
| 116 | +
|
| 117 | + async function createPasskeyOnLocalDevice() { |
| 118 | + const credential = await navigator.credentials.create({ |
| 119 | + publicKey: { |
| 120 | + challenge: "challenge-from-server", |
| 121 | + rp: { }, // omitted |
| 122 | + user: { }, // omitted |
| 123 | + pubKeyCredParams: [], // omitted |
| 124 | + timeout: 60000, |
| 125 | + hints: [ "client-device" ], |
| 126 | + authenticatorSelection: { |
| 127 | + residentKey: "required", |
| 128 | + userVerification: "preferred", |
| 129 | + authenticatorAttachment: "platform" |
| 130 | + } |
| 131 | + } |
| 132 | + }); |
| 133 | + // omitted |
| 134 | + }; |
| 135 | +</script> |
| 136 | +``` |
| 137 | + |
| 138 | +#### Passkey Authentication |
| 139 | + |
| 140 | +While Client Hints primarily targets passkey creation flows, it also supports specific authentication scenarios. Choose your approach based on your configuration and security requirements. Below is a mapping of the scenarios from the beginning of this article and their solutions. |
| 141 | + |
| 142 | +| **SCENARIO** | **SOLUTION** | |
| 143 | +|---------------------------|--------------------------------------------------------------------------------| |
| 144 | +| **1** (required for all) | Use Client Hints | |
| 145 | +| **2** (required for some) | Use identifier-first plus an allow list | |
| 146 | +| **3** (required for none) | Don't use Client Hints or an allow list; let the WebAuthn Client do its thing | |
| 147 | + |
| 148 | +##### Scenario 1 |
| 149 | + |
| 150 | +In scenario 1, Client Hints is used to prefer the security key experience for all users. |
| 151 | + |
| 152 | +Sample code for scenario 1: |
| 153 | + |
| 154 | +```html |
| 155 | +<!-- additional code omitted --> |
| 156 | + |
| 157 | +<button type="button" onclick="signIn()">Sign in with a passkey</button> |
| 158 | + |
| 159 | +<!-- additional code omitted --> |
| 160 | + |
| 161 | +<script> |
| 162 | + async function signIn() { |
| 163 | + const credential = await navigator.credentials.get({ |
| 164 | + publicKey: { |
| 165 | + challenge: "challenge-from-server", |
| 166 | + rpId: "", // omitted in example |
| 167 | + timeout: 60000, |
| 168 | + hints: [ "security-key" ] |
| 169 | + } |
| 170 | + }); |
| 171 | + // additional code omitted |
| 172 | + }; |
| 173 | +</script> |
| 174 | +``` |
| 175 | + |
| 176 | +##### Scenario 2 |
| 177 | + |
| 178 | +In scenario 2, an identifier-first flow is used where the user enters their username, and a request is made to the server for a list of credential IDs for the user. These are then passed in to the WebAuthn request (along with their transports) in the `allowCredentials` list. If only passkeys on security keys are included, the WebAuthn Client will show the security key experience. |
| 179 | + |
| 180 | +Sample code: |
| 181 | + |
| 182 | +```javascript |
| 183 | +// call this after the user has been identified |
| 184 | +// and the credential IDs have been looked up |
| 185 | + |
| 186 | +async function signIn() { |
| 187 | + const credential = await navigator.credentials.get({ |
| 188 | + publicKey: { |
| 189 | + challenge: "challenge-from-server", |
| 190 | + rpId: "", // omitted in example |
| 191 | + timeout: 60000, |
| 192 | + allowCredentials: [ |
| 193 | + // the passkeys created on security keys |
| 194 | + // that are linked to the user's account |
| 195 | + { |
| 196 | + "id": "qx30Jbh0IJFq4Y3i7r5DY7aECNDnlH4-lldmDeshvTVFZolxwIgIBQfnoxrJKe1z", |
| 197 | + "type": "public-key", |
| 198 | + "transports": [ "nfc", "usb" ] |
| 199 | + }, |
| 200 | + { |
| 201 | + "id": "3WiVDBng9vWlRX8Zkarc-4vpVNt8ysHFhHyYNldgf26n7eHJ4TN9AsBOr36Lsnl2", |
| 202 | + "type": "public-key", |
| 203 | + "transports": [ "usb" ] |
| 204 | + } |
| 205 | + ] |
| 206 | + } |
| 207 | + }); |
| 208 | + // additional code omitted |
| 209 | +}; |
| 210 | +``` |
| 211 | + |
| 212 | +##### Scenario 3 |
| 213 | + |
| 214 | +In scenario 3, there is no special configuration, allowing the WebAuthn Client to do what it believes is best based on available context that only it has. |
| 215 | + |
| 216 | +Sample code: |
| 217 | + |
| 218 | +```javascript |
| 219 | +async function signIn() { |
| 220 | + const credential = await navigator.credentials.get({ |
| 221 | + publicKey: { |
| 222 | + challenge: "challenge-from-server", |
| 223 | + rpId: "", // omitted in example |
| 224 | + timeout: 60000, |
| 225 | + } |
| 226 | + }); |
| 227 | + // additional code omitted |
| 228 | +}; |
| 229 | +``` |
| 230 | + |
| 231 | +## Client Hints vs Authenticator Attachment |
| 232 | + |
| 233 | +> Coming Soon |
| 234 | +
|
| 235 | +## Additional Information |
| 236 | + |
| 237 | +WebAuthn Client Hints support is rolling out across the ecosystem. Details about support WebAuthn Clients can be found in the [Device Support matrix](device-support#advanced). |
| 238 | + |
| 239 | +A presentation by Tim Cappalli at Authenticate 2024 which dives into a WebAuthn Client's selection logic: ["Peeling back the passkeys onion"](https://blog.timcappalli.me/p/preso-authn24-passkeysonion/). |
| 240 | + |
| 241 | +{{< button color="light" size="sm" icon="fas fa-circle-info" cue=false order="first" tooltip="Go to reference in the WebAuthn specification" href="https://www.w3.org/TR/webauthn-3/#enum-hints" >}}WebAuthn Spec Reference{{< /button >}} |
0 commit comments