Migrate to FedCM

This guide helps you understand the changes to your web application introduced by the Federated Credentials Management API (FedCM).

When FedCM is enabled the browser displays user prompts and no third-party cookies are used.

Overview

Privacy Sandbox for the Web and Chrome's removal of third-party cookies from the web introduce significant changes to Google Identity Services and user sign in.

FedCM enables more private sign-in flows without requiring the use of third-party cookies. The browser controls user settings, displays user prompts, and only contacts an Identity Provider such as Google after explicit user consent is given.

For most websites, migration occurs seamlessly through backward compatible updates to the Google Identity Services JavaScript library.

Before you begin

Check that your browser and browser version supports the FedCM API, updating to a newer version if necessary.

Before testing sign-in flows with third-party cookies blocked, open chrome://flags and enable the experimental FedCmWithoutThirdPartyCookies feature. This step is only necessary until it becomes the default. Also, the Third-party sign-in setting has to be enabled in Chrome.

Migrate your web app

Follow these steps to enable FedCM, evaluate potential migration impact, and if needed to make changes to your existing web application:

1. Add a boolean flag to enable FedCM when initializing using:

HTML, set the data-use_fedcm_for_prompt attribute to true.
JavaScript, set use_fedcm_for_prompt to true in the IdConfiguration object.

2. Remove use of `isDisplayMoment()`, `isDisplayed()`, `isNotDisplayed()`, and `getNotDisplayedReason()` methods in your code.

To improve user privacy, the google.accounts.id.prompt callback no longer returns any Display Moment notification in the PromptMomentNotication object. Remove any code that depends on the Display Moment related methods. They are isDisplayMoment(), isDisplayed(), isNotDisplayed(), and getNotDisplayedReason() methods.

3. Remove use of `getSkippedReason()` method in your code.

While the Skip Moment, isSkippedMoment(), would still be called from the google.accounts.id.prompt callback in the PromptMomentNotication object, detailed reason wouldn't be provided. Remove any code that depends on the getSkippedReason() method from your code.

Note that the Dismissed Moment notification, isDismissedMoment(), and the related detailed reason method, getDismissedReason(), are unchanged when FedCM is enabled.

4. Remove `position` style attributes from `data-prompt_parent_id` and `intermediate_iframes`.

The browser controls the size and position of user prompts, custom positions for One Tap on Desktop are not supported.

5. Update page layout if needed.

The browser controls the size and position of user prompts. Depending upon the layout of individual pages, some content might be overlaid as custom positions for One Tap on Desktop are not supported in any way such as style attribute, data-prompt_parent_id, intermediate_iframes, customized iframe, and other creative ways.

Change page layout to improve the user experience when important information is obscured. Don't build your UX around the One Tap prompt even if you assume it is in the default position. Because the FedCM API is browser-mediated, different browser vendors may place the position of the prompt slightly differently.

6. Add `allow="identity-credentials-get"` attribute to parent frame if your web app calls One Tap API from cross-origin iframes.

An iframe is considered as cross-origin if its origin is not exactly the same as the parent origin. For Example:

Different domains: https://example1.com and https://example2.com
Different top-level domains: https://example.uk and https://example.jp
Subdomains: https://example.com and https://login.example.com

To improve user privacy, when One Tap API is called from cross-origin iframes, you must add allow="identity-credentials-get" attribute in every parent frame iframe tag:
```
<iframe src="https://your.cross-origin/onetap.page" allow="identity-credentials-get"></iframe>
```
If your app utilizes an iframe that contains another iframe, you must ensure that the attribute is added to every iframe, including all sub-iframes.

For example, consider the following scenario:
The top document (https://www.example.uk) contains an iframe named "Iframe A", which embeds a page (https://logins.example.com).
This embedded page (https://logins.example.com) also contains an iframe named "Iframe B," which further embeds a page (https://onetap.example2.com) that hosts One Tap.

To ensure that One Tap can be displayed properly, the attribute must be added to both Iframe A and Iframe B tags.

Note: The Intermediate Iframe API supports FedCM cross-origin iframes. No additional attribute is needed. However, if you embed a page using the Intermediate Iframe API within another iframe, you must add the allow="identity-credentials-get" attribute to all parent iframes. Enable FedCM to test and ensure proper permission policy setup on all layers.

Prepare for inquiries on the One Tap prompt not displayed. Other sites with different origins may embed your pages that host One Tap within their iframes. You may receive increased amount of support tickets related to One Tap not showing up from end-users or other site owners. While the updates can only be made by the site owners on their pages, you can do the following to mitigate the impact:
Update your developer documentation to include how to set up the iframe properly to call your site. You can link to this page in your documentation.
Update your developer FAQs page if applicable.
Let your support team know this upcoming change and prepare for the response to the inquiry ahead of time.
Proactively contact impacted partners, customers, or site owners for a smooth FedCM transition.

7. Add these directives to your Content Security Policy (CSP).

This step is optional as not all websites choose to define a CSP. * If CSP is not used in your website, no changes are needed. * If your CSP works for the current One Tap and you don't use connect-src, frame-src, script-src, style-src, or default-src no changes are needed. * Otherwise, follow this guide to set up your CSP. Without proper CSP setup, the FedCM One Tap wouldn't be displayed on the site.

8. Remove Accelerated Mobile Pages (AMP) support for sign-in.

User sign-in support for AMP is an optional feature of GIS your web app may have implemented. If this is the case,

Delete any references to the:

amp-onetap-google custom element, and
<script async custom-element="amp-onetap-google" src="https://cdn.ampproject.org/v0/amp-onetap-google-0.1.js"></script>

Consider redirecting sign-in requests from AMP to your website's HTML sign-in flow. Note that the related Intermediate Iframe Support API is unaffected.