Normalize CredentialsContainer.get()

files/en-us/glossary/authenticator/index.md

@@ -0,0 +1,19 @@
+---
+title: Authenticator
+slug: Glossary/Authenticator
+page-type: glossary-definition
+---
+
+{{GlossarySidebar}}
+
+An **authenticator** is an entity that is inside or attached to the user's device, and that can perform the cryptographic operations needed to register and authenticate users, and securely store the cryptographic keys used in these operations.
+
+An authenticator might be integrated into the device, like the [Touch ID](https://en.wikipedia.org/wiki/Touch_ID) system in Apple devices or the [Windows Hello](https://en.wikipedia.org/wiki/Windows_10#System_security) system, or it might be a removable module like a [Yubikey](https://en.wikipedia.org/wiki/YubiKey).
+
+The [Web Authentication API](/en-US/docs/Web/API/Web_Authentication_API) makes authenticators available to websites as part of the [Credential Management API](/en-US/docs/Web/API/Credential_Management_API). This enables websites to use authenticators to generate {{glossary("credential", "credentials")}} based on {{glossary("public-key cryptography")}}, which can then be used to sign users into websites.
+
+## See also
+
+- Related glossary terms:
+  - {{glossary("Authentication")}}
+  - {{glossary("Credential")}}

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:
 

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
 

files/en-us/web/api/identitycredentialrequestoptions/index.md

@@ -0,0 +1,64 @@
+---
+title: IdentityCredentialRequestOptions
+slug: Web/API/IdentityCredentialRequestOptions
+page-type: web-api-interface
+spec-urls: https://fedidcg.github.io/FedCM/#dictdef-identitycredentialrequestoptions
+---
+
+{{APIRef("FedCM API")}}{{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 \<page-origin\> with \<IdP\>_
+
+    - `"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 \<page-origin\> with \<IdP\>_
+
+    - `"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 \<page-origin\> with \<IdP\>_
+
+    - `"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 \<page-origin\> with \<IdP\>_
+
+  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}}

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 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
 

files/en-us/web/api/publickeycredentialrequestoptions/index.md

@@ -0,0 +1,93 @@
+---
+title: PublicKeyCredentialRequestOptions
+slug: Web/API/PublicKeyCredentialRequestOptions
+page-type: web-api-interface
+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:.
+
+It is used to request a {{domxref("PublicKeyCredential")}} provided by an {{glossary("authenticator")}} that supports the [Web Authentication API](/en-US/docs/Web/API/Web_Authentication_API).
+
+## Instance properties
+
+- `allowCredentials` {{optional_inline}}
+
+  - : An array of objects used to restrict the list of acceptable credentials. An empty array indicates that any credential is acceptable.
+
+    Each object in the array 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.
+
+- `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}}

files/jsondata/GroupData.json

@@ -507,6 +507,7 @@
       ],
       "interfaces": [
         "IdentityCredential",
+        "IdentityCredentialRequestOptions",
         "IdentityProvider",
         "NavigatorLogin"
       ],
@@ -1859,6 +1860,7 @@
       "interfaces": [
         "PublicKeyCredential",
         "PublicKeyCredentialCreationOptions",
+        "PublicKeyCredentialRequestOptions",
         "AuthenticatorResponse",
         "AuthenticatorAttestationResponse",
         "AuthenticatorAssertionResponse"