FedCM updates: Multi IdP API on desktop, Button Mode API and Continuation Bundle for Chrome on Android origin trials

Natalia Markoborodova

From Chrome 128, the Multi-IdP API is starting an origin trial on desktop, and the Button Mode API and the Continuation bundle are starting an origin trial on Android. With the Multi IdP feature, developers can specify an array of multiple supported Identity providers in a single get() call. Button Mode API adds a new UI. With the Button Mode API, identity providers can use FedCM API even if their users don't have active IdP sessions upon the API call. The Continuation bundle consists of the Continuation API and the Parameters API, which enable an OAuth authorization flow-like experience involving an IdP-provided permission dialog. The bundle also includes other changes such as the Fields API, Multiple configURL, and Custom Account Labels.

Note: widget mode is the default UI mode shipped in FedCM. Learn more about the difference between widget and button modes.

Origin trial: Multi IdP API

The feature allows users to choose an account from a set of supported IdPs, and RPs benefit from higher sign in and sign up rates. If the user is logged in with multiple IdPs, they will be prompted to sign in to the RP using one of the IdPs.

A user is signing in with different IdPs using the multi-IdP API.

IdPs are prioritized based on the user's existing accounts and their associated timestamps.

• If the user has previously logged into the RP with a specific IdP (i.e., they have a "returning account"), those IdPs will be listed first.
• Within the returning accounts, the IdPs are further sorted by the timestamp of their most recent use, with the most recently used IdP appearing at the top of the list. In some cases, Chrome might not have timestamp data for a returning account. This is likely because the user signed in before timestamp logs were implemented in FedCM. These accounts are listed below the ones that have timestamps.
• If the user has no returning accounts with any IdPs, the RP provided order is respected.

FedCM allows auto re-authentication if the developer requests it, and if there is a single returning account. In the case of Multi IdP, if returning accounts exist for multiple IdPs, the user won't be automatically re-authenticated. Having a returning account is a strong requirement for auto-reauthentication. The browser will only initiate auto re-authentication when the browser has explicitly recognized the account. This implies the user must have previously used FedCM with this specific account on this RP.

If the user's login status is set to logged-out for an IdP, calling the FedCM does not fetch accounts for that IdP. Similarly, if the user's status is logged-out for all the available IdPs, the FedCM sign-in prompt is not shown automatically in the widget mode.

