|
| 1 | +--- |
| 2 | +title: "PublicKeyCredential: getClientCapabilities() static method" |
| 3 | +short-title: getClientCapabilities() |
| 4 | +slug: Web/API/PublicKeyCredential/getClientCapabilities_static |
| 5 | +page-type: web-api-static-method |
| 6 | +browser-compat: api.PublicKeyCredential.getClientCapabilities_static |
| 7 | +--- |
| 8 | + |
| 9 | +{{APIRef("Web Authentication API")}}{{securecontext_header}} |
| 10 | + |
| 11 | +The **`getClientCapabilities()`** static method of the {{domxref("PublicKeyCredential")}} interface returns a {{jsxref("Promise")}} that resolves with an object that can be used to check whether or not particular WebAuthn client capabilities and [extensions](/en-US/docs/Web/API/Web_Authentication_API/WebAuthn_extensions) are supported. |
| 12 | + |
| 13 | +A relying party (RP) can use this information to appropriately customize its sign-in and sign-up user interfaces and workflows. |
| 14 | + |
| 15 | +## Syntax |
| 16 | + |
| 17 | +```js-nolint |
| 18 | +PublicKeyCredential.getClientCapabilities() |
| 19 | +``` |
| 20 | + |
| 21 | +### Parameters |
| 22 | + |
| 23 | +None. |
| 24 | + |
| 25 | +### Return value |
| 26 | + |
| 27 | +A {{jsxref("Promise")}} that resolves to an object where the property names are the client capability strings, and the values are boolean values that indicate whether or not the corresponding capability or extension is supported. |
| 28 | + |
| 29 | +The WebAuthn client capability strings are: |
| 30 | + |
| 31 | +- `"conditionalCreate"` |
| 32 | + - : The client is capable of creating [discoverable credentials](/en-US/docs/Web/API/Web_Authentication_API#discoverable_credentials_and_conditional_mediation). |
| 33 | +- `"conditionalGet"` |
| 34 | + - : The client is capable of authenticating using [discoverable credentials](/en-US/docs/Web/API/Web_Authentication_API#discoverable_credentials_and_conditional_mediation). |
| 35 | + This capability is equivalent to [`isConditionalMediationAvailable()`](/en-US/docs/Web/API/PublicKeyCredential/isConditionalMediationAvailable_static) resolving to `true`. |
| 36 | +- `"hybridTransport"` |
| 37 | + - : The client supports usage of the [hybrid](/en-US/docs/Web/API/AuthenticatorAttestationResponse/getTransports#hybrid) transport. |
| 38 | + This means that the client can use authenticators that rely on Bluetooth, NFC, or USB. |
| 39 | +- `"passkeyPlatformAuthenticator"` |
| 40 | + - : The client allows usage of a passkey authenticator that supports multi-factor authentication mechanisms such as a PIN or biometric check. |
| 41 | + The authenticator can be part of the same platform (device) as the client, or connected via a hybrid transport such as Bluetooth or USB. |
| 42 | + The credentials are stored on the authenticator. |
| 43 | + See [Passkeys developer guide for relying parties](https://developers.google.com/identity/passkeys/developer-guides). |
| 44 | +- `userVerifyingPlatformAuthenticator` |
| 45 | + - : The client has a platform authenticator (part of the same device) that supports multi-factor authentication mechanisms, such as a PIN or biometric check. |
| 46 | + The credentials may be stored on either the RP or the authenticator. |
| 47 | +- `relatedOrigins` |
| 48 | + - : The client supports [Related Origin Requests](https://web.dev/articles/webauthn-related-origin-requests). |
| 49 | + These clients allow a passkey to be used across multiple sites that have the same origin. |
| 50 | +- `signalAllAcceptedCredentials` |
| 51 | + - : The client supports the [`PublicKeyCredential.signalAllAcceptedCredentials()`](/en-US/docs/Web/API/PublicKeyCredential/signalAllAcceptedCredentials_static) static method. |
| 52 | + If not supported, RP workflows will need to prompt the user to manually delete credentials on the authenticator. |
| 53 | +- `signalCurrentUserDetails` |
| 54 | + - : The client supports the [`PublicKeyCredential.signalCurrentUserDetails()`](/en-US/docs/Web/API/PublicKeyCredential/signalCurrentUserDetails_static) static method. |
| 55 | + If not supported, RP workflows will need to prompt the user to manually update user details on the authenticator. |
| 56 | +- `signalUnknownCredential` |
| 57 | + - : The client supports the [`PublicKeyCredential.signalUnknownCredential()`](/en-US/docs/Web/API/PublicKeyCredential/signalUnknownCredential_static) static method. |
| 58 | + If not supported, RP workflows will need to prompt the user to manually delete credentials from the authenticator. |
| 59 | + |
| 60 | +The [web extension](/en-US/docs/Web/API/Web_Authentication_API/WebAuthn_extensions) strings are formatted by prefixing the [extension identifier](/en-US/docs/Web/API/Web_Authentication_API/WebAuthn_extensions#available_extensions) with the prefix `extension:`. |
| 61 | +For example, the key `extension:appid` can be used to check if the [`appid` extension](/en-US/docs/Web/API/Web_Authentication_API/WebAuthn_extensions#appid) is supported. |
| 62 | + |
| 63 | +### Exceptions |
| 64 | + |
| 65 | +The returned {{jsxref("Promise")}} may be rejected with the following values: |
| 66 | + |
| 67 | +- `NotAllowedError` {{domxref("DOMException")}} |
| 68 | + - : The Web Authentication API is not allowed in the current browsing context. |
| 69 | + For example, it might be blocked by a permission policy. |
| 70 | + |
| 71 | +## Description |
| 72 | + |
| 73 | +`getClientCapabilities()` allows you to check if a given capability or extension is supported, and use the information to offer an appropriate user experience. |
| 74 | + |
| 75 | +For example, support for the `userVerifyingPlatformAuthenticator` capability indicates that biometrics such as a fingerprint sensor are allowed. |
| 76 | +A web application could use this to display a fingerprint icon if the capability is supported, or a password input if it is not. |
| 77 | +If biometric login is required, then it could instead provide notification that the site cannot authenticate using this browser or device. |
| 78 | +Similarly, `conditionalGet` indicates that the client supports conditional mediation when signing in a user, which means the browser can provide auto-filled discoverable credentials in a login form (for example an autocompleting text field or a drop-down list), along with a sign-in button. |
| 79 | + |
| 80 | +If the value of a given capability is present in the returned object, then `true` indicates that the capability is currently supported, and `false` indicates that it is not. |
| 81 | +However, if a key is not present for a particular capability, no assumptions can be made about the availability of the associated feature. |
| 82 | + |
| 83 | +For an extension the assumptions are the same. |
| 84 | +Note though, that even if the extension is supported by the client a particular authenticator may not support that extension, so RPs must not assume that this is a guarantee that the authenticator processing steps for that extension will be performed. |
| 85 | +If the key is not present for an extension, an RP can't assume that the client processing steps for that extension will be carried out by this client, or that the extension will be forwarded to the authenticator. |
| 86 | + |
| 87 | +## Examples |
| 88 | + |
| 89 | +### Check all capabilities |
| 90 | + |
| 91 | +This example shows how to get the capabilities object and iterate its values. |
| 92 | + |
| 93 | +```html hidden |
| 94 | +<pre id="log"></pre> |
| 95 | +``` |
| 96 | + |
| 97 | +```js hidden |
| 98 | +const logElement = document.querySelector("#log"); |
| 99 | +function log(text) { |
| 100 | + logElement.innerText = `${logElement.innerText}${text}\n`; |
| 101 | + logElement.scrollTop = logElement.scrollHeight; |
| 102 | +} |
| 103 | +``` |
| 104 | + |
| 105 | +```css hidden |
| 106 | +#log { |
| 107 | + height: 230px; |
| 108 | + overflow: scroll; |
| 109 | + padding: 0.5rem; |
| 110 | + border: 1px solid black; |
| 111 | +} |
| 112 | +``` |
| 113 | + |
| 114 | +#### JavaScript |
| 115 | + |
| 116 | +First we await `getClientCapabilities()` to get an object containing the capabilities. |
| 117 | +We then iterate the object and log the result (logging code not shown): |
| 118 | + |
| 119 | +```js |
| 120 | +async function checkClientCapabilities() { |
| 121 | + const capabilities = await PublicKeyCredential.getClientCapabilities(); |
| 122 | + |
| 123 | + if (capabilities) { |
| 124 | + log("Client Capabilities:"); |
| 125 | + |
| 126 | + for (const [key, value] of Object.entries(capabilities)) { |
| 127 | + log(` ${key}: ${value}`); |
| 128 | + } |
| 129 | + } |
| 130 | +} |
| 131 | +``` |
| 132 | + |
| 133 | +Before calling the function we check that it is defined, and log the result. |
| 134 | + |
| 135 | +```js |
| 136 | +// Call the function to check capabilities. |
| 137 | +if (PublicKeyCredential.getClientCapabilities) { |
| 138 | + checkClientCapabilities(); |
| 139 | +} else { |
| 140 | + log( |
| 141 | + "PublicKeyCredential.getClientCapabilities() is not supported on this browser.", |
| 142 | + ); |
| 143 | +} |
| 144 | +``` |
| 145 | + |
| 146 | +#### Result |
| 147 | + |
| 148 | +{{EmbedLiveSample("Check all capabilities", "", "280")}} |
| 149 | + |
| 150 | +### Test for user verifying platform authenticator |
| 151 | + |
| 152 | +This example checks a single capability, `userVerifyingPlatformAuthenticator`. A real application might use the result to configure the user interface. |
| 153 | + |
| 154 | +```html hidden |
| 155 | +<pre id="log"></pre> |
| 156 | +``` |
| 157 | + |
| 158 | +```js hidden |
| 159 | +const logElement = document.querySelector("#log"); |
| 160 | +function log(text) { |
| 161 | + logElement.innerText = `${logElement.innerText}${text}\n`; |
| 162 | + logElement.scrollTop = logElement.scrollHeight; |
| 163 | +} |
| 164 | +``` |
| 165 | + |
| 166 | +```css hidden |
| 167 | +#log { |
| 168 | + height: 40px; |
| 169 | + overflow: scroll; |
| 170 | + padding: 0.5rem; |
| 171 | + border: 1px solid black; |
| 172 | +} |
| 173 | +``` |
| 174 | + |
| 175 | +#### JavaScript |
| 176 | + |
| 177 | +The code is similar to the previous example, except that we check a particular returned capability, and we use `try...catch` to catch the case where `getClientCapabilities()` is not supported. |
| 178 | + |
| 179 | +```js |
| 180 | +checkisUserVerifyingPlatformAuthenticatorAvailable(); |
| 181 | + |
| 182 | +async function checkisUserVerifyingPlatformAuthenticatorAvailable() { |
| 183 | + try { |
| 184 | + const capabilities = await PublicKeyCredential.getClientCapabilities(); |
| 185 | + |
| 186 | + if (capabilities.userVerifyingPlatformAuthenticator) { |
| 187 | + log("Biometric login supported"); |
| 188 | + } else { |
| 189 | + log("Biometric login not supported. Do password."); |
| 190 | + } |
| 191 | + } catch (error) { |
| 192 | + if (error instanceof TypeError) { |
| 193 | + log( |
| 194 | + "PublicKeyCredential.getClientCapabilities() is not supported on this browser.", |
| 195 | + ); |
| 196 | + } else { |
| 197 | + log(`Unexpected error: ${error}`); |
| 198 | + } |
| 199 | + } |
| 200 | +} |
| 201 | +``` |
| 202 | + |
| 203 | +Note that here we log the result of a check. |
| 204 | +In a real application we might update the user interface to show appropriate options for verifying the user. |
| 205 | + |
| 206 | +#### Result |
| 207 | + |
| 208 | +The log below displays either a string indicating the method is not supported, or one that indicates whether biometric or password login is supported. |
| 209 | + |
| 210 | +{{EmbedLiveSample("Test for user verifying platform authenticator", "", "90")}} |
| 211 | + |
| 212 | +## Specifications |
| 213 | + |
| 214 | +{{Specifications}} |
| 215 | + |
| 216 | +## Browser compatibility |
| 217 | + |
| 218 | +{{Compat}} |
| 219 | + |
| 220 | +## See also |
| 221 | + |
| 222 | +- [Web Authentication API](/en-US/docs/Web/API/Web_Authentication_API) |
0 commit comments