Participate in a Federated Credential Management API origin trial for IdPs

Published on

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

At this time, FedCM is supported in Google Chrome 101 and above on Android. It's not supported by other browsers yet, but the WebKit team has expressed general support and interest in working together on the FedCM proposal.

Chrome on desktop is planning to support FedCM within this origin trial period.

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 on Android to use the Federated Credential Management API. Initial testing is limited to Chrome on Android to assess feature stability, but we expect to expand to Chrome on desktop soon.

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

At this time, FedCM is only supported in Google Chrome 101 and above on Android.

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

  1. Open Google Chrome on an Android device.
  2. In the Chrome address bar, type chrome://version. Confirm the browser version is newer than 101.
  3. Go to chrome://flags#fedcm to enable FedCM.
  4. 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 (window.FederatedCredential || FederatedCredential.prototype.login) {
// 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.

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](#accounts-list-endpoint, ID token issuance, and token revocation.

From there, FedCM exposes JavaScript APIs that RPs can use to sign in, sign out, and revoke tokens 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({
federated: {
providers: [{
url: 'https://idp.example',
clientId: '********'
}]
}
})

For example, if the IdP url is specified as https://idp.example, the browser appends /fedcm.json to it to create the manifest URL: https://idp.example/fedcm.json. The url can include a path as well, for example https://idp.example/sub/ specifies a URL with a subdirectly. In this case, the manifest URL is https://idp.example/sub/fedcm.json.

When a FedCM login() is called on the RP, the browser fetches the manifest file with a GET request with 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 /fedcm.json HTTP/1.1
Host: idp.example
Accept: application/json
Sec-FedCM-CSRF: ?1
Caution

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:

PropertyDescription
accounts_endpoint (required)URL for the accounts list endpoint.
client_metadata_endpoint (required)URL for the client metadata endpoint.
id_token_endpoint (required)URL for the ID token endpoint.
revocation_endpoint (required)URL for the revocation 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.
  • size (optional): icon dimensions, assumed by the application to be square and single resolution.
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",
"revocation_endpoint": "/revocation.php",
"branding": {
"background_color": "green",
"color": "0xFFEEAA",
"icons": [{
"url": "https://idp.example/icon.ico",
"size": 10
}]
}
}

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

IdP endpoints

Top level domain manifest

Beginning in Chrome 102, this endpoint is required.

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

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

{
"provider_urls": ["https://accounts.idp.example/sub/"]
}

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

As of Chrome version 102, FedCM will not work without this manifest file.

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 /client_medata.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:

PropertyDescription
privacy_policy_url (required)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_list.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:

PropertyDescription
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 an ID token for their signed-in user. When the user signs in to an RP website using a FedCM login() 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:

PropertyDescription
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.
consent_acquiredResults 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 /fedcm_token_endpoint HTTP/1.1
Host: idp.example
Referer: https://rp.example/
Content-Type: application/x-www-form-urlencoded
Cookie: 0x23223
Sec-FedCM-CSRF: ?1
account_id=123&client_id=client1234&nonce=Ct60bD&consent_acquired=true

On the server, the IdP should confirm if the claimed account ID matches the ID for the account that is already signed in. The IdP should store the user's registration status for the RP to a database. This way, the IdP can revoke the token by changing the registration status via the revocation endpoint or by manually removing the database entry.

Revoking the IdP’s token by itself won't remove the user’s account on the RP.

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

PropertyDescription
id_token (required)IDToken is a security token (string) that contains claims about the authentication.
{
"id_token": "eyJ********"
}

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

Revocation endpoint

The IdP's revocation endpoint provides a way for RPs to revoke the user's tokens on the IdP. The URL of the revocation endpoint is declared by the manifest.

Once FedCM revoke() is called on the RP, the browser sends a POST request with cookies and a content type of application/x-www-form-urlencoded, along with the following properties:

PropertyDescription
client_id (required)The RP's client identifier.
hint (required)The user ID hint provided to the JavaScript call for revocation.

Example HTTP header:

POST /fedcm_revocation_endpoint HTTP/1.1
Host: idp.example
Referer: https://rp.example/
Content-Type: application/x-www-form-urlencoded
Cookie: 0x23223
Sec-FedCM-CSRF: ?1
client_id=client1234&hint=user@idp.example

On the server, the IdP should confirm if the hint matches one of the signed in users' ID (because FedCM supports multiple signed in users). The IdP should then revoke the token of the user by changing the registration status.

If successful, send an HTTP code 204 with an empty body.

Request the FedCM object for the relying party

Once the IdP’s configuration and endpoints are available, RPs can call navigator.credentials.get() to request the FederatedCredential object for the RP. With this object, the RP can:

For example:

const credential = await navigator.credentials.get({
federated: {
providers: [{
url: 'https://idp.example',
clientId: '********'
}]
}
})

FederatedCredential is an extension of the Credential Management API's FederatedCredential. These serve different purposes, but are designed with backwards compatibility.

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

PropertyDescription
url (required)The URL of the IdP.
clientId (required)The RP's client identifier, issued by the IdP.
hint (optional)A unique user ID that matches the one in the accounts list endpoint

This object provides the RP a method for users to sign-in, sign-out, or revoke tokens provided by the IdP.

Allow users to sign in

Call FederatedCredential.login() for both sign-up and sign-in dialogs. The browser handles these 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 and the user hasn't previously signed up for the RP in this browser.

const nonce = '15863786';
const { id_token } = await credential.login({ nonce });

The login() call takes the following properties:

PropertyDescription
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.
A user signs into an RP using FedCM

When the RP calls login(), 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 an ID token.
  4. The RP can validate the ID token to authenticate the user.
login API call
Caution

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 ID token is validated by the RP server, the RP may register the user or let them sign-in and start a new session.

Allow user sign out

TTo sign out a user from the RP, the initialized FederatedCredential object must include the account ID of the signed-in user as the hint property in addition to the IdP URL and the RP’s client ID. The account ID must match the ID returned by accounts list endpoint. Once a credential is returned, use the logout() call to let the user sign-out from the RP.

Sign-out process for FederatedCredential
const credential = await navigator.credentials.get({
federated: {
providers: [{
url: 'https://idp.example',
clientId: '********',
hint: 'john_doe@idp.example'
}]
}
});
await credential.logout();

The FedCM logout() call doesn't take any arguments. With this call, the browser clears the user's sign-in state, but session termination such as erasing a session cookie must be performed by the RP.

Revoke tokens for RP access

To allow revocation, the FederatedCredential object must include the IdP URL and the RP’s client ID. Once a credential is returned, use the revoke() call with the user ID to request the IdP to revoke the user's tokens.

const credential = await navigator.credentials.get({
federated: {
providers: [{
url: 'https://idp.example',
clientId: '********',
}]
}
});
await credential.revoke('john_doe@idp.example');

With this call, the browser sends a request to the revocation endpoint.

Revoke tokens with FederatedCredential

Once the returned promise is resolved, the user's tokens are revoked from the IdP.

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';
document.head.appendChild(tokenElement);

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.