If the login status saved in the browser for an IdP was logged-in, but no accounts for this IdP were returned by the fetch request (for example, if the user session expired, but the login status hasn't yet been updated by the browser), the mismatch UI is shown for the IdP, suggesting the user to sign in with the mismatching IdP.

When the user's login status is logged-in, but the session has expired, the mismatch UI is displayed.

Note: Multi IdP feature is only integrated with the widget mode. During the origin trial, the Multi IdP feature won't work with the button mode.

For more information on login in status, check the documentation. See developer guide for more implementation details.

Origin trial: Multi IdP API

You can try Multi IdP API as a user on the demo RP, or as a developer using Chrome 128 or newer.

Try it out as a user

Try it out yourself as a user. Make sure that:

• Chrome is not configured to block third-party sign-in prompts on the page: chrome://settings/content/federatedIdentityApi.
• You're signed in multiple demo IdPs. Follow the instructions on the demo page.

Note that to try Multi-IdP on sites whose origin is not registered for the origin trial, you need to enable the feature flag under chrome://flags/#fedcm-multi-idp.

Try it out as a developer

If a login provider has a Javascript SDK embedded on the RP (recommended), the navigator.credentials.get() call to enable multiple IdPs can be implemented by the provider, and the RP developers don't need to change their code. Otherwise, the RP needs to call the FedCM API themselves.

To test the Multi IdPs on an RP, specify the array of supported providers as follows:

try {
  const cred = await navigator.credentials.get({
    identity: {
      providers: [
        {
          configUrl: "https://idp1.example/foo.json", // first IdP
          clientId: "123",
        },
        {
          configUrl: "https://idp2.example/bar.json", // second IdP
          clientId: "456",
        }
      ]
    }
  });

  const token = cred.token;
  const currentConfigFileUrl = cred.configURL;

  if (cred.configURL === 'https://idp1.example/foo.json')  {
    // handle the token for idp1.example
  } else if (cred.configURL === 'https://idp2.example/bar.json') {
    // handle the token for idp2.example
  }
} catch (error) {
  console.error("Error during credential retrieval:", error);
}

The configURL attribute within the resulting object stores the URL of the configuration file for the IdP that the user authenticated with. The RP can determine how to handle the resulting token as it differs depending on the IdP.

Note: FedCM only allows a single navigator.credentials.get() request at a time. Any subsequent requests will fail until the first one is resolved. You need to specify all the IdPs in an array in a single call. Support for multi-get FedCM dialogs is planned for the future.

Participate in the origin trial

Origin trials allow you to try new features and give feedback on their usability, practicality, and effectiveness. For more information, check out the Get started with origin trials.

You can try the Multi IdP feature by registering for the origin trials starting from Chrome 128.

To try Multi IdP, an RP can register their origin and run a first-party origin trial. It is also possible for the IdP to register for a third-party origin trial and have the Multi IdP feature available for all their RPs using Javascript SDKs.

Steps to participate in the origin trial:

1. Go to the Multi IdP API origin trial registration page.
2. Click the Register button and fill out the form to request a token.
3. To register for a first-party origin trial, enter the RP's origin in the "Web Origin" field. For a third-party origin trial, enter the origin of the IdP's JavaScript SDK and check the "Third-party matching" box.
4. Click Submit.
5. Provide the issued token on the RP page:
   • For 1P origin trial participants:
     • As a meta tag in the <head>: <meta http-equiv="origin-trial" content="TOKEN_GOES_HERE">
     • As an HTTP header: Origin-Trial: TOKEN_GOES_HERE
   • For third-party origin trial participants:
     • By providing a token programmatically.

Button Mode API for Chrome on Android

From Chrome version 128, the origin trial of the Button Mode API will begin on Chrome on Android, following its initial trial on desktop. With the Button Mode API, identity providers can use FedCM API even if their users are logged out of the IdP upon the API call. The sign-in flow is initiated by a user gesture, which better reflects the user's intention.

In Chrome 128, a new feature is introduced that allows IdPs to include the RP's official logo icon directly in the client metadata endpoint response. This enhances the UI on mobile devices in button mode.

Similar to the IdP branding in the config file, the RP's icons can be configured on the IdP side and returned in the client_metadata_endpoint response as follows:

  "privacy_policy_url": "https://rp.example/privacy_policy.html",
  "terms_of_service_url": "https://rp.example/terms_of_service.html",
  "icons": [{
      "url": "https://idp.example/rp-icon.ico",
      "size": 40
   }]

The IdP's and RP's logo icons in the disclosure UI on mobile.

To learn more about icons support, check the developer documentation.

Note: Passing an RP logo icon to the browser is optional. If the RP icon is not present, Chrome will only show the IdP logo on the disclosure UI where the user is asked for sharing permission. The new UI is only available on Android in Chrome 128 and newer, and a similar UI affordance will be applied to the desktop in later milestones.

If the user is not yet signed in, FedCM prompts the user to sign in to the IdP using the login_url provided by the IdP through a Chrome Custom Tab (CCT).

A user is signing in through button mode on mobile.

If the user is re-authenticating with a returning account, the disclosure UI won't be displayed.

A user is signing in with a returning account. The disclosure UI is not displayed.

To register for the origin trial, see the instructions for the Button Mode API on desktop. If you have already signed up for the origin trial on desktop, the feature will automatically be available for you on Chrome on Android starting from Chrome 128.

Continuation API bundle for Chrome on Android

From Chrome version 128, the Continuation API bundle will be available for Chrome on Android as part of an origin trial, following its initial trial on desktop. The bundle consists of multiple FedCM features, including Continuation API, Parameters API, Fields API, Multiple configURLs, and Custom Account Labels.

The Continuation API enables multi-step sign-in flows. The Parameters API allows passing additional parameters to the IdP. The Fields API lets the RP request specific account attributes for disclosure UI in the FedCM dialog. Additionally, Multiple configURL support multiple config files for an IdP, and Custom Account Labels allow IdPs to annotate accounts so that RPs can filter them by these labels.

To learn more about the Continuation API bundle, see the blog post on the Continuation API bundle on desktop. To register for the origin trial, follow these instructions. If you have already signed up for the origin trial on desktop, the features will automatically be available for you on Chrome on Android starting from Chrome 128.

Engage and share feedback

If you have feedback or encounter any problems, you can file an issue. We will keep the canonical FedCM developer guide up to date, along with the accumulated update logs page.