Federated Credential Management API

# 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

• 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, 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.

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

# What do we expect will be affected?

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:

• 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 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 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 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?

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.

• 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

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.

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

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

# 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:

• 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.
• 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 (update).

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

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