Federated Credential Management API

# Implementation status

This document outlines a new proposal for identity federation: the Federated Credential Management API (FedCM).

• The FedCM proposal is open for public discussion.
• FedCM is shipped in Chrome 108.
• FedCM isn't supported in other browsers yet, but Mozilla is implementing a prototype to Firefox, while the Apple has expressed general support and interest in working together on the FedCM proposal.
• Chrome Platform 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.

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 with your integration in Incognito mode. Alternatively, you can block third-party cookies on desktop at chrome://settings/cookies or on mobile by navigating to Settings > Site settings > Cookies.

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.

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.
• Personalized button: IdPs can display a returning user's identity on the sign-in button from within an IdP owned cross-origin iframe.
• 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.

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.

# How can you develop FedCM?

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

# Debug code on Chrome on Android

Set up and run a server locally to debug your FedCM code. You can access this server in Chrome on an Android device connected using a USB cable with port forwarding.

You can use DevTools on desktop to debug Chrome on Android by following the instructions at Remote debug Android devices.

# Use the FedCM API

You integrate with FedCM by creating 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.

# Create a well-known file

To prevent trackers from abusing the API, a well-known file must be served from /.well-known/web-identity of eTLD+1 of the IdP.

For example, if the IdP endpoints are served under https://accounts.idp.example/, they must serve a well-known file at https://idp.example/.well-known/web-identity as well as an IdP config file. Here's an example well-known file content:

{
  "provider_urls": ["https://accounts.idp.example/config.json"]
}

The JSON file must contain the provider_urls property with an array of IdP config file URLs that can be specified as a path part of configURL in navigator.credentials.get by RPs. The number of URL strings in the array is limited to one, but this may change with your feedback in the future.

# Create an IdP config file and endpoints

The IdP config file provides a list of required endpoints for the browser. IdPs will host this config file and the required endpoints. All JSON response must be served with application/json content type.

The config file's URL is determined by the values provided to the navigator.credentials.get call executed on an RP.

const credential = await navigator.credentials.get({
  identity: {
    providers: [{
      configURL: 'https://accounts.idp.example/config.json',
      clientId: '********',
      nonce: '******'
    }]
  }
});
const { token } = credential;

Specify a full URL of the IdP config file location as a configURL. When navigator.credentials.get() is called on the RP, the browser fetches the config file with a GET request without the Referer header. The request doesn't have cookies and doesn't follow redirects. This effectively prevents the IdP from learning who made the request and which RP is attempting to connect. For example:

GET /config.json HTTP/1.1
Host: accounts.idp.example
Accept: application/json
Sec-Fetch-Dest: webidentity

The browser expects a JSON response from the IdP which includes the following properties:

Here's an example response body from the IdP:

{
  "accounts_endpoint": "/accounts.php",
  "client_metadata_endpoint": "/client_metadata.php",
  "id_assertion_endpoint": "/assertion.php",
  "branding": {
    "background_color": "green",
    "color": "0xFFEEAA",
    "icons": [{
      "url": "https://idp.example/icon.ico",
      "size": 25
    }]
  }
}

Once the browser fetches the config file, it sends subsequent requests to the IdP endpoints:

# Accounts list endpoint

The IdP's accounts list endpoint returns a list of accounts that the user is currently signed in on the IdP. If the IdP supports multiple accounts, this endpoint will return all signed in accounts.

The browser sends a GET request with cookies, but without a client_id parameter or the Referer header. This effectively prevents the IdP from learning which RP the user is trying to sign in to. For example:

GET /accounts.php HTTP/1.1
Host: accounts.idp.example
Accept: application/json
Cookie: 0x23223
Sec-Fetch-Dest: webidentity

The browser expects a JSON response that includes an accounts property with an array of account information with following properties:

Example response body:

