RPs can callnavigator.credentials.get() with anidentity option to request that a user signs in to the RP with an existing IdP account that they are already signed in to on the browser. The IdP identifies the RP by itsclientId, which was issued by the IdP to the RP in a separate process that is specific to the IdP. The IdP identifies the specific user using credentials (cookies) provided to the browser on login.

The method returns a promise that fulfills with anIdentityCredential object if the user identity is successfully validated by the IdP. This object contains a token that includes user identity information that has been signed with the IdP'sdigital certificate.

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.

If the user has never signed into the IdP or is logged out, theget() method rejects with an error and the RP can direct the user to the IdP login page to sign in or create an account.

A typical request might look like this:

async function signIn() {  const identityCredential = await navigator.credentials.get({    identity: {      context: "signup",      providers: [        {          configURL: "https://accounts.idp.example/config.json",          clientId: "********",          nonce: "******",          loginHint: "user1@example.com",        },      ],    },  });}

Theidentity.providers property takes an array containing a single object specifying the path to an IdP config file (configURL) and the RP's client identifier (clientId) issued by the IdP.

The example above also includes a couple of optional features:

• identity.context specifies the context in which the user is authenticating with FedCM. For example, is it a first-time signup for this account, or a sign-in with an existing account? The browser uses this information to vary the text in its FedCM UI to better suit the context.
• Thenonce property provides a random nonce value that ensures the response is issued for this specific request, preventingreplay attacks.
• TheloginHint property provides a hint about the account option(s) the browser should present for user sign-in. This hint is matched against thelogin_hints values that the IdP provides from theaccounts list endpoint.

The browser requests the IdP config file and carries out the sign-in flow detailed below. For more information on the kind of interaction a user might expect from the browser-supplied UI, seeSign in to the relying party with the identity provider.

There are three parties involved in the sign-in flow — the RP app, the browser itself, and the IdP. The following diagram summarizes what is happening visually.

The flow is as follows:

1. The RP invokesnavigator.credentials.get() to start off the sign-in flow.

2. From theconfigURL provided in theget() call, the browser requests two files:

   1. The well-known file (/.well-known/web-identity), available from/.well-known/web-identity at theeTLD+1 of theconfigURL.
   2. TheIdP config file (/config.json), available at theconfigURL.

   These are bothGET requests, which don't have cookies and don't follow redirects. This effectively prevents the IdP from learning who made the request and which RP is attempting to connect.

   All requests sent from the browser via FedCM include aSec-Fetch-Dest: webidentity header to preventCSRF attacks. All IdP endpoints must confirm this header is included.

3. The IdP responds with the requested well-known file andconfig.json files. The browser validates the config file URL in theget() request against the list of valid config URLs inside the well-known file.

4. If the browser has theIdP's login status set to"logged-in", it makes a credentialed request (i.e., with a cookie that identifies the user that is signed in) to theaccounts_endpoint inside the IdP config file for the user's account details. This is aGET request with cookies, but without aclient_id parameter or theOrigin header. This effectively prevents the IdP from learning which RP the user is trying to sign in to. As a result, the list of accounts returned is RP-agnostic.

   Note:If the IdP login status is"logged-out", theget() call rejects with aNetworkErrorDOMException and does not make a request to the IdP'saccounts_endpoint. In this case it is up to the developer to handle the flow, for example by prompting the user to go and sign in to a suitable IdP. Note that there may be some delay in the rejection to avoid leaking the IdP login status to the RP.

5. The IdP responds with the account information requested from theaccounts_endpoint. This is an array of all accounts associated with the user's IdP cookies for any RPs associated with the IdP.

6. Optional If included in the IdP config file, the browser makes an uncredentialed request to theclient_metadata_endpoint for the location of the RP terms of service and privacy policy pages. This is aGET request sent with theclientId passed into theget() call as a parameter, without cookies.

7. Optional The IdP responds with the URLs requested from theclient_metadata_endpoint.

