Federated Credential Management API overview

A web API for privacy-preserving identity federation.

What is FedCM?

FedCM (Federated Credential Management) is a privacy-preserving approach to federated identity services (such as "Sign in with...") that doesn't rely on third-party cookies or navigational redirects.

Implementation status

• Chrome Platform Status
• FedCM shipped in Chrome 108.
• The FedCM proposal is open for public discussion.
• FedCM isn't supported in other browsers yet.
  • Mozilla is implementing a prototype for Firefox and Apple has expressed general support and interest in working together on the FedCM proposal.

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, be aware that FedCM is still an API under active development.

To minimize the challenges of deploying backwards incompatible changes, we 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 using 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. In its first step we are focused on reducing the impact of third-party cookie restrictions on federated identity (see the Roadmap section for 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 restrictions. 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 restrictions:

• OpenID Connect Front-Channel Logout
• OpenID Connect Session Management
• Iframe-based background token renewal
• Iframe-based login widgets

FedCM's first goal is to reduce the impact of third-party cookie restrictions on identity federation, and these are the areas we expect to be affected. If there are additional use cases not listed, you can engage and share feedback.

FedCM as a trust signal for other APIs

Along with handling federated identity, FedCM also serves as a trust signal for other Privacy Sandbox APIs.

Starting from Chrome 131, the Storage Access API (SAA) uses FedCM as a trust signal. This integration is useful for the websites that rely on both FedCM for authentication and the SAA to enable cross-origin iframes to access necessary storage.

When a user authenticates with FedCM, with RP opt-in, the IdP's content embedded on the RP's website can call the requestStorageAccess() method to automatically get storage access to its own top-level cookies without needing an additional user prompt. The permission will be auto-granted only as long as the user is signed in with FedCM and the FedCM sign-in state is active. Read the Storage Access API documentation for more details.

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 restrictions.
3. Your RPs are third-party sites. If your RPs are meaningfully related sites, you may be better served by Related Website 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 restrictions

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

If you're unsure if your identity federation will continue to work when third-party cookies are not available, 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 third-party cookie restrictions are expected to affect.

Your RPs are third-party

If you're an identity provider whose RPs have a first-party relationship to IdP, we expect Related Website Sets may be a better option. Related Website Sets (RWS) is a way for an organization to declare relationships among sites, so that browsers allow limited third-party cookie access for specific purposes. This allows third-party cookies to work among sets of meaningfully related sites, even when third-party cookies are otherwise restricted.

How will users interact with FedCM?

FedCM's primary focus is to mitigate the impact of third-party cookie restrictions. 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.

• Use an identity provider to sign-in to a relying party

Check out our demo to see how it works.

Sign in to a relying party

A user signs into 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.

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.

Caution: The sign-in dialog enables users to sign in to an RP with their federated account, but shouldn't be relied upon as a consent under ePrivacy and data protection laws in the European Economic Area (EEA) and the UK. If you determine you need user consent under these laws for some of your data processing, (which could be because you are using API data for purposes beyond authentication, for example showing personalized ads to users), you must obtain that consent separately from the FedCM dialog. For more information, see the Compliance section, and our Privacy-related Compliance FAQs.

Settings 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.

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

Prompt cooldown period

If the user closes the UI manually, an entry would be temporarily 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 on consecutive closes. For example, in Chrome:

Consecutive times closed	Time period that FedCM prompt is suppressed
1	Two hours
2	One day
3	One week
4+	Four weeks

Other browsers may define their own, different, cooldown time periods.

Users can re-enable 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 resetting the permission.

Roadmap

We are working on landing a number of changes to FedCM. 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:

• CORS: We are discussing with Apple and Mozilla to ensure to improve the specification of FedCM fetches.
• Multiple-IdP API: We are exploring ways to support multiple IdPs to coexist cooperatively in the FedCM account chooser.
• IdP Sign-in Status API: Mozilla has identified a timing attack issue, and we are exploring ways for an IdP to proactively notify the browser of the user's sign-in status to mitigate the issue. (update)
• Sign in to IdP API: To support various scenarios, when a user is not signed in to the IdP, the browser provides a UI for the user to sign in without leaving the RP.

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 in its standards position, 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. (update)
• 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.

Use the FedCM API

You need a secure context (HTTPS or localhost) both on the IdP and RP in Chrome to use 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

• GitHub: Read the explainer, raise issues and follow discussion.
• Developer support: Ask questions and join discussions on the Privacy Sandbox Developer Support repo.

Compliance with ePrivacy laws

Using FedCM, either as an IdP or an RP, involves the storage of information on a user's terminal equipment or access to information already stored in it, and is therefore an activity subject to ePrivacy laws in the European Economic Area (EEA) and the UK generally requiring user consent. It is your responsibility to determine whether your use of FedCM is strictly necessary to provide an online service explicitly requested by the user, and therefore exempt from the consent requirement. For more information, we encourage you to read our Privacy Sandbox Privacy-related Compliance FAQs.