Participate in a Federated Credential Management API origin trial for IdPs

Published on Updated on

Update, August 2022

  • Added an important security information. The identity provider (IdP) needs to check if the Referer header matches the origin the RP registered in advance on the ID token endpoint.

Starting from Chrome 105:

  • The top-level manifest is renamed from /.well-known/fedcm.json to /.well-known/web-identity and the URL specified in provider_urls should be full manifest URLs rather than paths.
  • APIs login(), logout() and revoke() on FederatedCredential instance are no longer available.
  • Use IdentityCredential instead of FederatedCredential.
  • Move login functionality to navigator.credentials.get().
  • Revocation endpoint in the manifest is no longer in effect.
  • Use identity type instead of federated type for navigator.credentials.get() call.
  • url is now configURL and must be a full URL of the manifest JSON file instead of a path for navigator.credentials.get() call.
  • nonce is now an optional parameter for navigator.credentials.get() call.
  • hint is no longer available as an option for navigator.credentials.get() call.
const credential = await navigator.credentials.get({
identity: {
providers: [{
configURL: 'https://idp.example/anything.json',
clientId: '********',
nonce: '******'
const { token } = credential;

Update, June 2022

Starting Chrome 104:

  • consent_acquired parameter sent to the ID token endpoint is now disclosure_text_shown. The value is unchanged.
  • branding icons stop supporting SVG images.

Update, May 2022

Starting Chrome 103, FedCM:

  • Supports desktop environments.
  • Supports per RP settings on desktop.
  • The client metadata endpoint is now optional.
    • In this endpoint, the privacy policy URL is also optional.
  • No longer supports SVG images as an icon in the IdP manifest.

Also added a caveat about using CSP connect-src.

Over the last decade, identity federation has played a central role in raising the bar for authentication on the web, in terms of ease-of-use (such as password-less single sign-in), security (such as improved resistance to phishing and credential stuffing attacks) and trustworthiness compared to per-site usernames and passwords. With identity federation, a RP (relying party) relies on an IDP (identity provider) to provide the user an account without requiring a new username and password.

Key Term

Identity federation delegates authentication or authorization of an individual (user or entity) to a trusted external party (an identity provider or IdP). The identity provider then allows the individual to sign in to a website (a relying party or RP).

Unfortunately, the mechanisms that identity federation was designed on (iframes, redirects and cookies) can also track users across the web. As the user agent can't differentiate between identity federation and tracking, this makes it difficult to determine when these mechanisms are being used to support identity federation.

The Federated Credential Management API (FedCM) provides a use case specific abstraction for federated identity flows on the web. This purpose-built API allows the browser to understand the context in which the RP and IdP exchange information, inform the user as to the information and privilege levels being shared and prevent unintended abuse.

This proposal is now available to test in the FedCM origin trial. To learn about high-level FedCM user journeys, read Federated Credential Management API.

Support and compatibility

FedCM is supported in:

  • Android: Google Chrome 101 and above
  • Desktop: Google Chrome 103 and above

FedCM isn't supported by other browsers yet, but the WebKit team has expressed general support and interest in working together on the FedCM proposal.

Who should use FedCM?

We expect FedCM to be useful to you only if all these conditions apply:

  1. You're an identity provider (IdP).
  2. You're affected by the third-party cookie phase out.
  3. Your RPs are third-parties. If your RPs are SameParty, you may be better served by First-Party Sets.

You're an IdP

FedCM requires support from an identity provider. A relying party cannot use FedCM independently. If you are a RP, you can ask your IdP to provide instructions.

You're affected by the third-party cookie phase out

Simulate third-party cookie phase-out by configuring Chrome to block them
Simulate third-party cookie phase-out by configuring Chrome to block them

You should only use FedCM if your current integration is affected by the third-party cookie phase out. If you're not affected, you should not use FedCM.

If you're unsure if your identity federation will continue to work after Chrome's third-party cookie phase out, you can test the effect on a website with your integration in Incognito mode. Alternatively, you can block third-party cookies on desktop at chrome://settings/cookies or on mobile by navigating to Settings > Site settings > Cookies.

If there is no discoverable impact on your identity federation without third-party cookies, you can continue using your current integration without FedCM.

If you aren't sure what to check for, read more about the known features that the phase-out is expected to affect.

Your RPs are third-parties

If you're an identity provider whose RPs are within the same party as your IdP, we expect First-Party Sets may be a better option. First-Party Sets allow related domain names owned and operated by the same entity to declare themselves as belonging to the same first-party. This allows the same party’s third-party cookies to work, even after third-party cookie phase-out.

First-Party Sets can't always be used. However, if your RPs are SameParty, consider using First-Party Sets.

How can identity providers test FedCM?

You need a secure context (HTTPS or localhost) on Chrome to use the Federated Credential Management API. FedCM is currently disabled by default on Chrome. Start with:

  1. Local development and tests by flipping a flag at chrome://flags.
  2. Once you're ready to test in production, you can sign up for the FedCM origin trial.

Develop and test locally with a flag

Set a browser flag to develop locally, here is how:

  1. Open Google Chrome. In the address bar, enter chrome://version. Confirm the browser version is 101 or higher.
  2. Go to chrome://flags#fedcm to enable FedCM.
  3. Restart your browser.

Detect whether FedCM is available

Once the flag is turned on, you can try the FedCM API.

FedCM on localhost doesn't require a secure context (HTTPS).

First, you need to confirm that FedCM is available before actually using it. To check if FedCM is available, wrap this code around your FedCM implementation:

if ('IdentityCredential' in window) {
// If the feature is available, take action

Debug code on Chrome on Android

Set up and run a server locally to debug your FedCM code. You can access this server in Chrome on an Android device connected using a USB cable with port forwarding.

You can use DevTools on desktop to debug Chrome on Android by following the instructions at Remote debug Android devices.

Use the FedCM API

You integrate with FedCM by creating a manifest and endpoints for client metadata, accounts list, and token issuance.

From there, FedCM exposes JavaScript APIs that RPs can use to sign in from the IdP.

Create an IdP manifest and endpoints

The IdP manifest provides a list of required endpoints for the browser. IdPs will host this manifest and the required endpoints.

The manifest file's URL is determined by the values provided to the navigator.credentials.get call executed on an RP.

const credential = await navigator.credentials.get({
identity: {
providers: [{
configURL: 'https://idp.example/anything.json',
clientId: '********',
nonce: '******'
const { token } = credential;

Specify a full URL of the IdP manifest file location as a configURL. When navigator.credentials.get() is called on the RP, the browser fetches the manifest file with a GET request without the Referer header. The request doesn’t have cookies and doesn’t follow redirects. This effectively prevents the IdP from learning who made the request and which RP is attempting to connect. For example:

GET /anything.json HTTP/1.1
Host: idp.example
Accept: application/json
Sec-FedCM-CSRF: ?1

All requests sent from the browser via FedCM include a Sec-FedCM-CSRF header to prevent CSRF attacks. All IdP endpoints must confirm this header exists with Sec-FedCM-CSRF: ?1.

The browser expects a JSON response from the IdP which includes the following properties:

accounts_endpoint (required)URL for the accounts list endpoint.
client_metadata_endpoint (optional)URL for the client metadata endpoint.
id_token_endpoint (required)URL for the ID token endpoint.
branding (optional)Object which contains various branding options.
branding.background_color (optional)Background color of the "Continue as..." button. Use the relevant CSS syntax, namely hex-color, hsl(), rgb(), or named-color.
branding.color (optional)Branding option which sets the background color of the "Continue as..." button. Use the relevant CSS syntax, namely hex-color, hsl(), rgb(), or named-color.
branding.icons (optional)Branding option which sets the icon object, displayed in the sign-in dialog. The icon object is an array with two parameters:
  • url (required): URL of the icon image. This does not support SVG images.
  • size (optional): icon dimensions, assumed by the application to be square and single resolution. This number must be greater or equal to 25.
How branding is applied to the FedCM dialog

Here's an example response body from the IdP:

"accounts_endpoint": "/accounts.php",
"client_metadata_endpoint": "/metadata.php",
"id_token_endpoint": "/idtokens.php",
"branding": {
"background_color": "green",
"color": "0xFFEEAA",
"icons": [{
"url": "https://idp.example/icon.ico",
"size": 25

Once the browser fetches the manifest, it sends subsequent requests to the IdP endpoints:

IdP endpoints

If the RP deploys Content Security Policy (CSP) on the page FedCM is called and enforce connect-src directive, they must explicitly allow endpoints and icon image URLs described in the manifest.

Top level domain manifest

To prevent trackers from abusing the API, an additional manifest file must be served from /.well-known/web-identity of eTLD+1 of the IdP.

For example, if an IdP serves an IdP Manifest at https://accounts.idp.example/sub/anything.json, they must also serve a top-level domain manifest at https://idp.example/.well-known/web-identity with the following content:

"provider_urls": ["https://accounts.idp.example/sub/anything.json"]

The JSON file must contain the provider_urls property with an array of URL strings that can be specified as a path part of configURL in navigator.credentials.get by RPs. The number of URL strings in the array is limited to one, but this may change with your feedback in the future.

Client metadata endpoint

The IdP's client metadata endpoint returns the relying party’s metadata such as the RP's privacy policy and terms of service. RPs should provide links to their privacy policy and terms of service to the IdP in advance. These links are displayed in the sign-in dialog when the user hasn't registered with the RP yet.

The browser sends a GET request using the client_id navigator.credentials.get without cookies. For example:

GET /metadata.php?client_id=1234 HTTP/1.1
Host: idp.example
Referer: https://rp.example/
Accept: application/json
Sec-FedCM-CSRF: ?1

The properties for the client metadata endpoint include:

privacy_policy_url (optional)RP privacy policy URL.
terms_of_service_url (optional)RP terms of service URL.

The browser expects a JSON response from the endpoint:

"privacy_policy_url": "https://rp.example/privacy_policy.html",
"terms_of_service_url": "https://rp.example/terms_of_service.html",

The returned client metadata is consumed by the browser and will not be available to the RP.

Accounts list endpoint

The IdP's accounts list endpoint returns a list of accounts that the user is currently signed in on the IdP. If the IdP supports multiple accounts, this endpoint will return all signed in accounts.

The browser sends a GET request with cookies, but without a client_id parameter and the Referer header. This effectively prevents the IdP from learning which RP the user is trying to sign in to. For example:

GET /accounts.php HTTP/1.1
Host: idp.example
Accept: application/json
Cookie: 0x23223
Sec-FedCM-CSRF: ?1

The browser expects a JSON response that includes an accounts property with an array of account information with following properties:

id (required)Unique ID of the user.
name (required)Given and family name of the user.
email (required)Email address of the user
given_name (optional)Given name of the user.
picture (optional)URL of the user avatar image
approved_clients (optional)An array of RP client IDs which the user has registered with

Example response body:

"accounts": [{
"id": "1234",
"given_name": "John",
"name": "John Doe",
"email": "john_doe@idp.example",
"picture": "https://idp.example/profile/123",
"approved_clients": ["123", "456", "789"],
}, {
"id": "5678",
"given_name": "Johnny",
"name": "Johnny",
"email": "johnny@idp.example",
"picture": "https://idp.example/profile/456"
"approved_clients": ["abc", "def", "ghi"],

If the user is not signed in, respond with HTTP 401 (Unauthorized).

The returned accounts list is consumed by the browser and will not be available to the RP.

ID token endpoint

The IdP's ID token endpoint returns a token for their signed-in user. When the user signs in to an RP website using navigator.credentials.get() call, the browser sends a POST request with cookies and a content type of application/x-www-form-urlencoded to this endpoint with the following information:

client_id (required)The RP's client identifier.
account_id (required)The unique ID of the signing in user.
nonce (optional)The request nonce, provided by the RP.
disclosure_text_shownResults in a string of true or false (rather than a boolean). The result is false if the RP's client ID was included in the approved_clients property list and the sign-in dialog displayed both the privacy policy and the terms of service.

Example HTTP header:

POST /idtokens.php HTTP/1.1
Host: idp.example
Referer: https://rp.example/
Content-Type: application/x-www-form-urlencoded
Cookie: 0x23223
Sec-FedCM-CSRF: ?1

On the server, the IdP should confirm that:

  1. The claimed account ID matches the ID for the account that is already signed in.
  2. The Referer header matches the origin the RP, registered in advance for the given client ID.

Since the domain verification on OAuth or OpenID Connect relies on a browser redirect, it's critical in FedCM that the IdP server checks a Referer header value matches the RP's registered origin.

The browser expects a JSON response that includes the following property:

token (required)A token is a string that contains claims about the authentication.
"token": "eyJ********"

The returned token is passed to the RP by the browser, so that the RP can validate the authentication.

Sign in to the identity provider from the relying party

Once the IdP’s configuration and endpoints are available, RPs can call navigator.credentials.get() to request allowing users to sign in to the IdP from the RP.

For example:

const credential = await navigator.credentials.get({
identity: {
providers: [{
configURL: 'https://idp.example/anything.json',
clientId: '********',
nonce: '******'
const { token } = credential;

The providers property takes an array of IdentityProvider objects that must have the following properties:

configURL (required)A full path of the IdP manifest file.
clientId (required)The RP's client identifier, issued by the IdP.
nonce (optional)A random string to ensure the response is issued for this specific request. Prevents replay attacks.
signal (optional)An AbortSignal for the RP to terminate the request arbitrarily.

The browser handles sign-up and sign-in use cases differently depending on the existence of approved_clients in the response from the accounts list endpoint. The browser will only display the RP's privacy policy and terms of service in the dialog if approved_clients isn't provided or does not include the RP's clientId and the user hasn't previously signed p for the RP in this browser.

A user signs into an RP using FedCM

When the RP calls navigator.credentials.get(), the following activities take place:

  1. The browser sends requests and fetches several documents:
    1. An IdP manifest which stores declared endpoints.
    2. URLs for the RP's privacy policy and terms of service, retrieved from the client metadata endpoint.
    3. An accounts list.
  2. The browser displays the list of accounts that the user can use to sign-in, as well as the terms of service and privacy policy.
  3. Once the user chooses an account to sign in with, a request to the ID token endpoint is sent to the IdP to retrieve a token.
  4. The RP can validate the token to authenticate the user.
login API call

FedCM is designed to not inform the RP of the user's IdP sign-in state until the user explicitly confirms to Continue as and signs in. This means RPs aren't informed of connection to the FedCM API if: the user isn't signed into the IdP, the accounts list endpoint returns an empty list, or the endpoint returns an error.

RPs are expected to support browsers which don't support FedCM, therefore users should be able to use an existing, non-FedCM sign-in process. Until third-party cookies are phased out completely, this should remain non-problematic.

Once the token is validated by the RP server, the RP may register the user or let them sign-in and start a new session.

Test in production with the origin trial

Once you are satisfied with the API locally, the FedCM origin trial allows you to test and work with experimental features in production environments, with end users. You can activate FedCM without flags on a specified origin by participating in the FedCM origin trial.

Participate in a third-party OT to use FedCM on RPs

If your RPs are loading a JavaScript file or an SDK served from your IdP domain to orchestrate an identity federation, third-party origin trials offer you a scalable solution.

Check 'Third-party matching. The token will be injected by script on other origins.' checkbox.
Check Third-party matching. The token will be injected by script on other origins. checkbox.

To register for the third-party origin trial and activate FedCM on RPs:

  1. Go to the FedCM origin trial registration page.
  2. Click the Register button and fill out the form to request a token
  3. Enter the IdP's origin as Web Origin.
  4. Check Third-party matching to inject the token with JavaScript on other origins.
  5. Click Submit.
  6. Embed the issued token on the RP.

To embed the token to the RP, add the following code to your JavaScript library or SDK served from the registered IdP's origin.

const tokenElement = document.createElement('meta');
tokenElement.httpEquiv = 'origin-trial';
tokenElement.content = 'TOKEN_GOES_HERE';

Replace TOKEN_GOES_HERE with your own token.

The origin trial meta tag must be added before you add feature detection. Otherwise, the feature won't be available.

If FedCM is executed directly by an RP without loading an IdP's scripts, the RP must register their origin for the origin trial separately.

Next steps

Find out more

Last updated: Improve article

We serve cookies on this site to analyze traffic, remember your preferences, and optimize your experience.