Federated Credential Management API

A web API for privacy-preserving identity federation.

Published on Updated on

Translated to: 日本語

Implementation status

This document outlines a new proposal for identity federation: the Federated Credential Management API (FedCM).

Why do we need FedCM?

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 isn't able to 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.

What do we expect will be affected?

Caution

We aim to mitigate all tracking vectors on Chrome with the Privacy Sandbox initiative. Our first step is to reduce the impact of third-party cookie phase-out which is already happening on other browsers, and is planned in Chrome for 2023. While removing these cookies can help reduce third-party tracking, it also impacts other cross-site use cases.

Through community effort and our research, we learned there are a few identity federation related integrations that are affected by third-party cookie phase-out:

FedCM's first goal is to reduce the impact of third-party cookie phase-out on identity federation and above is a list of areas we expect to be affected. If there are any additional use cases that we've not listed, we encourage you to engage and share feedback.

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 indentity 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-party

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 will users interact with FedCM?

In the first origin trial, FedCM's primary focus is to mitigate the impact of third-party cookie phase-out. Users can enable or disable FedCM in Chrome's user sttings.

FedCM is designed to be protocol-agnostic and offers the following authentication-related functionalities.

Check out our demo to see how it works.

In the future, we hope to support more features, including:

  • Automatic sign-in
  • Authorization prompt
  • Access and refresh tokens
  • Front-channel logout: sign-out from the relying party (RP) initiated by the identity provider (IdP)
  • OpenID Connect (OIDC) session management
  • Cross-origin iframes
  • Personalized buttons

Sign in to a relying party

A user is signing to an RP using FedCM

When the user lands on the relying party (RP) website, a FedCM sign-in dialog will appear if the user is signed in to the IdP.

If the user hasn't signed in to the RP, a sign-up dialog appears with additional disclosure text such as the RP's terms of service (which is required) and a privacy policy (if provided).

The user can complete sign in by tapping Continue as.... If successful, the user's account status and the sign-in status is stored in the browser.

Caution

There is a known issue. If the user doesn't sign in with an IdP or if the session has expired, the FedCM dialog won't be displayed. Share feedback if you need this to be fixed.

RPs are expected to support browsers which don't support FedCM. Users should be able to use an existing, non-FedCM sign-in process. Learn more about how sign-in works in the FedCM origin trial.

Sign out from an RP

When the user signs out from the RP, FedCM clears the sign-in state from the browser.

Revoke tokens

The user may decide to revoke their tokens on the relying party (e.g. unregister from the relying party). The RP can use FedCM to request the IdP to revoke the user's tokens if the user is signed in to the IdP. At the same time, FedCM clears the sign-in state on the RP from the browser.

Setting to enable or disable FedCM

Users can enable or disable FedCM in settings on Chrome on Android. Go to Settings > Site settings > Third-party sign-in, then change the toggle.

Enable FedCM in Chrome Settings on mobile by toggling on Third-party sign-in

They can do the same for Chrome on desktop by going to chrome://settings/content/federatedIdentityApi.

Enable FedCM in Chrome Settings on desktop by toggling on Third-party sign-in

How can IdPs support FedCM?

Read detailed instructions on how to implement and participate in the third-party origin trial for FedCM for support details.

Engage and share feedback

Find out more

Last updated: Improve article

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