How to Configure Strict FedCM (Federated Credential Management) API in Google Chrome

Federated identity protocols (such as OpenID Connect and SAML) historically relied on third-party cookies and covert cross-site iframe navigations to track user session states and maintain single sign-on (SSO) across relying parties. As modern browsers restrict third-party storage access to eliminate passive cross-site tracking, traditional iframe-based identity federation breaks. The Federated Credential Management (FedCM) API introduces a privacy-preserving browser primitive in Google Chrome. By delegating user prompts directly to the browser UI, FedCM enables secure identity federation without exposing cross-site user data.

Understanding the FedCM Architecture and Trust Boundaries

FedCM alters the trust triangle between the Identity Provider (IdP), the Relying Party (RP), and the user agent:

• Browser Mediation: Rather than rendering hidden third-party iframes that read cross-site cookies, the relying party invokes navigator.credentials.get({ identity: ... }). Google Chrome directly queries the IdP’s metadata endpoints and renders an operating-system-level native sign-in dialog.
• Well-Known Configuration Endpoint: The IdP must host a standardized manifest file at /.well-known/web-identity to declare authorized configuration URLs and prevent rogue origin spoofing.
• Tracking Prevention: The IdP cannot observe which relying parties a user visits until the user explicitly selects an account within Chrome’s native dialogue, eliminating ambient cross-site fingerprinting.

Configuring the Identity Provider Endpoints

To enable FedCM integration, the Identity Provider must implement three primary JSON HTTP endpoints with strict CORS and Sec-Fetch-Dest: webidentity headers:

1. Well-Known Manifest (/.well-known/web-identity):

   {
     "provider_urls": ["https://idp.example.com/fedcm.json"]
   }

2. Configuration Manifest (/fedcm.json):

   {
     "accounts_endpoint": "/api/fedcm/accounts",
     "client_metadata_endpoint": "/api/fedcm/client_metadata",
     "id_assertion_endpoint": "/api/fedcm/assertion",
     "branding": {
       "background_color": "#0f172a",
       "color": "#ffffff",
       "icons": [
         {
           "url": "https://idp.example.com/icon.png",
           "size": 48
         }
       ]
     }
   }

3. Accounts Endpoint (/api/fedcm/accounts):

   Returns the currently authenticated user sessions. Must return HTTP 200 with credentials:

   {
     "accounts": [
       {
         "id": "usr_94821",
         "name": "Jane Doe",
         "email": "[email protected]",
         "given_name": "Jane",
         "picture": "https://idp.example.com/avatars/jane.jpg",
         "approved_clients": ["client_rp_992"]
       }
     ]
   }

Invoking FedCM on the Relying Party Website

The relying party initiates federated sign-in using standard asynchronous JavaScript:

async function signInWithFedCM() {
    if (!window.IdentityCredential) {
        console.warn("FedCM API is not supported in this browser.");
        // Fall back to standard full-page redirect flow
        window.location.href = "/auth/traditional-login";
        return;
    }

    try {
        const credential = await navigator.credentials.get({
            identity: {
                providers: [
                    {
                        configURL: "https://idp.example.com/fedcm.json",
                        clientId: "client_rp_992",
                        nonce: "random_cryptographic_nonce_772"
                    }
                ]
            }
        });

        // Send received identity token to server for JWT verification
        const response = await fetch("/api/auth/verify-fedcm-token", {
            method: "POST",
            headers: { "Content-Type": "application/json" },
            body: JSON.stringify({ token: credential.token })
        });

        const authResult = await response.json();
        if (authResult.authenticated) {
            window.location.reload();
        }
    } catch (err) {
        console.error("FedCM login failed or was dismissed by user:", err);
    }
}

Debugging FedCM Handshakes in Chrome DevTools

To inspect and debug FedCM workflows in Google Chrome:

1. Open Chrome DevTools via F12 and navigate to the Application panel.
2. In the left sidebar, navigate to Background Services > FedCM.
3. Click Record and trigger your FedCM authentication workflow.
4. DevTools logs every request made to the web-identity manifest, configuration file, accounts endpoint, and token assertion endpoint, displaying detailed HTTP status codes and parser errors.
5. To test auto-reauthentication, toggle the Auto Re-authn flag under chrome://flags/#fedcm-auto-reauthn to verify that returning visitors log in seamlessly.