Federated Credential Management API

A web API for privacy-preserving identity federation.

Published on Updated on

Translated to: 日本語

What is FedCM?

FedCM (Federated Credential Management) is a privacy-preserving approach to federated identity services (such as "Sign in with...") whereby users can log into sites without sharing their personal information with the identity service or the site.

Implementation status

Moving forward, we plan to introduce a number of new features based on the feedback we received from identity providers (IdP), relying parties (RP) and browser vendors. While we hope identity providers will adopt FedCM, please be aware that FedCM is still an API under active development and that backward incompatible changes are expected until Q4 2023.

To minimize the challenges of deploying backwards incompatible changes, we currently have two recommendations for identity providers:

  • Subscribe to our newsletter where we will send updates as the API evolves.
  • We encourage IdPs to distribute the FedCM API via JavaScript SDKs while the API is maturing, and to discourage RPs from self-hosting SDKs. This will ensure IdPs can make changes as the API evolves, without having to ask all of their relying parties to redeploy.

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 trustworthiness, ease-of-use (for example, passwordless single sign-in) and security (for example, improved resistance to phishing and credential stuffing attacks) compared to per-site usernames and passwords.

With identity federation, an 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 has relied on (iframes, redirects and cookies) are actively being abused to track users across the web. As the user agent isn’t able to differentiate between identity federation and tracking, the mitigations for the various types of abuse make the deployment of identity federation more difficult.

The Federated Credential Management API (FedCM) provides a use-case-specific abstraction for federated identity flows on the web, by exposing a browser mediated dialog that allows users to choose accounts from IdPs to login to websites.

FedCM is a multi-step journey to make identity on the web better, and in its first step we are focused on reducing the impact of third-party cookie phase-out on federated identity (see the Roadmap section to see a few steps further).

A user is signing to an RP using FedCM

What do we expect will be affected?

Caution

The aim of the Privacy Sandbox initiative is to mitigate all tracking vectors in Chrome. Our first step is to reduce the impact of third-party cookie phase-out which is already happening in other browsers, and is planned in Chrome for 2024. 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 Related Website Sets, formerly called First-Party Sets.

You're an IdP

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

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

You should only use FedCM if your current integration is affected by the third-party cookie phase out.

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 by blocking third-party cookies on Chrome.

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 Related Website Sets may be a better option. Related Website 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.

Related Website Sets can't always be used. However, if your RPs are SameParty, consider using Related Website Sets.

How will users interact with FedCM?

Currently, 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 settings.

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

Check out our demo to see how it works.

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 doesn't have an account on the RP with the IdP, a sign-up dialog appears with additional disclosure text such as the RP's terms of service and a privacy policy if they are provided.

The user can complete sign in by tapping Continue as.... If successful, the browser stores the fact that the user has created a federated account on the RP with the IdP.

If the user closes the UI manually, an entry would be added to the settings UI and the UI won't be displayed in the same website for a period of time. The UI will be reenabled after the period, but the duration will be exponentially expanded. Users can reenable FedCM on the RP manually by either going to the settings page or clicking on the PageInfo UI (a lock icon beside the URL bar) and reset the permission.

RPs are expected to work on 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.

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

Roadmap

We are working on landing a number of changes on the FedCM.

Several updates have already been applied based on feedback. And also it's expected to continue evolving until Q4 2023 at least to stabilize. Please see Updates for more details.

  • Change Log: Federated Credential Management API updates.

There are a few things we know that still need to be done, including issues we heard about from IdPs, RPs and browser vendors. We believe we know how to resolve these issues:

  • Cross-origin iframe support: IdPs can call FedCM from within a cross-origin iframe (update).
  • Personalized button: IdPs can display a returning user's identity on the sign-in button from within an IdP owned cross-origin iframe (update).
  • Metrics endpoint: Provides performance metrics to IdPs.

Additionally, there are unresolved issues we are actively exploring including specific proposals that we are evaluating or prototyping:

Finally, there are things we believe still need to be done, based on feedback from Mozilla, Apple and TAG reviewers. We are working to evaluate the best solutions for these open questions:

  • Improving user comprehension and matching intent: As Mozilla noted, we’d like to continue exploring different UX formulations and surface areas, as well as triggering criteria.
  • Identity Attributes and Selective Disclosure: As our TAG Reviewers noted, we’d like to provide a mechanism to selectively share more or less identity attributes (such as emails, age brackets, phone numbers, and so on).
  • Raising the Privacy Properties: As Mozilla suggested here, we’d like to continue exploring mechanisms to offer better privacy guarantees, such as IdP blindness, directed identifiers.
  • Relationship with WebAuthn: As suggested by Apple, we are super excited to see the progress on passkeys and to work on providing a coherent and cohesive experience between FedCM, Passwords, WebAuthn and WebOTP.
  • Login Status: As Apple suggested with the Privacy CG’s Login Status API, we share the intuition that the user’s login status is a useful bit of information that can help browsers make informed decisions, and we are excited to see what opportunities arise from that.
  • Enterprises and Education: As is clear at the FedID CG, there are still a lot of use cases that are not well served by FedCM that we’d like to work on, such as
    front-channel logout (the ability for an IdP to send a signal to RPs to logout) and support for SAML.
  • Relationship with mDLs/VCs/etc: continue working to understand how these fit within FedCM, for example with the Mobile Document Request API.

Using the FedCM API

You need a secure context (HTTPS or localhost) both on the IdP and RP in Chrome to use the FedCM.

To integrate with FedCM you need to create a well-known file, config file and endpoints for accounts list, assertion issuance and optionally client metadata. From there, FedCM exposes JavaScript APIs that RPs can use to sign in with the IdP.

To learn how to use the FedCM API check out the FedCM developer guide.

Engage and share feedback

Updated on Improve article

This site uses cookies to deliver and enhance the quality of its services and to analyze traffic. If you agree, cookies are also used to serve advertising and to personalize the content and advertisements that you see. Learn more about our use of cookies.