{
 "accounts": [{
   "id": "1234",
   "given_name": "John",
   "name": "John Doe",
   "email": "john_doe@idp.example",
   "picture": "https://idp.example/profile/123",
   "approved_clients": ["123", "456", "789"],
  }, {
   "id": "5678",
   "given_name": "Johnny",
   "name": "Johnny",
   "email": "johnny@idp.example",
   "picture": "https://idp.example/profile/456"
   "approved_clients": ["abc", "def", "ghi"],
  }]
}

If the user is not signed in, respond with HTTP 401 (Unauthorized).

The returned accounts list is consumed by the browser and will not be available to the RP.

# Client metadata endpoint

The IdP's client metadata endpoint returns the relying party's metadata such as the RP's privacy policy and terms of service. RPs should provide links to their privacy policy and terms of service to the IdP in advance. These links are displayed in the sign-in dialog when the user hasn't registered on the RP with the IdP yet.

The browser sends a GET request using the client_id navigator.credentials.get without cookies. For example:

GET /client_metadata.php?client_id=1234 HTTP/1.1
Host: accounts.idp.example
Referer: https://rp.example/
Accept: application/json
Sec-Fetch-Dest: webidentity

The properties for the client metadata endpoint include:

The browser expects a JSON response from the endpoint:

{
  "privacy_policy_url": "https://rp.example/privacy_policy.html",
  "terms_of_service_url": "https://rp.example/terms_of_service.html",
}

The returned client metadata is consumed by the browser and will not be available to the RP.

# ID assertion endpoint

The IdP's ID assertion endpoint returns an assertion for their signed-in user. When the user signs in to an RP website using navigator.credentials.get() call, the browser sends a POST request with cookies and a content type of application/x-www-form-urlencoded to this endpoint with the following information:

Example HTTP header:

POST /assertion.php HTTP/1.1
Host: accounts.idp.example
Referer: https://rp.example/
Content-Type: application/x-www-form-urlencoded
Cookie: 0x23223
Sec-Fetch-Dest: webidentity
account_id=123&client_id=client1234&nonce=Ct60bD&disclosure_text_shown=true

On the server, the IdP should confirm that:

1. The claimed account ID matches the ID for the account that is already signed in.
2. The Referer header matches the origin the RP, registered in advance for the given client ID.

The browser expects a JSON response that includes the following property:

{
  "token": "***********"
}

The returned token is passed to the RP by the browser, so that the RP can validate the authentication.

# Sign in to the relying party with the identity provider

Once the IdP's configuration and endpoints are available, RPs can call navigator.credentials.get() to request allowing users to sign in to the RP with the IdP.

Before calling the API, you need to confirm that [FedCM is available on the user's browser]. To check if FedCM is available, wrap this code around your FedCM implementation:

if ('IdentityCredential' in window) {
  // If the feature is available, take action
}

To request allowing users to sign in to the IdP from the RP, do the following, for example:

const credential = await navigator.credentials.get({
  identity: {
    providers: [{
      configURL: 'https://accounts.idp.example/config.json',
      clientId: '********',
      nonce: '******'
    }]
  }
});
const { token } = credential;

The providers property takes an array of IdentityProvider objects that have the following properties:

The browser handles sign-up and sign-in use cases differently depending on the existence of approved_clients in the response from the accounts list endpoint. The browser will only display the RP's privacy policy and terms of service in the dialog if approved_clients isn't provided or does not include the RP's clientId and the user hasn't previously signed up for the RP in this browser.

When the RP calls navigator.credentials.get(), the following activities take place:

1. The browser sends requests and fetches several documents:
   1. The well-known file and an IdP config file which declare endpoints.
   2. An accounts list.
   3. Optional: URLs for the RP's privacy policy and terms of service, retrieved from the client metadata endpoint.
2. The browser displays the list of accounts that the user can use to sign-in, as well as the terms of service and privacy policy if available.
3. Once the user chooses an account to sign in with, a request to the ID assertion endpoint is sent to the IdP to retrieve a token.
4. The RP can validate the token to authenticate the user.

Once the token is validated by the RP server, the RP may register the user or let them sign-in and start a new session.

# Engage and share feedback

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