From 3ed33d1be6a1d6f41d063f76cdd00ad3269bbf1c Mon Sep 17 00:00:00 2001 From: wbamberg Date: Tue, 30 Jul 2024 16:02:23 -0700 Subject: [PATCH] Normalize CredentialsContainer.get() --- .../api/credentialscontainer/create/index.md | 2 +- .../web/api/credentialscontainer/get/index.md | 341 ++++-------------- .../api/fedcm_api/idp_integration/index.md | 2 +- .../identitycredentialrequestoptions/index.md | 66 ++++ .../index.md | 14 +- .../index.md | 91 +++++ files/jsondata/GroupData.json | 2 + 7 files changed, 241 insertions(+), 277 deletions(-) create mode 100644 files/en-us/web/api/identitycredentialrequestoptions/index.md create mode 100644 files/en-us/web/api/publickeycredentialrequestoptions/index.md diff --git a/files/en-us/web/api/credentialscontainer/create/index.md b/files/en-us/web/api/credentialscontainer/create/index.md index 00858ff876ec81d..b3fa179fd59494a 100644 --- a/files/en-us/web/api/credentialscontainer/create/index.md +++ b/files/en-us/web/api/credentialscontainer/create/index.md @@ -8,7 +8,7 @@ browser-compat: api.CredentialsContainer.create {{APIRef("Credential Management API")}}{{SecureContext_Header}} -The **`create()`** method of the {{domxref("CredentialsContainer")}} interface creates a new {{glossary("credential")}}, which can then be stored and later used to authenticate users via {{domxref("CredentialsContainer.get", "navigator.credentials.get()")}}. +The **`create()`** method of the {{domxref("CredentialsContainer")}} interface creates a new {{glossary("credential")}}, which can then be stored and later retrieved using the {{domxref("CredentialsContainer.get", "navigator.credentials.get()")}} method. This method supports three different types of credential: diff --git a/files/en-us/web/api/credentialscontainer/get/index.md b/files/en-us/web/api/credentialscontainer/get/index.md index 0c506b1cf598df7..64b25b0ae512e4d 100644 --- a/files/en-us/web/api/credentialscontainer/get/index.md +++ b/files/en-us/web/api/credentialscontainer/get/index.md @@ -8,16 +8,17 @@ browser-compat: api.CredentialsContainer.get {{APIRef("Credential Management API")}}{{SecureContext_Header}} -The **`get()`** method of the {{domxref("CredentialsContainer")}} interface returns a {{jsxref("Promise")}} that fulfills with a single credential instance that matches the provided parameters, which the browser can then use to authenticate with a relying party. This is used by several different credential-related APIs with significantly different purposes: +The **`get()`** method of the {{domxref("CredentialsContainer")}} interface returns a {{jsxref("Promise")}} that fulfills with a single {{glossary("credential")}}, which can then be used to authenticate a user: for example, when signing them into a website. -- The [Credential Management API](/en-US/docs/Web/API/Credential_Management_API) uses `get()` to authenticate using basic federated credentials or username/password credentials. -- The [Web Authentication API](/en-US/docs/Web/API/Web_Authentication_API) uses `get()` to authenticate or provide additional factors during MFA with public key credentials (based on asymmetric cryptography). -- The [Federated Credential Management (FedCM) API](/en-US/docs/Web/API/FedCM_API) uses `get()` to authenticate with federated identity providers (IdPs). -- The [WebOTP API](/en-US/docs/Web/API/WebOTP_API) uses `get()` to request retrieval of a one-time password (OTP) from a specially-formatted SMS message sent by an app server. +The method accepts a single optional `options` argument, which may include: -The below reference page starts with a syntax section that explains the general method call structure and parameters that apply to all the different APIs. After that, it is split into separate sections providing parameters, return values, and examples specific to each API. +- A `mediation` property indicating how and whether the user should be asked to participate in the operation, controlling, for example, whether the site can silently sign a user in using a stored credential. +- A `signal` property enabling the operation to be cancelled using an {{domxref("AbortController")}}. +- One or more properties — `password`, `federated`, `identity`, `otp`, `publicKey` — which indicate the [types of credential](/en-US/docs/Web/API/Credential_Management_API/Credential_types) being requested. If set, the values of these properties include any parameters that the browser needs in order to find an appropriate credential of the requested type. -## General syntax +The API always fulfills with a single credential or `null`. If multiple credentials are available and user mediation is allowed, then the browser will ask the user to select a single credential. + +## Syntax ```js-nolint get() @@ -42,7 +43,7 @@ get(options) - `"silent"`: The user will not be asked to authenticate. The user agent will automatically reauthenticate the user and log them in if possible. If consent is required, the promise will fulfill with `null`. This value is intended for situations where you would want to automatically sign a user in upon visiting a web app if possible, but if not, you don't want to present them with a confusing login dialog box. Instead, you'd want to wait for them to explicitly click a "Login/Signup" button. - If `mediation` is omitted, it will default to `"optional"`. + The default value is `"optional"`. > [!NOTE] > In the case of a [federated authentication (FedCM API)](/en-US/docs/Web/API/FedCM_API) request, a `mediation` value of `optional` or `silent` may result in attempted [auto-reauthentication](/en-US/docs/Web/API/FedCM_API/RP_sign-in#auto-reauthentication). Whether this occurred is communicated to the identity provider (IdP) via the [`is_auto_selected`](/en-US/docs/Web/API/FedCM_API/IDP_integration#is_auto_selected) parameter sent to the IdP's `id_assertion_endpoint` during validation and the relying party (RP) via the {{domxref("IdentityCredential.isAutoSelected")}} property. This is useful for performance evaluation, security requirements (the IdP may wish to reject automatic reauthentication requests and always require user mediation), and general UX (an IdP or RP may wish to present different UX for auto and non-auto login experiences). @@ -51,122 +52,82 @@ get(options) - : An {{domxref("AbortSignal")}} object instance that allows an ongoing `get()` operation to be aborted. An aborted operation may complete normally (generally if the abort was received after the operation finished) or reject with an "`AbortError`" {{domxref("DOMException")}}. - Each of the following properties represents a _credential type_ being requested: - - - `federated` {{optional_inline}} - - : An object containing requirements for a requested credential from a federated identify provider. Bear in mind that the Federated Credential Management API (the `identity` credential type) supersedes this credential type. See the [Credential Management API](#credential_management_api) section below for more details. - `password` {{optional_inline}} - - : A boolean value indicating that a password credential is being requested. See the [Credential Management API](#credential_management_api) section below for more details. + - : This option asks the browser to retrieve a stored [password](/en-US/docs/Web/API/Credential_Management_API/Credential_types#passwords) as a {{domxref("PasswordCredential")}} object. It is a boolean value. - `identity` {{optional_inline}} - - : An object containing details of federated identity providers (IdPs) that a relying party (RP) website can use for purposes such as signing in or signing up on a website. It causes the `get()` call to initiate a request for a user to sign in to an RP with an IdP. See the [Federated Credential Management API](#federated_credential_management_api) section below for more details. - - `otp` {{optional_inline}} - - : An object containing transport type hints. Causes the `get()` call to initiate a request for the retrieval of an OTP. See the [WebOTP API](#webotp_api) section below for more details. - - `publicKey` {{optional_inline}} - - : An object containing requirements for returned public key credentials. Causes the `get()` call to use an existing set of public key credentials to authenticate to a relying party. See the [Web Authentication API](#web_authentication_api) section below for more details. -## Credential Management API + - : This option asks the browser to retrieve a [federated identity credential](/en-US/docs/Web/API/Credential_Management_API/Credential_types#federated_identity_credentials) as an {{domxref("IdentityCredential")}} object, using the [Federated Credential Management API](/en-US/docs/Web/API/FedCM_API). -The [Credential Management API](/en-US/docs/Web/API/Credential_Management_API) lets a website store and retrieve password and federated credentials. These capabilities allow users to sign in without typing passwords, see the federated account they used to sign in to a site, and resume a session without the explicit sign-in flow of an expired session. + This option's value is an {{domxref("IdentityCredentialRequestOptions")}} object containing details of the specific identity providers that the website wants to use. -### `federated` object structure - -`federated` will contain the following properties: - -- `protocols` - - : An array of strings representing the protocols of the requested credentials' federated identity providers (for example, `"openidconnect"`). -- `providers` - - : An array of strings representing the credentials' federated identity providers (for example `"https://www.facebook.com"` or `"https://accounts.google.com"`). - -### `password` boolean value + - `federated` {{optional_inline}} -`password` is a single boolean value. If set to `true`, it indicates that the requested credential is a password credential. + - : This option asks the browser to retrieve a [federated identity credential](/en-US/docs/Web/API/Credential_Management_API/Credential_types#federated_identity_credentials) as a {{domxref("FederatedCredential")}} object, using the now superseded {{domxref("FederatedCredential")}} interface. Developers should prefer to use the `identity` option, if it is available. -### Return value + This option's value is an object with the following properties: -A {{jsxref("Promise")}} that resolves with a {{domxref("Credential")}} instance matching the provided parameters: + - `protocols` + - : An array of strings representing the protocols of the requested credentials' federated identity providers (for example, `"openidconnect"`). + - `providers` + - : An array of strings representing the credentials' federated identity providers (for example `"https://www.facebook.com"` or `"https://accounts.google.com"`). -- If the provided credential type was a `federated` object, the returned instance will be a {{domxref("FederatedCredential")}}. -- If the provided credential type was a `password` boolean value of `true`, the returned instance will be a {{domxref("PasswordCredential")}}. + - `otp` {{optional_inline}} -If a single credential cannot be unambiguously obtained, the Promise will resolve to `null`. + - : This option asks the browser to retrieve a [one-time password (OTP)](/en-US/docs/Web/API/Credential_Management_API/Credential_types#one-time_passwords) as an {{domxref("OTPCredential")}} object. -### Examples + This option's value is an array of strings which may only contain the string value `"sms"`. -```js -navigator.credentials - .get({ - federated: { - protocols: ["openidconnect"], - providers: ["https://www.facebook.com", "https://accounts.google.com"], - }, - }) - .then((fedCred) => { - console.log(fedCred.provider); - }); -``` + - `publicKey` {{optional_inline}} -## Federated Credential Management API + - : This option asks the browser to retrieve an [assertion signed using the Web Authentication API](/en-US/docs/Web/API/Credential_Management_API/Credential_types#web_authentication_assertions) as a {{domxref("PublicKeyCredential")}}. -The [Federated Credential Management (FedCM) API](/en-US/docs/Web/API/FedCM_API) provides a standard mechanism to delegate authentication or authorization of an individual (user or entity) to trusted external parties called identity providers (IdPs) in a privacy-preserving way, without relying on [third-party cookies](/en-US/docs/Web/Privacy/Third-party_cookies) and redirects. + This option's value is a {{domxref("PublicKeyCredentialRequestOptions")}} object. -An individual can then use an existing IdP account (that they are already signed into on the browser) to sign into a website (a relying party or RP). The RP handles this by calling `get()` with an `identity` option. +### Return value -> [!NOTE] -> Usage of `get()` with the `identity` parameter may be blocked by an {{httpheader("Permissions-Policy/identity-credentials-get", "identity-credentials-get")}} [Permissions Policy](/en-US/docs/Web/HTTP/Permissions_Policy) set on your server. +A {{jsxref("Promise")}} that resolves with one of the following subclasses of {{domxref("Credential")}}: -### `identity` object structure +- {{domxref("PasswordCredential")}} +- {{domxref("IdentityCredential")}} +- {{domxref("FederatedCredential")}} +- {{domxref("OTPCredential")}} +- {{domxref("PublicKeyCredential")}} -`identity` can contain the following properties: +If a single credential cannot be unambiguously obtained, the promise resolves with `null`. -- `context` {{optional_inline}} - - : An enumerated value specifying the context in which the user is authenticating with FedCM. The browser uses this value to vary the text in its FedCM UI to better suit the context. Possible values are: - - `continue`: Suitable for situations where the user is choosing an identity to continue to the next page in the flow, which requires a sign-in. Browsers will provide a text string similar to "Continue to \ with \". - - `signin`: Suitable for general situations where the user is signing in with an IdP account they've already used on this origin. Browsers will provide a text string similar to "Sign in to \ with \". This is the default value. - - `signup`: An option for situations where the user is signing in to the origin with a new IdP account they've not used here before. Browsers will provide a text string similar to "Sign up to \ with \". - - `use`: Suitable for situations where a different action, such as validating a payment, is being performed. Browsers will provide a text string similar to "Use \ with \". -- `providers` +### Exceptions - - : An array containing a single object specifying details of an IdP to be used to sign in. This object can contain the following properties: +- `AbortError` {{domxref("DOMException")}} - - `configURL` - - : A string specifying the URL of the IdP's config file. See [Provide a config file](/en-US/docs/Web/API/FedCM_API/IDP_integration#provide_a_config_file_and_endpoints) for more information. - - `clientId` - - : A string specifying the RP's client identifier. This information is issued by the IdP to the RP in a separate process that is specific to the IdP. - - `loginHint` {{optional_inline}} - - : A string providing a hint about the account option(s) the browser should provide for the user to sign in with. This is useful in cases where the user has already signed in and the site asks them to reauthenticate. Otherwise, the reauthentication process can be confusing when a user has multiple accounts and can't remember which one they used to sign in previously. The value for the `loginHint` property can be taken from the user's previous sign-in, and is matched against the `login_hints` values provided by the IdP in the array of user information returned from the IdP's [accounts list endpoint](/en-US/docs/Web/API/FedCM_API/IDP_integration#the_accounts_list_endpoint). - - `nonce` {{optional_inline}} - - : A random string that can be included to ensure the response is issued specifically for this request and prevent {{glossary("replay attack", "replay attacks")}}. + - : The request was aborted by a call to the {{domxref("AbortController.abort", "abort()")}} method of the {{domxref("AbortController")}} associated with this method's [`signal`](#signal) option. - > [!NOTE] - > Currently FedCM only allows the API to be invoked with a single IdP, i.e. the `identity.providers` array has to have a length of 1. Multiple IdPs must be supported via different `get()` calls. +- `IdentityCredentialError` {{domxref("DOMException")}} -### Return value + - : When requesting an {{domxref("IdentityCredential")}}, the request to the [ID assertion endpoint](/en-US/docs/Web/API/FedCM_API/IDP_integration#the_id_assertion_endpoint) is unable to validate the authentication, and rejects with an error response containing information about the reason. -A {{jsxref("Promise")}} that resolves with an {{domxref("IdentityCredential")}} instance matching the provided parameters if the user identity is successfully validated by the IdP. +- `NetworkError` {{domxref("DOMException")}} -This object contains a token that includes user identity information that has been signed with the IdP's {{glossary("digital certificate")}}. + - : When requesting an {{domxref("IdentityCredential")}}, the {{glossary("identity provider")}} (IdP) did not respond within 60 seconds, the provided credentials were not valid/found, or the browser's login status for the IdP is set to `"logged-out"` (see [Update login status using the Login Status API](/en-US/docs/Web/API/FedCM_API/IDP_integration#update_login_status_using_the_login_status_api) for more information about FedCM login status). In the latter case, there may be some delay in the rejection to avoid leaking the IdP login status to the RP. -The RP sends the token to its server to validate the certificate, and on success can use the (now trusted) identity information in the token to sign them into their service (starting a new session), sign them up to their service if they are a new user, etc. +- `NotAllowedError` {{domxref("DOMException")}} -If the `get()` method's promise rejects, the RP can direct the user to the IdP login page to sign in or create an account. + - : Thrown in one of the following situations: -> [!NOTE] -> The exact nature of the token is opaque to the FedCM API, and to the browser. The IdP decides on the syntax and usage of it, and the RP needs to follow the instructions provided by the IdP (see [Verify the Google ID token on your server side](https://developers.google.com/identity/gsi/web/guides/verify-google-id-token), for example) to make sure they are using it correctly. + - Use of this API was blocked by one of the following [permissions policies](/en-US/docs/Web/HTTP/Permissions_Policy): -### Exceptions + - {{HTTPHeader("Permissions-Policy/identity-credentials-get","identity-credentials-get")}} + - {{HTTPHeader("Permissions-Policy/publickey-credentials-get","publickey-credentials-get")}} + - {{HTTPHeader("Permissions-Policy/otp-credentials","otp-credentials")}} -- `IdentityCredentialError` {{domxref("DOMException")}} - - : The request to the [ID assertion endpoint](/en-US/docs/Web/API/FedCM_API/IDP_integration#the_id_assertion_endpoint) is unable to validate the authentication, and rejects with an error response containing information about why. See the [Error API example](#example_including_error_api_information) below for more information on how it can be used. -- `NetworkError` {{domxref("DOMException")}} + - The calling origin is an [opaque origin](/en-US/docs/Web/HTTP/Headers/Origin#null). - - : The IdP did not respond within 60 seconds, the provided credentials were not valid/found, or the browser's login status for the IdP is set to `"logged-out"` (see [Update login status using the Login Status API](/en-US/docs/Web/API/FedCM_API/IDP_integration#update_login_status_using_the_login_status_api) for more information about FedCM login status). In the latter case, there may be some delay in the rejection to avoid leaking the IdP login status to the RP. +- `SecurityError` {{domxref("DOMException")}} -- `NotAllowedError` {{domxref("DOMException")}} - - : Use of this feature was blocked by an {{HTTPHeader("Permissions-Policy/identity-credentials-get","identity-credentials-get")}} [Permissions Policy](/en-US/docs/Web/HTTP/Permissions_Policy). + - : The calling domain is not a valid domain. -### Examples +## Examples -#### Basic example +### Retrieving a federated identity credential Relying parties can call `get()` with the `identity` option to make a request for users to sign in to the relying party via an identity provider (IdP), using identity federation. A typical request would look like this: @@ -188,8 +149,6 @@ async function signIn() { Check out [Federated Credential Management (FedCM) API](/en-US/docs/Web/API/FedCM_API) for more details on how this works. This call will start off the sign-in flow described in [FedCM sign-in flow](/en-US/docs/Web/API/FedCM_API/RP_sign-in#fedcm_sign-in_flow). -#### Example including context and login hint - A similar call including the `context` and `loginHint` extensions would look like so: ```js @@ -210,14 +169,7 @@ async function signIn() { } ``` -> [!NOTE] -> After a user has signed in with an IdP, the IdP can call the static {{domxref("IdentityProvider.getUserInfo_static", "IdentityProvider.getUserInfo()")}} method to retrieve their details. `getUserInfo()` must be called from within an IdP-origin {{htmlelement("iframe")}} to ensure that RP scripts cannot access the data. This information can then be used to display a personalized welcome message and sign-in button. This approach is already common on sites that use identity federation for sign-in. However, `getUserInfo()` offers a way to achieve this without relying on [third-party cookies](/en-US/docs/Web/Privacy/Third-party_cookies). - -#### Example including Error API information - -If the IdP is unable to validate the authentication for a request to the [ID assertion endpoint](/en-US/docs/Web/API/FedCM_API/IDP_integration#the_id_assertion_endpoint) it will respond with an error. - -The error may be handled in code as shown: +If the IdP is unable to validate a request to the [ID assertion endpoint](/en-US/docs/Web/API/FedCM_API/IDP_integration#the_id_assertion_endpoint) it will reject the promise returned from `CredentialsContainer.get()`: ```js async function signIn() { @@ -241,172 +193,7 @@ async function signIn() { } ``` -## WebOTP API - -The [WebOTP API](/en-US/docs/Web/API/WebOTP_API) lets a web client request an OTP from an SMS sent by the web app's server. This capability is intended to streamline usage of OTPs in web apps, for example when using phone numbers as additional factors in sign-in flows. The OTP is retrieved from the SMS and can be set as a verification input value automatically after the user gives consent, avoiding the need for the user to manually go into their SMS app and copy and paste it. - -### `otp` object structure - -`otp` will contain the following properties: - -- `transport` - - : An array of strings representing transport hints for how the OTP should ideally be transmitted. This will always contain a single hint — `"sms"`. Unknown values will be ignored. - -### Return value - -A {{jsxref("Promise")}} that resolves with an {{domxref("OTPCredential")}} object instance. - -### Exceptions - -- `AbortError` {{domxref("DOMException")}} - - : The `get()` operation is associated with an {{domxref("AbortSignal")}} (i.e., set in the `signal` property) that has already been aborted. -- `NotAllowedError` {{domxref("DOMException")}} - - : The calling origin is an [opaque origin](/en-US/docs/Web/HTTP/Headers/Origin#null). -- `SecurityError` {{domxref("DOMException")}} - - : Either the usage is blocked by a {{HTTPHeader("Permissions-Policy/otp-credentials","otp-credentials")}} [Permissions Policy](/en-US/docs/Web/HTTP/Permissions_Policy) or the calling domain is not a valid domain. - -### Examples - -The below code triggers the browser's permission flow when an SMS message arrives. If permission is granted, then the promise resolves with an `OTPCredential` object. The contained `code` value is then set as the value of an {{htmlelement("input")}} form element, which is then submitted. - -```js -navigator.credentials - .get({ - otp: { transport: ["sms"] }, - signal: ac.signal, - }) - .then((otp) => { - input.value = otp.code; - if (form) form.submit(); - }) - .catch((err) => { - console.error(err); - }); -``` - -> [!NOTE] -> For a full explanation of the code, see the {{domxref('WebOTP API','','',' ')}} landing page. You can also [see this code as part of a full working demo](https://web-otp.glitch.me/). - -## Web Authentication API - -The [Web Authentication API](/en-US/docs/Web/API/Web_Authentication_API) enables strong authentication with public key cryptography, enabling passwordless authentication and/or secure multi-authentication (MFA) without SMS texts. Check out the linked API landing page for more usage information. - -> [!NOTE] -> Usage of `get()` with the `publicKey` parameter may be blocked by a {{HTTPHeader("Permissions-Policy/publickey-credentials-get","publickey-credentials-get")}} [Permissions Policy](/en-US/docs/Web/HTTP/Permissions_Policy) set on your server. - -### `publicKey` object structure - -`publicKey` can contain the following properties: - -- `allowCredentials` {{optional_inline}} - - - : An array of objects defining a restricted list of the acceptable credentials for retrieval. Each object will contain the following properties: - - - `id` - - - : An {{jsxref("ArrayBuffer")}}, {{jsxref("TypedArray")}}, or {{jsxref("DataView")}} representing the ID of the public key credential to retrieve. This value is mirrored by the {{domxref("PublicKeyCredential.rawId", "rawId")}} property of the {{domxref("PublicKeyCredential")}} object returned by a successful `get()` call. - - - `transports` - - - : An array of strings providing hints as to the methods the client could use to communicate with the relevant authenticator of the public key credential to retrieve. Possible transports are: `"ble"`, `"hybrid"`, `"internal"`, `"nfc"`, and `"usb"`. - - > [!NOTE] - > This value is mirrored by the return value of the {{domxref("AuthenticatorAttestationResponse.getTransports", "PublicKeyCredential.response.getTransports()")}} method of the {{domxref("PublicKeyCredential")}} object returned by the `create()` call that originally created the credential. - > At that point, it should be stored by the app for later use. - - - `type` - - : A string defining the type of the public key credential to retrieve. This can currently take a single value, `"public-key"`, but more values may be added in the future. This value is mirrored by the {{domxref("Credential.type", "type")}} property of the {{domxref("PublicKeyCredential")}} object returned by a successful `get()` call. - - If `allowCredentials` is omitted, it will default to an empty array, meaning that any credential is potentially acceptable for retrieval without the relying party first providing an ID. - -- `attestation` {{optional_inline}} - - - : A string specifying the relying party's preference for how the attestation statement (i.e., provision of verifiable evidence of the authenticity of the authenticator and its data) is conveyed during authentication. The value can be one of the following: - - - `"none"` - - - : Specifies that the relying party is not interested in authenticator attestation. This might be to avoid additional user consent for round trips to the relying party server to relay identifying information, or round trips to an attestation certificate authority (CA), with the aim of making the authentication process smoother. If `"none"` is chosen as the `attestation` value, and the authenticator signals that it uses a CA to generate its attestation statement, the client app will replace it with a "None" attestation statement, indicating that no attestation statement is available. - - - `"direct"` - - - : Specifies that the relying party wants to receive the attestation statement as generated by the authenticator. - - - `"enterprise"` - - - : Specifies that the relying party wants to receive an attestation statement that may include uniquely identifying information. This is intended for controlled deployments within an enterprise where the organization wishes to tie registrations to specific authenticators. - - - `"indirect"` - - : Specifies that the relying party wants to receive a verifiable attestation statement, but it will allow the client to decide how to receive it. For example, the client could choose to replace the authenticator's assertion statement with one generated by an anonymization CA to protect user privacy. - - If `attestation` is omitted, it will default to `"none"`. - -- `attestationFormats` {{optional_inline}} - - - : An array of strings specifying the relying party's preference for the attestation statement format used by the authenticator. Values should be ordered from highest to lowest preference, and should be considered hints — the authenticator may choose to issue an attestation statement in a different format. For a list of valid formats, see [WebAuthn Attestation Statement Format Identifiers](https://www.iana.org/assignments/webauthn/webauthn.xhtml#webauthn-attestation-statement-format-ids). - - If omitted, `attestationFormats` defaults to an empty array. - -- `challenge` - - - : An {{jsxref("ArrayBuffer")}}, {{jsxref("TypedArray")}}, or {{jsxref("DataView")}} originating from the relying party's server and used as a [cryptographic challenge](https://en.wikipedia.org/wiki/Challenge%E2%80%93response_authentication). This value will be signed by the authenticator and the signature will be sent back as part of the {{domxref("AuthenticatorAssertionResponse.signature")}} (available in the {{domxref("PublicKeyCredential.response", "response")}} property of the {{domxref("PublicKeyCredential")}} object returned by a successful `get()` call). - -- `extensions` {{optional_inline}} - - - : An object containing properties representing the input values for any requested extensions. These extensions are used to specific additional processing by the client or authenticator during the authentication process. Examples include dealing with legacy FIDO API credentials, and evaluating outputs from a pseudo-random function (PRF) associated with a credential. - - Extensions are optional and different browsers may recognize different extensions. Processing extensions is always optional for the client: if a browser does not recognize a given extension, it will just ignore it. For information on using extensions, and which ones are supported by which browsers, see [Web Authentication extensions](/en-US/docs/Web/API/Web_Authentication_API/WebAuthn_extensions). - -- `rpId` {{optional_inline}} - - - : A string that specifies the relying party's identifier (for example `"login.example.org"`). For security purposes: - - - The calling web app verifies that `rpId` matches the relying party's origin. - - The authenticator verifies that `rpId` matches the `rpId` of the credential used for the authentication ceremony. - - If `rpId` is omitted, it will default to the current origin's domain. - -- `timeout` {{optional_inline}} - - - : A numerical hint, in milliseconds, indicating the time the relying party is willing to wait for the retrieval operation to complete. This hint may be overridden by the browser. - -- `userVerification` {{optional_inline}} - - - : A string specifying the relying party's requirements for user verification of the authentication process. This verification is initiated by the authenticator, which will request the user to provide an available factor (for example a PIN or a biometric input of some kind). - - The value can be one of the following: - - - `"required"` - - : The relying party requires user verification, and the operation will fail if it does not occur. - - `"preferred"` - - : The relying party prefers user verification if possible, but the operation will not fail if it does not occur. - - `"discouraged"` - - : The relying party does not want user verification, in the interests of making user interaction as smooth as possible. - - If `userVerification` is omitted, it will default to `"preferred"`. - -- `hints` {{optional_inline}} - - - : An array of strings providing hints as to what authentication UI the user-agent should provide for the user. - - The values can be any of the following: - - - `"security-key"` - - : Authentication requires a separate dedicated physical device to provide the key. - - `"client-device"` - - : The user authenticates using their own device, such as a phone. - - `"hybrid"` - - : Authentication relies on a combination of authorization/authentication methods, potentially relying on both user and server-based mechanisms. - -### Return value - -A {{jsxref("Promise")}} that resolves with an {{domxref("PublicKeyCredential")}} instance matching the provided parameters. If a single credential cannot be unambiguously obtained, the Promise will resolve to `null`. - -### Exceptions - -- `NotAllowedError` {{domxref("DOMException")}} - - : Usage was blocked by a {{HTTPHeader("Permissions-Policy/publickey-credentials-get","publickey-credentials-get")}} [Permissions Policy](/en-US/docs/Web/HTTP/Permissions_Policy). - -### Examples +### Retrieving a public key credential The following snippet shows a typical `get()` call with the WebAuthn `publicKey` option: @@ -446,8 +233,26 @@ navigator.credentials.get({ publicKey }).then((publicKeyCredential) => { Some of this data will need to be stored on the server — for example the `signature` to provide proof that authenticator possesses the genuine private key used to create the credential, and the `userHandle` to link the user with the credential, sign in attempt, and other data. -> [!NOTE] -> See [Authenticating a user](/en-US/docs/Web/API/Web_Authentication_API#authenticating_a_user) for more information about how the overall flow works. +See [Authenticating a user](/en-US/docs/Web/API/Web_Authentication_API#authenticating_a_user) for more information about how the overall flow works. + +### Retrieving a one-time password + +The code below triggers the browser's permission flow when an SMS message arrives. If permission is granted, then the promise resolves with an `OTPCredential` object. The contained `code` value is then set as the value of an {{htmlelement("input")}} form element, which is then submitted. + +```js +navigator.credentials + .get({ + otp: { transport: ["sms"] }, + signal: ac.signal, + }) + .then((otp) => { + input.value = otp.code; + if (form) form.submit(); + }) + .catch((err) => { + console.error(err); + }); +``` ## Specifications diff --git a/files/en-us/web/api/fedcm_api/idp_integration/index.md b/files/en-us/web/api/fedcm_api/idp_integration/index.md index 5c4b78f6f52d473..17bd4d282c5053c 100644 --- a/files/en-us/web/api/fedcm_api/idp_integration/index.md +++ b/files/en-us/web/api/fedcm_api/idp_integration/index.md @@ -238,7 +238,7 @@ The error response fields are as follows: This information can be used in a couple of different ways: - The browser can display a custom UI to the user informing them of what went wrong (see the [Chrome documentation](https://developers.google.com/privacy-sandbox/blog/fedcm-chrome-120-updates#error-api) for an example). Bear in mind that if the request failed because the IdP server is unavailable, it obviously can't return any information. In such cases, the browser will report this via a generic message. -- The associated RP {{domxref("CredentialsContainer.get", "navigator.credentials.get()")}} call used to attempt sign-in will return the above information when the promise rejects, which can be used to handle the error. For example, an RP may wish to follow-up the browser's custom UI with some information to help the user succeed in a future sign-in attempt. The [`get()` Error API example](/en-US/docs/Web/API/CredentialsContainer/get#example_including_error_api_information) shows what this looks like in code. +- The associated RP {{domxref("CredentialsContainer.get", "navigator.credentials.get()")}} call used to attempt sign-in will reject its promise with an `IdentityCredentialError`, which contains the error information. An RP can catch this error and then follow up the browser's custom UI with some information to help the user succeed in a future sign-in attempt. ## Update login status using the Login Status API diff --git a/files/en-us/web/api/identitycredentialrequestoptions/index.md b/files/en-us/web/api/identitycredentialrequestoptions/index.md new file mode 100644 index 000000000000000..d417c6a43169f28 --- /dev/null +++ b/files/en-us/web/api/identitycredentialrequestoptions/index.md @@ -0,0 +1,66 @@ +--- +title: IdentityCredentialRequestOptions +slug: Web/API/IdentityCredentialRequestOptions +page-type: web-api-interface +status: + - experimental +spec-urls: https://fedidcg.github.io/FedCM/#dictdef-identitycredentialrequestoptions +--- + +{{APIRef("FedCM API")}}{{SeeCompatTable}}{{SecureContext_Header}} + +The **`IdentityCredentialRequestOptions`** dictionary represents the object passed to {{domxref("CredentialsContainer.get()")}} as the value of the `identity` option. + +It is used to request an {{domxref("IdentityCredential")}} provided by a {{glossary("identity provider", "federated identity provider")}} that supports the [Federated Credential Management (FedCM) API](/en-US/docs/Web/API/FedCM_API). + +## Instance properties + +- `context` {{optional_inline}} + + - : A string specifying the context in which the user is authenticating with FedCM. The browser uses this value to vary the text in its FedCM UI to better suit the context. Possible values are: + + - `"continue"` + + - : Suitable for situations where the user is choosing an identity to continue to the next page in the flow, which requires a sign-in. Browsers will provide a text string similar to: + + > _Continue to \ with \_ + + - `"signin"` + + - : Suitable for general situations where the user is signing in with an IdP account they've already used on this origin. Browsers will provide a text string similar to: + + > _Sign in to \ with \_ + + - `"signup"` + + - : An option for situations where the user is signing in to the origin with a new IdP account they've not used here before. Browsers will provide a text string similar to: + + > _Sign up to \ with \_ + + - `"use"` + + - : Suitable for situations where a different action, such as validating a payment, is being performed. Browsers will provide a text string similar to: + + > _Use \ with \_ + +The default value is `"signin"`. + +- `providers` + + - : An array containing a single object specifying details of an IdP to be used to sign in. This object can contain the following properties: + + - `configURL` + - : A string specifying the URL of the IdP's config file. See [Provide a config file](/en-US/docs/Web/API/FedCM_API/IDP_integration#provide_a_config_file_and_endpoints) for more information. + - `clientId` + - : A string specifying the RP's client identifier. This information is issued by the IdP to the RP in a separate process that is specific to the IdP. + - `loginHint` {{optional_inline}} + - : A string providing a hint about the account option(s) the browser should provide for the user to sign in with. This is useful in cases where the user has already signed in and the site asks them to reauthenticate. Otherwise, the reauthentication process can be confusing when a user has multiple accounts and can't remember which one they used to sign in previously. The value for the `loginHint` property can be taken from the user's previous sign-in, and is matched against the `login_hints` values provided by the IdP in the array of user information returned from the IdP's [accounts list endpoint](/en-US/docs/Web/API/FedCM_API/IDP_integration#the_accounts_list_endpoint). + - `nonce` {{optional_inline}} + - : A random string that can be included to ensure the response is issued specifically for this request and prevent {{glossary("replay attack", "replay attacks")}}. + + > [!NOTE] + > Currently FedCM only allows the API to be invoked with a single IdP, i.e. the `identity.providers` array has to have a length of 1. Multiple IdPs must be supported via different `get()` calls. + +## Specifications + +{{Specifications}} diff --git a/files/en-us/web/api/publickeycredential/parserequestoptionsfromjson_static/index.md b/files/en-us/web/api/publickeycredential/parserequestoptionsfromjson_static/index.md index d2f6a5dacc37e85..bdd6ef706dc3517 100644 --- a/files/en-us/web/api/publickeycredential/parserequestoptionsfromjson_static/index.md +++ b/files/en-us/web/api/publickeycredential/parserequestoptionsfromjson_static/index.md @@ -10,7 +10,7 @@ browser-compat: api.PublicKeyCredential.parseRequestOptionsFromJSON_static {{APIRef("Web Authentication API")}} {{SeeCompatTable}}{{securecontext_header}} -The **`parseRequestOptionsFromJSON()`** static method of the {{domxref("PublicKeyCredential")}} interface converts a {{glossary("JSON type representation")}} into its corresponding [`publicKey` request credentials options object structure](/en-US/docs/Web/API/CredentialsContainer/get#publickey_object_structure). +The **`parseRequestOptionsFromJSON()`** static method of the {{domxref("PublicKeyCredential")}} interface converts a {{glossary("JSON type representation")}} into a {{domxref("PublicKeyCredentialRequestOptions")}} instance. The method is a convenience function for converting information provided by a relying server to a web app in order to request an existing credential. @@ -24,25 +24,25 @@ PublicKeyCredential.parseRequestOptionsFromJSON(options) - `options` - - : An object with the same structure as the Web Authentication API [`publicKey` request credentials options object](/en-US/docs/Web/API/CredentialsContainer/get#publickey_object_structure), but with [base64url](/en-US/docs/Glossary/Base64)-encoded strings used in place of buffer properties. + - : An object with the same structure as a {{domxref("PublicKeyCredentialRequestOptions")}} instance, but with [base64url](/en-US/docs/Glossary/Base64)-encoded strings used in place of buffer properties. ### Return value -An object with the Web Authentication API [`publicKey` request credentials options object structure](/en-US/docs/Web/API/CredentialsContainer/get#publickey_object_structure). +A {{domxref("PublicKeyCredentialRequestOptions")}} instance. ### Exceptions - `EncodingError` {{domxref("DOMException")}} - - : Thrown if any part of the `options` object cannot be converted into the [`publicKey` request credentials options object structure](/en-US/docs/Web/API/CredentialsContainer/get#publickey_object_structure). + - : Thrown if any part of the `options` object cannot be converted into a {{domxref("PublicKeyCredentialRequestOptions")}} instance. ## Description The Web Authentication process for [authenticating a (registered) user](/en-US/docs/Web/API/Web_Authentication_API#authenticating_a_user) involves a relying party server sending the web app information needed to find an existing credential, including details about the user identity, the relying party, a "challenge", and optionally where to look for the credential: for example on a local built-in authenticator, or on an external one over USB, BLE, and so on. -The web app passes this information to an authenticator to find the credential, by calling [`navigator.credentials.get()`](/en-US/docs/Web/API/CredentialsContainer/get) with an argument that contains the server-supplied data in the [`publicKey` request credentials options object structure](/en-US/docs/Web/API/CredentialsContainer/get#publickey_object_structure). +The web app passes this information to an authenticator to find the credential, by calling [`navigator.credentials.get()`](/en-US/docs/Web/API/CredentialsContainer/get) with an argument that contains the server-supplied data as a {{domxref("PublicKeyCredentialRequestOptions")}} instance The specification does not define how the information needed for requesting a credential is sent. -A convenient approach is for the server to encapsulate the information in a {{glossary("JSON type representation")}} of the [`publicKey` request credentials options object](/en-US/docs/Web/API/CredentialsContainer/get#publickey_object_structure) that mirrors its structure but encodes buffer properties such as the `challenge` as [base64url](/en-US/docs/Glossary/Base64) strings. -This object can be serialized to a [JSON](/en-US/docs/Glossary/JSON) string, sent to the web app and deserialized, and then converted to the [`publicKey` request credentials options object structure](/en-US/docs/Web/API/CredentialsContainer/get#publickey_object_structure) using **`parseRequestOptionsFromJSON()`**. +A convenient approach is for the server to encapsulate the information in a {{glossary("JSON type representation")}} of the a {{domxref("PublicKeyCredentialRequestOptions")}} instance, that mirrors its structure but encodes buffer properties such as the `challenge` as [base64url](/en-US/docs/Glossary/Base64) strings. +This object can be serialized to a [JSON](/en-US/docs/Glossary/JSON) string, sent to the web app and deserialized, and then converted to a {{domxref("PublicKeyCredentialRequestOptions")}} instance using **`parseRequestOptionsFromJSON()`**. ## Examples diff --git a/files/en-us/web/api/publickeycredentialrequestoptions/index.md b/files/en-us/web/api/publickeycredentialrequestoptions/index.md new file mode 100644 index 000000000000000..504b744d6e35998 --- /dev/null +++ b/files/en-us/web/api/publickeycredentialrequestoptions/index.md @@ -0,0 +1,91 @@ +--- +title: PublicKeyCredentialRequestOptions +slug: Web/API/PublicKeyCredentialRequestOptions +page-type: web-api-interface +status: + - experimental +spec-urls: https://w3c.github.io/webauthn/#dictdef-publickeycredentialrequestoptions +--- + +{{APIRef("Web Authentication API")}}{{securecontext_header}} + +The **`PublicKeyCredentialRequestOptions`** dictionary represents the object passed to {{domxref("CredentialsContainer.get()")}} as the value of the `publicKey` option: that is, when using `get()` to generate an assertion using the [Web Authentication API](/en-US/docs/Web/API/Web_Authentication_API). + +## Instance properties + +- `allowCredentials` {{optional_inline}} + + - : An array of objects defining a restricted list of the acceptable credentials for retrieval. Each object will contain the following properties: + + - `id` + + - : An {{jsxref("ArrayBuffer")}}, {{jsxref("TypedArray")}}, or {{jsxref("DataView")}} representing the ID of the public key credential to retrieve. This value is mirrored by the {{domxref("PublicKeyCredential.rawId", "rawId")}} property of the {{domxref("PublicKeyCredential")}} object returned by a successful `get()` call. + + - `transports` + + - : An array of strings providing hints as to the methods the client could use to communicate with the relevant authenticator of the public key credential to retrieve. Possible transports are: `"ble"`, `"hybrid"`, `"internal"`, `"nfc"`, and `"usb"`. + + > [!NOTE] + > This value is mirrored by the return value of the {{domxref("AuthenticatorAttestationResponse.getTransports", "PublicKeyCredential.response.getTransports()")}} method of the {{domxref("PublicKeyCredential")}} object returned by the `create()` call that originally created the credential. + > At that point, it should be stored by the app for later use. + + - `type` + + - : A string defining the type of the public key credential to retrieve. This can currently take a single value, `"public-key"`, but more values may be added in the future. This value is mirrored by the {{domxref("Credential.type", "type")}} property of the {{domxref("PublicKeyCredential")}} object returned by a successful `get()` call. + + This value defaults to an empty array, meaning that any credential is potentially acceptable for retrieval without the relying party first providing an ID. + +- `challenge` + + - : An {{jsxref("ArrayBuffer")}}, {{jsxref("TypedArray")}}, or {{jsxref("DataView")}} originating from the relying party's server and used as a [cryptographic challenge](https://en.wikipedia.org/wiki/Challenge%E2%80%93response_authentication). This value will be signed by the authenticator and the signature will be sent back as part of the {{domxref("AuthenticatorAssertionResponse.signature")}} (available in the {{domxref("PublicKeyCredential.response", "response")}} property of the {{domxref("PublicKeyCredential")}} object returned by a successful `get()` call). + +- `extensions` {{optional_inline}} + + - : An object containing properties representing the input values for any requested extensions. These extensions are used to specific additional processing by the client or authenticator during the authentication process. Examples include dealing with legacy FIDO API credentials, and evaluating outputs from a pseudo-random function (PRF) associated with a credential. + + Extensions are optional and different browsers may recognize different extensions. Processing extensions is always optional for the client: if a browser does not recognize a given extension, it will just ignore it. For information on using extensions, and which ones are supported by which browsers, see [Web Authentication extensions](/en-US/docs/Web/API/Web_Authentication_API/WebAuthn_extensions). + +- `hints` {{optional_inline}} + + - : An array of strings providing hints as to what authentication UI the user-agent should provide for the user. + + The values can be any of the following: + + - `"security-key"` + - : Authentication requires a separate dedicated physical device to provide the key. + - `"client-device"` + - : The user authenticates using their own device, such as a phone. + - `"hybrid"` + - : Authentication relies on a combination of authorization/authentication methods, potentially relying on both user and server-based mechanisms. + +- `rpId` {{optional_inline}} + + - : A string that specifies the relying party's identifier (for example `"login.example.org"`). For security purposes: + + - The calling web app verifies that `rpId` matches the relying party's origin. + - The authenticator verifies that `rpId` matches the `rpId` of the credential used for the authentication ceremony. + + This value defaults to the current origin's domain. + +- `timeout` {{optional_inline}} + + - : A numerical hint, in milliseconds, indicating the time the relying party is willing to wait for the retrieval operation to complete. This hint may be overridden by the browser. + +- `userVerification` {{optional_inline}} + + - : A string specifying the relying party's requirements for user verification of the authentication process. This verification is initiated by the authenticator, which will request the user to provide an available factor (for example a PIN or a biometric input of some kind). + + The value can be one of the following: + + - `"required"` + - : The relying party requires user verification, and the operation will fail if it does not occur. + - `"preferred"` + - : The relying party prefers user verification if possible, but the operation will not fail if it does not occur. + - `"discouraged"` + - : The relying party does not want user verification, in the interests of making user interaction as smooth as possible. + + This value defaults to `"preferred"`. + +## Specifications + +{{Specifications}} diff --git a/files/jsondata/GroupData.json b/files/jsondata/GroupData.json index 85cf5eef5dfe2bd..6807fff8d94a267 100644 --- a/files/jsondata/GroupData.json +++ b/files/jsondata/GroupData.json @@ -507,6 +507,7 @@ ], "interfaces": [ "IdentityCredential", + "IdentityCredentialRequestOptions", "IdentityProvider", "NavigatorLogin" ], @@ -1859,6 +1860,7 @@ "interfaces": [ "PublicKeyCredential", "PublicKeyCredentialCreationOptions", + "PublicKeyCredentialRequestOptions", "AuthenticatorResponse", "AuthenticatorAttestationResponse", "AuthenticatorAssertionResponse"