Add fedcm docs

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

@@ -4,7 +4,7 @@ slug: Glossary/Challenge
 page-type: glossary-definition
 ---
 
-In security protocols, a _challenge_ is some data sent to the client by the server in order to generate a different response each time. Challenge-response protocols are one way to fight against [replay attacks](https://en.wikipedia.org/wiki/Replay_attack) where an attacker listens to the previous messages and resends them at a later time to get the same credentials as the original message.
+In security protocols, a _challenge_ is some data sent to the client by the server in order to generate a different response each time. Challenge-response protocols are one way to fight against {{glossary("replay attack", "replay attacks")}} where an attacker listens to the previous messages and resends them at a later time to get the same credentials as the original message.
 
 The [HTTP authentication protocol](/en-US/docs/Web/HTTP/Authentication) is challenge-response based, though the "Basic" protocol isn't using a real challenge (the realm is always the same).
 

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

@@ -0,0 +1,14 @@
+---
+title: Replay attack
+slug: Glossary/Replay_attack
+tags:
+  - Security
+---
+
+In web security, a _replay attack_ is when an attacker intercepts a previously-sent message and resends it later to get the same credentials as the original message, potentially with a different payload or instruction.
+
+Replay attacks can be prevented by including a unique, single-use identifier with each message that the receiver can use to verify the authenticity of the transmission. This identifier can take the form of a session token or "number used only once" ("nonce").
+
+## See also
+
+- [Replay attack](https://en.wikipedia.org/wiki/Replay_attack) on Wikipedia.

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

@@ -7,13 +7,14 @@ browser-compat: api.Credential
 
 {{APIRef("Credential Management API")}}{{securecontext_header}}
 
-The **`Credential`** interface of the [Credential Management API](/en-US/docs/Web/API/Credential_Management_API) provides information about an entity (usually a user) as a prerequisite to a trust decision.
+The **`Credential`** interface of the [Credential Management API](/en-US/docs/Web/API/Credential_Management_API) provides information about an entity (usually a user) normally as a prerequisite to a trust decision.
 
-`Credential` objects may be of 3 different types:
+`Credential` objects may be of four different types:
 
+- {{domxref("FederatedCredential")}}
+- {{domxref("IdentityCredential")}}
 - {{domxref("PasswordCredential")}}
 - {{domxref("PublicKeyCredential")}}
-- {{domxref("FederatedCredential")}}
 
 ## Instance properties
 

files/en-us/web/api/credentialscontainer/get/index.md

@@ -9,22 +9,15 @@ browser-compat: api.CredentialsContainer.get
 
 The **`get()`** method of the
 {{domxref("CredentialsContainer")}} interface returns a {{jsxref("Promise")}} to a
-single {{domxref("Credential")}} instance that matches the provided parameters. If no
-match is found the Promise will resolve to null.
+single {{domxref("Credential")}} instance that matches the provided parameters.
 
 This method first collects all credentials in the {{domxref("CredentialsContainer")}}
 that meet the necessary criteria (defined in the **`options`**
 argument). From the resulting set of credentials, it then selects the best one.
 Depending on the options, it may display a dialog to the user and ask the user to make
 the selection.
 
-This method collects credentials by calling the "CollectFromCredentialStore" method for
-each credential type allowed by the **`options`** argument. For
-example: if options.password exists, then the
-{{domxref("PasswordCredential")}}.\[\[CollectFromCredentialStore]] is called.
-
-> **Note:** This method is restricted to top-level contexts. Calls to it within an
-> `<iframe>` element will resolve without effect.
+> **Note:** Usage of this feature may be blocked by an {{httpheader("Permissions-Policy/identity-credentials-get", "identity-credentials-get")}} or {{HTTPHeader("Permissions-Policy/publickey-credentials-get","publickey-credentials-get")}} [Permissions Policy](/en-US/docs/Web/HTTP/Permissions_Policy) set on your server.
 
 ## Syntax
 
@@ -37,28 +30,36 @@ get(options)
 
 - `options` {{optional_inline}}
 
-  - : An object of type {{domxref("CredentialRequestOptions")}} that contains options for
+  - : An object that contains options for
     the request. The options include criteria that the credentials are required or allowed
     to have, and options for interacting with the user. It can contain the following
     properties:
 
-    - `password`
+    - `password` {{optional_inline}}
       - : a boolean value indicating that returned
         {{domxref("Credential")}} instances should include user (as opposed to federated)
         credentials.
-    - `federated`
+    - `federated` {{optional_inline}}
 
       - : An object containing requirements for returned federated credentials. The available
         options are:
 
         - `providers`
           - : An array of string instances of
             identity providers to search for.
-        - `protocols`
-          - : An array of string instances of
-            federation protocols to search for.
 
-    - `publicKey`
+    - `identity` {{optional_inline}}
+
+      - : An object containing details of federated identity providers (IdPs) that a relying party (RP) website can use to sign users in. Causes a `get()` call to initiate a request for a user to sign in to a RP with an IdP (see [Federated Credential Management API (FedCM)](/en-US/docs/Web/API/FedCM_API)). `identity` can contain a single property, `providers`, which contains an array of objects each specifying the details of a separate IdP:
+
+        - `configURL`
+          - : A string specifying the URL of the IdP's config file. See [Provide a config file](/en-US/docs/Web/API/FedCM_API#provide_a_config_file) for more information.
+        - `clientId`
+          - : A string specifying the the RP's client identifier, issued by the IdP to the RP in a completely separate process specific to the IdP.
+        - `nonce` {{optional_inline}}
+          - : A random string that can be included to ensure the response is issued for this specific request, and prevent {{glossary("replay attack", "replay attacks")}}.
+
+    - `publicKey` {{optional_inline}}
       - : An object containing requirements for returned [WebAuthn](/en-US/docs/Web/API/Web_Authentication_API) credentials. The available options are:
         - `challenge`
           - : An {{jsxref("ArrayBuffer")}}, a {{jsxref("TypedArray")}}, or a {{jsxref("DataView")}} emitted by 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 {{domxref("AuthenticatorAssertionResponse.signature")}}.
@@ -72,15 +73,15 @@ get(options)
           - : A string qualifying how the user verification should be part of the authentication process.
         - `extensions` {{optional_inline}}
           - : An object with several client extensions' inputs. Those extensions are used to request additional processing (e.g. dealing with legacy FIDO APIs credentials, prompting a specific text on the authenticator, etc.).
-    - `mediation`
+    - `mediation` {{optional_inline}}
       - : A {{jsxref("String")}} indicating whether the user will
         be required to log on for every visit to the website. Valid values are
         `"silent"`, `"optional"`, `"conditional"`, or `"required"`.
-    - `unmediated` {{deprecated_inline}}
+    - `unmediated` {{optional_inline}} {{deprecated_inline}}
       - : A boolean value
         indicating the returned {{domxref("Credential")}} instance should not require user
         mediation.
-    - `signal`
+    - `signal` {{optional_inline}}
       - : An instance of {{domxref("AbortSignal")}} that can indicate
         that an ongoing `get()` operation should be halted. An aborted
         operation may complete normally (generally if the abort was received after the
@@ -90,13 +91,39 @@ get(options)
 ### Return value
 
 A {{jsxref("Promise")}} that resolves with a {{domxref("Credential")}} instance that
-matches the provided parameters. If a single Credential cannot be unambiguously
-obtained, the Promise will resolve to null.
+matches the provided parameters. If a single credential cannot be unambiguously
+obtained, the Promise will resolve to `null`.
 
 ### Exceptions
 
+- `NetworkError` {{domxref("DOMException")}}
+  - : In the case of a `get()` call with an `identity` option, this exception is thrown if the IdP does not respond within 60 seconds, or if the provided credentials are not valid/found.
+- `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).
 - `SecurityError` {{domxref("DOMException")}}
-  - : Use of this feature was blocked by a [Permissions Policy](/en-US/docs/Web/HTTP/Permissions_Policy).
+  - : Use of this feature was blocked by a {{HTTPHeader("Permissions-Policy/publickey-credentials-get","publickey-credentials-get")}} [Permissions Policy](/en-US/docs/Web/HTTP/Permissions_Policy).
+
+## Examples
+
+### Relying party sign-in using the FedCM API
+
+Relying parties (RPs) can call `navigator.credentials.get()` with the `identity` option to make a request for users to sign in to the RP via an identity provider (IdP), using identity federation. A typical request would look like this:
+
+```js
+async function signIn() {
+  const identityCredential = await navigator.credentials.get({
+    identity: {
+      providers: [{
+        configURL: 'https://accounts.idp.example/config.json',
+        clientId: '********',
+        nonce: '******'
+      }]
+    }
+  });
+}
+```
+
+Check out [Federated Credential Management API (FedCM)](/en-US/docs/Web/API/FedCM_API#fedcm_sign-in_flow) for more details on how this works. This call will start off the sign-in flow described in [FedCM sign-in flow](http://localhost:5042/en-US/docs/Web/API/FedCM_API#fedcm_sign-in_flow).
 
 ## Specifications
 
@@ -108,5 +135,7 @@ obtained, the Promise will resolve to null.
 
 ## See also
 
-- {{HTTPHeader("Permissions-Policy")}} directive
-  {{HTTPHeader("Permissions-Policy/publickey-credentials-get","publickey-credentials-get")}}
+- [Federated Credential Management API (FedCM)](/en-US/docs/Web/API/FedCM_API)
+- {{HTTPHeader("Permissions-Policy")}} directives:
+  - {{HTTPHeader("Permissions-Policy/identity-credentials-get","identity-credentials-get")}}
+  - {{HTTPHeader("Permissions-Policy/publickey-credentials-get","publickey-credentials-get")}}