FedCM updates: Button Mode API origin trial, CORS and SameSite

Eiji Kitamura

From Chrome 125, the Button Mode API is starting an origin trial on desktop. With the Button Mode API, identity providers can use FedCM API even if their users don't have active IdP sessions upon the API call. Users can then sign in to a website with their federated account without being navigated to the IdP site. The FedCM UI in the button mode is more prominent compared to the one from the existing widget flow because it's gated by a user gesture and better reflects the user's intention for signing in.

Button Mode API

FedCM user interface has been available as a widget displayed at the top-right corner on desktop, or as a bottom sheet on mobile, as soon as the API is invoked which could be when the user lands on the relying party (RP). This is called widget mode. To display the widget, the user must be signed in to the IdP before they land on the RP. FedCM by itself didn't have a reliable way to let the user sign in to the IdP before they could let the user sign in to the RP using the account available on the IdP. FedCM is about to add a way to do this.

With the widget mode, a dialog is displayed at the top right corner on desktop Chrome without user activation.

The new Button Mode API adds a new UI mode called button mode. Unlike the widget mode, button mode isn't meant to be invoked as soon as the user lands the RP. It instead is meant to be invoked when the user initiates a sign-in flow such as pressing a "Sign-in with IdP" button.

As soon as the button is pressed, FedCM checks if the user is signed in to the IdP through a fetch to the accounts endpoint or a login status stored to the browser. If the user is not signed in yet, FedCM asks the user to sign in to the IdP using the login_url provided by the IdP through a popup window. If the browser knows that the user is already signed in to the IdP or as soon as the user signs in to the IdP with the popup window, FedCM opens a modal dialog for the user to choose an IdP account to sign in with. By selecting an account, the user can proceed to sign in to the RP using the IdP account.

With the button mode, a modal dialog is displayed at the top center on desktop Chrome.

Try it out yourself using Chrome 125 at https://fedcm-rp-demo.glitch.me/button_flow.

A user is signing in to the RP using the Button Mode API.

To use the Button Mode API:

• Enable the experimental feature FedCmButtonMode in chrome://flags.
• Make sure to invoke the API behind transient user activation such as a button click.
• Invoke the API with the mode parameter like so:

  return await navigator.credentials.get({
    identity: {
      providers: [{
        configURL: "https://idp.example/config.json",
        clientId: "123",
        nonce:"456",
      }],
      mode: "button"
    }
  });

Note: Chrome only supports "button" in the new mode property for now. Other properties such as "widget" will be added when Chrome ships this feature.

The browser will send a new parameter to the ID assertion endpoint representing the request type by including mode=button:

POST /fedcm_assertion_endpoint HTTP/1.1
Host: idp.example
Origin: 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&is_auto_selected=false&mode=button

Note: When something goes wrong, the FedCM API call using the button mode responds immediately, while with the widget mode, it delays the response intentionally. This is because the user's signed-in state to the IdP is considered private information and sending an error signal soon gives the RP a hint of the user's IdP signed-in state. With the button mode, the user is asked to sign in to the IdP anyway there's no concern to expose the user's IdP sign-in state to the RP.

Note: Users can disable FedCM widget mode in Chrome settings. This doesn't affect the Button Mode API because the login request is initiated by a user gesture and the browser should assist users to complete the login flow.

Use other account option

The RP can allow users to "use other accounts" in the account chooser, for example, when IdPs support multiple accounts or replacing the existing account.

To enable the option to use other account:

• Enable the experimental feature FedCmUseOtherAccount in chrome://flags or enroll the Button Mode API origin trial.
• IdP specifies the following in the IdP config file:

{
  "accounts_endpoint" : ...,
  "modes: {
    "button": {
      "supports_use_other_account": true,
    }
  }
}

Participate in the origin trial

You can try the Button Mode API locally by turning on a Chrome flag chrome://flags#fedcm-button-mode on Chrome 125 or later.

IdPs can also enable the Button Mode by registering an origin trial:

• Register a third-party origin trial for the RP.

Origin trials allow you to try new features and give feedback on their usability, practicality, and effectiveness to the web standards community. For more information, check out the Origin Trials Guide for Web Developers.

The Button Mode API origin trial is available from Chrome 125 through Chrome 127.

1. Go to the origin trial registration page.
2. Click the Register button and fill out the form to request a token.
3. Enter the IdP's origin as Web Origin.
4. Check Third-party matching to inject the token with JavaScript on other origins.
5. Click Submit.
6. Embed the issued token on a third-party website.

To embed the token on a third-party website, add the following code to the IdP's JavaScript library or SDK served from the IdP's origin.

const tokenElement = document.createElement('meta');
tokenElement.httpEquiv = 'origin-trial';
tokenElement.content = 'TOKEN_GOES_HERE';
document.head.appendChild(tokenElement);

Replace TOKEN_GOES_HERE with your own token.

Note: If FedCM API is invoked by the RP, not via script loaded from the IdP, the RP must register their origin themselves and run their first-party origin trial.

CORS and SameSite=None will be required in Chrome 125

CORS

Chrome will enforce CORS on the ID assertion endpoint starting from Chrome 125.

CORS (Cross-Origin-Resource-Sharing) is a system, consisting of transmitting HTTP headers, that determines whether browsers block frontend JavaScript code from accessing responses for cross-origin requests. The ID assertion endpoint on the IdP server must respond to the request with additional headers. The following is an example response header to a request from https://fedcm-rp-demo.glitch.me:

Access-Control-Allow-Origin: https://fedcm-rp-demo.glitch.me
Access-Control-Allow-Credentials: true

Note: Because Access-Control-Allow-Credentials is set to true, Access-Control-Allow-Origin must return a domain explicitly and can't use a wildcard indicated by *.

SameSite=None

Cookie's SameSite parameter declares whether the cookie is restricted to a first-party or same-site context. By specifying it to be None, the cookie can be sent to a third-party domain.

In FedCM, Chrome sends cookies to the accounts endpoint, the ID assertion endpoint and the disconnect endpoint. Starting from Chrome 125, Chrome will send those credentialed requests with only cookies explicitly marked as SameSite=None.