# Google Sign-in with FedCM APIs

> [!WARNING]
> **Warning:** The Google Sign-In library optionally uses FedCM APIs, and their use will become a requirement. [Conduct an impact assessment](https://developers.google.com/identity/sign-in/web/gsi-with-fedcm) to confirm that user sign-in continues to function as expected.   
>
> Support for the Google Sign-In library is deprecated, see the [Deprecation and Sunset](https://developers.google.com/identity/sign-in/web/deprecation-and-sunset) guide for more.

> [!CAUTION]
> **Caution:** If your site uses a cross-origin iframe for sign-in, set `use_fedcm` to `false` as Chrome feature support is only available in August 2025 as part of the M139 stable release.

This guide discusses the adoption of FedCM APIs by the Google
Sign-in platform library. Topics include the [Timeline](https://developers.google.com/identity/sign-in/web/gsi-with-fedcm#timeline) and
[Next Steps](https://developers.google.com/identity/sign-in/web/gsi-with-fedcm#next_steps) for a backward compatible update to the library, how to
[Conduct an impact assessment](https://developers.google.com/identity/sign-in/web/gsi-with-fedcm#conduct_an_impact_assessment) and verify user sign-in continues to
function as expected, and if needed, instructions for updating your web app.
Options to [Manage the transition period](https://developers.google.com/identity/sign-in/web/gsi-with-fedcm#manage_the_transition_period) along with how to [Get help](https://developers.google.com/identity/sign-in/web/gsi-with-fedcm#get_help)
are also covered.

## Status of the library

Any new web apps are blocked from using the deprecated Google Sign-in platform
library, while apps using the library can continue until further notice. A
final sunset date (shutdown) for the library has not been established.
See [Deprecation of support and sunset](https://developers.google.com/identity/sign-in/web/deprecation-and-sunset) for more.

A backward compatible update adds [FedCM APIs](https://fedidcg.github.io/FedCM/) to the Google Sign-In library.
While most changes are seamless, the update introduces differences to
[user prompts](https://fedidcg.github.io/FedCM/#browser-surface-impersonation), iframe [permissions-policy](https://fedidcg.github.io/FedCM/#permissions-policy-integration), and
[Content Security Policy](https://fedidcg.github.io/FedCM/#content-security-policy) (CSP). These changes may affect your web app and
require changes to application code and site configuration.

During the transition period a configuration option controls whether or not
FedCM APIs are used during user sign-in.

After the transition period, FedCM APIs are mandatory for all web apps using
the Google Sign-In library.

## Timeline

**Last updated April 2025**

These are the dates and changes that affect user sign-in behavior:

- **March 2023** [Deprecation of support](https://developers.google.com/identity/sign-in/web/deprecation-and-sunset) for the Google Sign-in platform library.
- **July 2024 Transition period** begins, and Google Sign-in platform library support for FedCM APIs is added. By default, Google controls the percentage of user sign-in requests using FedCM during this time and web apps may explicitly override this behavior with the [`use_fedcm`](https://developers.google.com/identity/sign-in/web/reference#gapiauth2clientconfig) parameter.
- **August 2025 Mandatory adoption** of FedCM APIs by the Google Sign-in platform library.

## Next steps

There are three options you may choose to follow:

1. [**Conduct an impact assessment**](https://developers.google.com/identity/sign-in/web/gsi-with-fedcm#conduct_an_impact_assessment), and if needed, update your web app. This approach evaluates if features that require changes to your web app are in use. Instructions are provided in the next section of this guide.
2. **Move to** Google Identity Services (GIS) library. Moving to the latest and supported sign-in library is strongly recommended. Do this by following these [instructions](https://developers.google.com/identity/gsi/web/guides/migration).
3. **Do nothing.** Your web app will automatically be updated when the Google Sign-in library moves to FedCM APIs for user sign-in. This is the least work, but there is some risk of users being unable to sign-in to your web app.

## Conduct an impact assessment

Follow these instructions to determine if your web app can be seamlessly updated
through a backward compatible update or if changes are necessary to avoid
users being unable to sign-in when the Google Sign-in platform library fully
adopts FedCM APIs.

### Setup

Browser APIs and the latest version of the Google Sign-in platform library are
necessary to use FedCM during user sign-in.

Before going further:

- Update to the latest version of Chrome for Desktop. Chrome for Android requires release M128 or later and cannot be tested using earlier versions.
- Set [`use_fedcm`](https://developers.google.com/identity/sign-in/web/reference#gapiauth2clientconfig) to `true` when initializing the Google Sign-in platform
  library in your web app. Typically, JavaScript initialization looks like:

  - `gapi.client.init({use_fedcm: true})`, or
  - `gapi.auth2.init({use_fedcm: true})`, or
  - `gapi.auth2.authorize({use_fedcm: true})`.

  Alternatively, a `meta` tag can be used to enable FedCM in HTML:
  - `<meta name="google-signin-use_fedcm" content="true">`
- Invalidate cached versions of the Google Sign-in platform library.
  Usually this step is unnecessary as the latest version of the library is
  directly downloaded to the browser by including `api.js`, `client.js`, or
  `platform.js` in a `<script src>` tag (the request may use any of these
  bundle names for the library).

- Confirm OAuth settings for your OAuth client ID:

  1. Open the Credentials page of the Google API Console
  2. Verify the URI of your website is included in
     **Authorized JavaScript origins** . The URI includes the scheme and
     fully qualified hostname only. For example, `https://www.example.com`.

     > [!IMPORTANT]
     > **Key Point:** For local tests or development add both `http://localhost` and `http://localhost:<port_number>`.

  3. Optionally, credentials may be returned using a redirect to an endpoint
     you host rather than through a JavaScript callback. If this is the case,
     verify your redirect URIs are included in **Authorized redirect URIs** .
     Redirect URIs include the scheme, fully qualified hostname, and path
     and must comply with [Redirect URI validation rules](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Referrer-Policy). For example,
     `https://www.example.com/auth-receiver`.

     > [!IMPORTANT]
     > **Key Point:** When testing using http and localhost set the [Referrer-Policy](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Referrer-Policy) header in your web app to `Referrer-Policy: no-referrer-when-downgrade`.

### Testing

After following the instructions in Setup:

- Close all existing Chrome Incognito windows, and open a new Incognito window. Doing this clears any cached content or cookies.
- Load your user sign-in page and attempt to sign-in.
- Follow the instructions in these sections of this guide to identify
  and fix known issues:

  - [Locate the Google Sign-in library request](https://developers.google.com/identity/sign-in/web/gsi-with-fedcm#check_for_user_prompt_changes)
  - [Check iframe permissions-policy](https://developers.google.com/identity/sign-in/web/gsi-with-fedcm#check_iframe_permissions-policy)
  - [Check Content Security Policy](https://developers.google.com/identity/sign-in/web/gsi-with-fedcm#check_content_security_policy)
  - [Check for user prompt changes](https://developers.google.com/identity/sign-in/web/gsi-with-fedcm#check_for_user_prompt_changes)
- Look for any errors or warnings in the Console related to the Google Sign-in
  library.

- Repeat this process until no errors occur and you can successfully sign-in.
  You can verify a successful sign-in by confirming
  [`BasicProfile.getEmail()`](https://developers.google.com/identity/sign-in/web/reference#googleusergetbasicprofile) returns your email address and that
  [`GoogleUser.isSignedIn()`](https://developers.google.com/identity/sign-in/web/reference#googleuserissignedin) is `True`.

### Locate the Google Sign-in library request

Check if [permissions-policy](https://developers.google.com/identity/sign-in/web/gsi-with-fedcm#check_iframe_permissions-policy) and [Content Security Policy](https://developers.google.com/identity/sign-in/web/gsi-with-fedcm#check_content_security_policy) changes are
necessary by inspecting the request for the Google Sign-in platform library.
To do this, locate the request using the name and origin of the library:

- In Chrome, Open the DevTools **Network** panel and reload the page.
- Use the values in the **Domain** and **Name** columns to locate the library request:
  - Domain is `apis.google.com` and
  - Name is either `api.js`, `client.js`, or `platform.js`. The specific value of Name depends upon the library bundle requested by the document.

For example, filter on `apis.google.com` in the **Domain** column and
`platform.js` in the **Name** column.

### Check iframe permissions-policy

> [!CAUTION]
> **Caution:** If your site uses a cross-origin iframe for sign-in, set `use_fedcm` to `false` as Chrome feature support is only available in August 2025 as part of the M139 stable release.

Your site might use the Google Sign-in platform library inside a cross-origin
iframe. If so, an update is needed.

After following the [Locate the Google Sign-in library request](https://developers.google.com/identity/sign-in/web/gsi-with-fedcm#locate_the_google_sign-in_library_request)
instructions, select the Google Sign-in library request in the DevTools
**Network** panel and locate the [`Sec-Fetch-Site`](https://web.dev/articles/same-site-same-origin#how_to_check_if_a_request_is_same-site_same-origin_or_cross-site)) header in the
**Request Headers** section in the **Headers** tab. If the value of the header
is:

- `same-site`or `same-origin` then cross-origin policies don't apply and no changes are needed.
- `cross-site` changes may be necessary if an iframe is being used.

To confirm if an iframe is present:

- Select the **Elements** panel in Chrome DevTools, and
- Use Ctrl-F to find an iframe in the document.

If an iframe is found, inspect the document to check for calls to [gapi.auth2
functions](https://developers.google.com/identity/gsi/web/guides/migration#object_migration_reference_for_user_sign-in) or `script src` directives which load the Google Sign-in library
within the iframe. If this is the case:

- Add the [`allow="identity-credentials-get"`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Permissions-Policy/identity-credentials-get) permissions policy to the parent iframe.

Repeat this process for every iframe in the document. iframes can be nested, so
be sure to add the allow directive to all surrounding parent iframes.

### Check Content Security Policy

If your site uses a Content Security Policy, you may need to update your CSP to
allow use of the Google Sign-in library.

After following the [Locate the Google Sign-in library request](https://developers.google.com/identity/sign-in/web/gsi-with-fedcm#locate_the_google_sign-in_library_request)
instructions, select the Google Sign-in library request in the DevTools
**Network** panel and locate the [`Content-Security-Policy`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Security-Policy) header in the
**Response Headers** section of the **Headers** tab.

If the header is not found, no changes are necessary. Otherwise, check if any of
these CSP directives are defined in the CSP header and update them by:

- Adding `https://apis.google.com/js/`, `https://accounts.google.com/gsi/`,
  and `https://acounts.google.com/o/fedcm/` to any `connect-src`,
  `default-src`, or `frame-src` directives.

- Adding to `https://apis.google.com/js/bundle-name.js` to the `script-src`
  directive. Replace `bundle-name.js` with either `api.js`, `client.js`, or
  `platform.js`based upon the library bundle the document requests.

### Check for user prompt changes

There are some differences to user prompt behavior, FedCM adds a modal dialog
displayed by the browser and updates user activation requirements.

> [!IMPORTANT]
> **Key Point:** Consent is per browser instance, so using Chrome on a different device also requires a one-time consent regardless if users have previously done so on a different device.

#### Modal dialog

![Image of FedCM modal dialog](https://developers.google.com/static/identity/sign-in/web/fedcm-consent.png "FedCM modal dialog")

Inspect the layout of your site to confirm that underlying content can be
safely overlaid and temporarily obscured by the browser's modal dialog. If this
is not the case you may need to adjust the layout or position of some elements
of your website.

> [!NOTE]
> **Note:** The size and position of the modal dialog is not available within the JavaScript runtime environment.

#### User activation

FedCM includes updated user activation requirements. Pressing a button or
clicking on a link are examples of user gestures that allow third-party origins
to make network requests or to store data. With FedCM, the browser prompts for
user consent when:

- a user first signs-in to a web app using a new browser instance, or
- [`GoogleAuth.signIn`](https://developers.google.com/identity/sign-in/web/reference#googleauthsigninoptions) is called.

Today, if the user has signed in to your website before, you are able to obtain
the user's sign in information when initializing the Google Sign-In library
using `gapi.auth2.init`, without further user interactions. This is no longer
possible unless the user has first gone through the FedCM sign in flow at least
once.

By opting in to FedCM and calling `GoogleAuth.signIn`, the next time the same
user visits your website, `gapi.auth2.init` can obtain the user's sign in
information during initialization without user interaction.

> [!IMPORTANT]
> **Key Point:** A user gesture and consent prompt is required the first time [`GoogleAuth.signIn`](https://developers.google.com/identity/sign-in/web/reference#googleauthsigninoptions) is called, even if this is occurs within a document `onload` event.

#### Common use cases

Developer documentation for the Google Sign-In library includes guides and code
samples for common use cases. This section discusses how FedCM affects their
behavior.

- [Integrating Google Sign-In into your web app](https://developers.google.com/identity/sign-in/web/sign-in#add_a_google_sign-in_button)

  In this [demo](https://gis-example.glitch.me/gapi-button.html), a `<div>` element and a class render the button, and
  for already signed-in users, the page `onload` event returns user
  credentials. User interaction is required to sign-in and establish a new
  session.

  Library initialization is done by the `g-signin2` class which calls
  `gapi.load` and `gapi.auth2.init`.

  A user gesture, a `<div>` element `onclick` event, calls `auth2.signIn`
  during sign-in or `auth2.signOut` on sign-out.
- [Building a custom Google Sign-In button](https://developers.google.com/identity/sign-in/web/build-button)

  In [demo one](https://gis-example.glitch.me/gapi-custombutton.html), custom attributes are used to control the appearance of
  the sign-in button and for already signed-in users, the page `onload` event
  returns user credentials. User interaction is required to sign-in and
  establish a new session.

  Library initialization is done through an `onload` event for the
  `platform.js` library and the button is displayed by `gapi.signin2.render`.

  A user gesture, pressing the sign-in button, calls `auth2.signIn`.

  In [demo two](https://gis-example.glitch.me/gapi-customgraphic.html), a `<div>` element, CSS styles, and a custom graphic are
  used to control the appearance of the sign-in button. User interaction is
  required to sign-in and establish a new session.

  Library initialization is done on document load using a start function
  which calls `gapi.load`, `gapi.auth2.init`, and
  `gapi.auth2.attachClickHandler`.

  A user gesture, a `<div>` element `onclick` event, calls `auth2.signIn`
  using the `auth2.attachClickHandler` during sign-in or `auth2.signOut` on
  sign-out.
- [Monitoring the user's session state](https://developers.google.com/identity/sign-in/web/session-state)

  In this [demo](https://gis-example.glitch.me/gapi-monitoring.html), a button press is used for user sign-in and sign-out.
  User interaction is required to sign-in and establish a new session.

  Library initialization is done by directly calling `gapi.load`,
  `gapi.auth2.init`, and `gapi.auth2.attachClickHandler()` after
  `platform.js` is loaded using `script src`.

  A user gesture, a `<div>` element `onclick` event, calls `auth2.signIn`
  using the `auth2.attachClickHandler` during sign-in or `auth2.signOut` on
  sign-out.
- [Requesting additional permissions](https://developers.google.com/identity/sign-in/web/incremental-auth)

  In this [demo](https://gis-example.glitch.me/gapi-authz.html), a button press is used to request additional OAuth 2.0
  scopes, obtain a new access token, and for already signed-in users, the
  page `onload` event returns user credentials. User interaction is required
  to sign-in and establish a new session.

  Library initialization is done by the `onload` event for the
  `platform.js` library through a call to `gapi.signin2.render`.

  A user gesture, clicking on a `<button>` element, triggers a request for
  additional OAuth 2.0 scopes using `googleUser.grant` or `auth2.signOut`
  on sign-out.
- [Integrating Google Sign-In using listeners](https://developers.google.com/identity/sign-in/web/listeners)

  In this [demo](https://gis-example.glitch.me/gapi-statechange.html), for already signed-in users, the page `onload` event
  returns user credentials. User interaction is required to sign-in and
  establish a new session.

  Library initialization is done on document load using a start function
  which calls `gapi.load`, `gapi.auth2.init`, and
  `gapi.auth2.attachClickHandler`. Next, `auth2.isSignedIn.listen` and
  `auth2.currentUser.listen` are used to setup notification of changes to
  session state. Lastly, `auth2.SignIn` is called to return credentials for
  signed-in users.

  A user gesture, a `<div>` element `onclick` event, calls `auth2.signIn`
  using the `auth2.attachClickHandler` during sign-in or `auth2.signOut` on
  sign-out.
- [Google Sign-In for server-side apps](https://developers.google.com/identity/sign-in/web/server-side-flow)

  In this [demo](https://gis-example.glitch.me/gapi-authcode.html), a user gesture is used to request an OAuth 2.0 auth code
  and a JS callback makes an AJAX call to send the response to the backend
  server for verification.

  Library initialization is done using an `onload` event for the `platform.js`
  library, which uses a start function to call `gapi.load` and
  `gapi.auth2.init`.

  A user gesture, clicking on a `<button>` element, triggers a request for
  an authorization code by calling `auth2.grantOfflineAccess`.
- [Cross platform SSO](https://developers.google.com/identity/sign-in/web/cross-platform-sign-in)

  FedCM requires consent for every browser instance, even if Android users
  have already signed in, a one time consent is necessary.

## Manage the transition period

During the transition period a percentage of user sign-ins may use FedCM, the
exact percentage can vary and may change over time. By default, Google controls
how many sign-in requests use FedCM, but you may choose to opt-in or opt-out of
using FedCM during the transition period. At the end of the transition period
FedCM becomes mandatory and is used for all sign-in requests.

Choosing to opt-in sends the user through the FedCM sign-in flow, while choosing
to opt-out sends the users through the existing sign-in flow. This behavior is
controlled using the [`use_fedcm`](https://developers.google.com/identity/sign-in/web/reference#gapiauth2clientconfig) parameter.

### Opt-in

It may be helpful to control whether all, or some, sign-in attempts to your
site use FedCM APIs. To do this, set `use_fedcm` to `true` when initializing
the platform library. The user sign-in request uses FedCM APIs in this case.

### Opt-out

During the transition period, a percentage of user sign-in attempts to your site
will use FedCM APIs by default. If more time is needed to make changes to your
app, you may temporarily opt-out of using FedCM APIs. To do this, set
`use_fedcm` to `false` when initializing the platform library. The user sign-in
request won't use FedCM APIs in this case.

After mandatory adoption occurs, any `use_fedcm` settings are ignored by the
Google Sign-in platform library.

## Get help

Search or ask questions on StackOverflow using the [*google-signin*](https://stackoverflow.com/questions/tagged/google-signin?tab=Frequent) tag.