8. The browser uses the information obtained by the previous two requests to create the UI asking the user to choose an account to sign in to the RP with (in the case where there is more than one available). The UI also asks the user for permission to sign in to the RP using their chosen federated IdP account.

   Note:At this stage, if the user has previously authenticated with a federated RP account in the current browser instance (i.e., created a new account with the RP or signed into the RP's website using an existing account), they may be able toauto-reauthenticate, depending on what themediation option is set to in theget() call. If so the user will be signed in automatically without entering their credentials, as soon asget() is invoked. See theAuto-reauthentication section for more details.

9. If the user grants permission to do so, the browser makes a credentialed request to theid_assertion_endpoint to request a validation token from the IdP for the selected account.

   The credentials are sent in an HTTPPOST request with cookies and a content type ofapplication/x-www-form-urlencoded.

   If the call fails, an error payload is returned as explained inID assertion error responses and the promise returned byget() will reject with the error.

10. The IdP checks that the account ID sent by the RP matches the ID for the account that is already signed in, and that theOrigin matches the origin of the RP, which will have been registered in advance with the IdP. If everything looks good, it responds with the requested validation token.

    Note:The origin of the RP will be registered with the IdP in a completely separate process when the RP first integrates with the IdP. This process will be specific to each IdP.

11. When the flow is complete, theget() promise resolves with anIdentityCredential object, which provides further RP functionality. Most notably, this object contains a token that the RP can verify comes from the IdP (using a certificate) and that contains trusted information about the signed in user. Once the RP validates the token, they can use the contained information to sign the user in and start a new session, sign them up to their service, etc. The format and structure of the token depends on the IdP and has nothing to do with the FedCM API (the RP needs to follow the IdP's instructions).

FedCM auto-reauthentication lets users reauthenticate automatically when they try to sign in to an RP again after their initial authentication using FedCM. "Initial authentication" refers to when the user creates an account or signs into the RP's website via the FedCM sign-in dialog for the first time on the RP site, on the same browser instance.

After the initial authentication, auto-reauthentication can be used to sign into the RP website again automatically, without needing to show the user a "Continue as..." confirmation prompt. If the user has recently granted permission to allow federated sign-in to occur with a particular account, there's no privacy or security benefit to immediately enforcing another explicit user confirmation.

Auto-reauthentication behavior is controlled by themediation option in theget() call:

async function signIn() {  const identityCredential = await navigator.credentials.get({    identity: {      providers: [        {          configURL: "https://accounts.idp.example/config.json",          clientId: "********",        },      ],    },    mediation: "optional", // this is the default  });  // isAutoSelected is true if auto-reauthentication occurred.  const isAutoSelected = identityCredential.isAutoSelected;}

Auto-reauthentication can occur ifmediation is set tooptional orsilent.

With thesemediation options, auto-reauthentication will occur under the following conditions:

• FedCM is available to use. For example, the user has not disabled FedCM either globally or in the RP's settings.
• The user has only used one account to sign into the RP website on this browser via FedCM.
• The user is signed into the IdP with that account.
• Auto-reauthentication didn't happen within the last 10 minutes. This restriction is put into place to stop users being auto-reauthenticated immediately after they sign out — which would make for a pretty confusing user experience.
• The RP hasn't calledpreventSilentAccess() after the previous sign in. This can be used by an RP to explicitly disable auto-reauthentication if desired.

When these conditions are met, an attempt to automatically reauthenticate the user starts as soon as theget() is invoked. If auto-reauthentication is successful, the user will log into the RP site again, without being shown a confirmation prompt, using the same IdP account and validated token as they did before.

If auto-reauthentication fails, the behavior depends on themediation value that was chosen:

• optional: the userwill be shown the dialog box and asked for confirmation again. As a result, this option tends to make sense to use on a page where a user journey is not in mid-flow, such an RP sign-in page.
• silent: Theget() promise will reject and the developer will need to handle guiding the user back to the sign-in page to start the process again. This option makes sense on pages where a user journey is in flow and you need to keep them signed in until completion, for example the pages of a checkout flow on an e-commerce website.

• Federated Credential Management API on privacysandbox.google.com (2023)