FedCM 更新：Button Mode API 源试用、CORS 和 SameSite

Eiji Kitamura

从 Chrome 125 开始，Button Mode API 将开始在桌面设备上进行源试用。借助 Button Mode API，即使用户在 API 调用时没有有效的 IdP 会话，身份提供方也可以使用 FedCM API。然后，用户可以使用其联合帐号登录网站，而无需转到 IdP 网站。与现有 widget 流程中的 FedCM 界面相比，按钮模式下的 FedCM 界面更加显眼，因为它受用户手势控制，可以更好地反映用户的登录意图。

按钮模式 API

FedCM 界面在调用 API 后（可能是用户到达依赖方 (RP) 时）就以 widget 的形式在桌面设备右上角显示，或在移动设备上显示为底部动作条。这称为 widget 模式。如需显示此 widget，用户必须先登录 IdP，然后才能登录 RP。FedCM 本身并没有可靠的方法让用户先登录 IdP，然后才能让用户使用 IdP 上提供的帐号登录 RP。FedCM 即将推出一种方法。

在微件模式下，桌面版 Chrome 会在右上角显示一个对话框，无需用户激活。

新的 Button Mode API 添加了一个名为“按钮”模式的新界面模式。与 widget 模式不同，按钮模式并不意味着在用户进入 RP 后立即调用。而是在用户发起登录流程（例如按“使用 IdP 登录”按钮）时调用。

按下该按钮后，FedCM 会立即通过提取到帐号端点或存储到浏览器中的登录状态来检查用户是否已登录 IdP。如果用户尚未登录，FedCM 会要求用户使用 IdP 提供的 login_url 通过弹出式窗口登录 IdP。如果浏览器知道用户已登录 IdP，或者只要用户通过弹出式窗口登录 IdP，FedCM 就会打开一个模态对话框，供用户选择用于登录的 IdP 帐号。选择帐号后，用户可以继续使用 IdP 帐号登录 RP。

在按钮模式下，系统会在桌面版 Chrome 的顶部中央显示一个模态对话框。

您可以访问 Chrome 125，亲自体验这一功能：https://fedcm-rp-demo.glitch.me/button_flow。

用户使用 Button Mode API 登录 RP。

如需使用 Button Mode API，请执行以下操作：

• 在 chrome://flags 中启用实验性功能 FedCmButtonMode。
• 请务必调用暂时性用户激活（如按钮点击）背后的 API。
• 使用 mode 参数调用 API，如下所示：

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

注意： Chrome 目前仅支持在新的 mode 属性中使用 "button"。其他属性（例如 "widget"）将在 Chrome 推出此功能后添加。

浏览器将通过添加 mode=button 向表示请求类型的 ID 断言端点发送新参数：

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

注意： 出现问题时，使用按钮模式的 FedCM API 调用会立即响应，而使用 widget 模式时，它会故意延迟响应。这是因为用户到 IdP 的登录状态被视为私密信息，发送错误信号很快会为 RP 提供有关用户的 IdP 登录状态的提示。在按钮模式下，无论如何，用户都无需担心向 RP 公开用户的 IdP 登录状态。

注意 ：用户可以在 Chrome 设置中停用 FedCM widget 模式。这不会影响 Button Mode API，因为登录请求是由用户手势发起，而浏览器应协助用户完成登录流程。

使用其他账号选项

例如，当 IdP 支持多个帐号或替换现有帐号时，RP 可以允许用户在帐号选择器中“使用其他帐号”。

要启用使用其他账号的选项，请执行以下操作：

• 在 chrome://flags 中启用实验性功能 FedCmUseOtherAccount，或注册 Button Mode API 源试用。
• IdP 会在 IdP 配置文件中指定以下内容：

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

参与源试用

您可以在 Chrome 125 或更高版本中开启 Chrome 标志 chrome://flags#fedcm-button-mode，在本地试用 Button Mode API。

IdP 还可以通过注册源试用来启用“按钮模式”：

• 为 RP 注册第三方源试用。

借助源试用，您可以试用新功能，并针对其易用性、实用性和有效性向 Web 标准社区提供反馈。如需了解详情，请参阅面向 Web 开发者的源试用指南。

从 Chrome 125 一直到 Chrome 127，Button Mode API 源试用处于试用阶段。

1. 前往源试用注册页面。
2. 点击注册按钮，然后填写相应表单以请求令牌。
3. 输入 IdP 的 Web Origin（网络来源）。
4. 检查第三方匹配，以在其他源站上通过 JavaScript 注入令牌。
5. 点击提交。
6. 将颁发的令牌嵌入到第三方网站中。

如需将令牌嵌入第三方网站，请将以下代码添加到 IdP 的 JavaScript 库或从 IdP 来源提供的 SDK 中。

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

将 TOKEN_GOES_HERE 替换为您自己的令牌。

注意 ：如果 RP 而不是通过从 IdP 加载的脚本调用 FedCM API，则 RP 必须自行注册其来源并运行第一方源试用。

Chrome 125 中需要使用 CORS 和 SameSite=None

CORS

从 Chrome 125 开始，Chrome 将在 ID 断言端点上强制执行 CORS。

CORS（跨源资源共享）是一个系统，由传输 HTTP 标头组成，用于确定浏览器是否阻止前端 JavaScript 代码访问跨源请求的响应。IdP 服务器上的 ID 断言端点必须使用额外的标头来响应请求。以下是来自 https://fedcm-rp-demo.glitch.me 的请求的响应标头示例：

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

注意： 由于 Access-Control-Allow-Credentials 设置为 true，因此 Access-Control-Allow-Origin 必须明确返回网域，而不能使用由 * 指示的通配符。

SameSite=None

Cookie 的 SameSite 参数声明了 Cookie 是否仅限于第一方环境或同网站环境。通过将其指定为 None，可将 Cookie 发送到第三方网域。

在 FedCM 中，Chrome 将 Cookie 发送到帐号端点、ID 断言端点和断开连接端点。从 Chrome 125 开始，Chrome 发送这些基于凭据的请求将仅包含明确标记为 SameSite=None 的 Cookie。