FedCM: Federated Credential Management API Overview for Developers

Introduction

FedCM (Federated Credential Management API) provides a browser-mediated approach to handling federated identity, allowing users to authenticate across multiple applications using a single set of credentials. This API enhances user privacy and convenience by putting the browser in a trusted intermediary role, improving the sign-in experience for all parties involved.

Configuration Checklist

Element	Version / Link
Language / Runtime	JavaScript (Web API)
Main library	navigator.credentials.get()
Required APIs	Identity Provider (IdP) specific endpoints
Browser Support	Chrome 147+ (with two UX modes)
Well-known file	/.well-known/web-identity

Step-by-Step Guide for Identity Providers

To enable FedCM, Identity Providers (IdPs) must implement specific server-side endpoints and optionally distribute an SDK for Relying Parties (RPs) to integrate.

Step 1 — Serve a Well-Known File

The IdP needs to serve a /.well-known/web-identity file. This file acts as a map, informing the browser where to find the IdP's FedCM configuration and required endpoints.

{
  "accounts_endpoint": "/auth/accounts",
  "login_url": "/"
}

Step 2 — Implement Required Endpoints

The IdP must implement several endpoints to handle the authentication flow:

• accounts_endpoint: This endpoint is responsible for listing the user's available accounts to the browser.
• id_assertion_endpoint: This endpoint verifies the user's identity and issues a secure token (e.g., an ID token) to log them in.
• login_url: This endpoint handles the sign-in page if the user is not currently authenticated with the IdP. It appears as a pop-up window in active mode.
• client_metadata: This endpoint provides branding elements, such as the Relying Party's logo or privacy policy, to the browser's UI for display in the FedCM dialog.

Step 3 — Integrate FedCM API on Relying Party

Relying Parties (RPs) integrate FedCM by calling the navigator.credentials.get() method, typically within an SDK provided by the IdP. This allows the IdP to manage future updates centrally without breaking the RP's flow.

// SDK sign-in method distributed by the Identity Provider
async function signin(options) {
  // [Editor's note: additional setup code might be present here]
  const credential = await navigator.credentials.get({
    identity: {
      providers: [
        {
          config: this.config, // Configuration object from the IdP
          clientId: this.clientId, // Client ID for the RP
          nonce: this.nonce, // Cryptographic nonce for security
          params: this.params, // Additional parameters if needed
        },
      ],
    },
  });
  // [Editor's note: further processing of the credential object]
  // e.g., send the credential to the RP's backend for verification
}

Comparison Tables

FedCM vs. Traditional Federated Identity Solutions

Feature	FedCM	iFrames / Third-Party Cookies
User Experience	One-tap sign-in (passive mode), no redirects	Often involves redirects, pop-ups, or less intuitive flows
Privacy	Browser mediates data exchange, delegation model enhances privacy, resilient to bounce tracking	Prone to bounce tracking, potential for cross-site tracking via third-party cookies
UI Clutter	Browser dynamically shows relevant accounts, less cluttered UI	RPs often display static lists of IdP login buttons
Sign-in Rates	Higher sign-in rates reported	Potentially lower due to friction and privacy concerns
Third-Party Cookies	Works without third-party cookies	Relies heavily on third-party cookies
Link Decorations	Does not rely on link decorations, resilient to bounce tracking mitigations	Can be vulnerable to link decoration-based tracking

⚠️ Common Mistakes & Pitfalls

1. Incomplete IdP Endpoint Implementation: Failing to correctly implement all required endpoints (accounts_endpoint, id_assertion_endpoint, login_url, client_metadata) will prevent FedCM from functioning correctly.
2. Misunderstanding UX Modes: Not distinguishing between Active and Passive modes can lead to incorrect integration. Active mode requires a user gesture, while Passive mode offers a streamlined experience only if the user is already signed into the IdP.
3. Lack of SDK Distribution: IdPs not distributing an SDK for RPs can lead to fragmented implementations and make future API updates more challenging to manage centrally.
4. Ignoring Privacy Implications: Developers might overlook the privacy benefits of FedCM and continue using less private methods, missing out on enhanced user trust and compliance with future privacy regulations.

Glossary

Federated Identity: A system that allows a user to log in to multiple independent applications or websites using a single set of credentials, typically managed by an external identity provider.
Identity Provider (IdP): A service that stores and manages digital identities and authenticates users, then provides this authentication to other services (Relying Parties).
Relying Party (RP): An application or website that relies on an Identity Provider to authenticate its users, rather than managing user credentials directly.

Key Takeaways

• FedCM is a browser-mediated API designed to improve the user experience and privacy of federated identity flows.
• The browser acts as a trusted intermediary, requesting user permission before sharing data between Relying Parties and Identity Providers.
• FedCM supports two UX modes: Active (requires user gesture, handles IdP login pop-ups) and Passive (streamlined one-tap sign-in for already authenticated users).
• It eliminates the need for redirects and is resilient to bounce tracking mitigations, offering better privacy than traditional methods like iframes or third-party cookies.
• For IdPs, implementation involves serving a well-known file and specific API endpoints (accounts_endpoint, id_assertion_endpoint, login_url, client_metadata).
• Relying Parties benefit from a less cluttered UI, potentially higher sign-in rates, and no reliance on third-party cookies.
• The FedCM team is actively developing the API, with a roadmap for future enhancements including IdP registration, better UX, automation, and metrics.

Resources

• FedCM Feedback: goo.gle/fedcm-feedback
• FedCM Documentation: goo.gle/fedcm
• FedCM Roadmap: goo.gle/fedcm-roadmap