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

Eiji Kitamura

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

按钮模式 API

FedCM 界面以 widget 形式显示在桌面设备的右上角，或以底部工作表的形式显示在移动设备上，只要 API 被调用（可能是用户进入信赖方 [RP] 时），该界面就会显示。这称为微件模式。如需显示 widget，用户必须在到达 RP 之前登录 IdP。FedCM 本身并没有可靠的方法让用户先登录 IdP，然后才能让用户使用 IdP 上提供的账号登录 RP。FedCM 即将添加一种实现此目的的方法。

新的按钮模式 API 新增了一种名为按钮模式的界面模式。与 widget 模式不同，按钮模式不应在用户到达 RP 后立即调用。相反，它旨在当用户发起登录流程（例如按“使用 IdP 登录”按钮）时调用。

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

在按钮模式界面中，显示的登录对话框比 widget 模式更大，因此品牌宣传图标也应更大，以保持视觉一致性。虽然 widget 模式下的最小图标尺寸为 25x25 像素，但按钮模式下的最小图标尺寸为 40x40 像素。IdP 的知名文件允许指定多个图标网址，如下所示：

{
  // ... Other settings (like endpoints) here
  "branding": {
    "icons": [
      {
        "url": "https://size-25px-image",
        "size": 25,
      },
      {
        "url": "https://size-40px-image",
        "size": 40
      }
    ]
  }
}

您可以使用 Chrome 125 在 https://fedcm-demo-rp.dev/active-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"
    }
  });

浏览器将向 ID 断言端点发送一个新参数，通过添加 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

功能检测

如需确定浏览器是否符合使用按钮模式的条件，您可以使用以下代码进行检查：

let supportsFedCmMode = false;
try {
  navigator.credentials.get({
    identity: Object.defineProperty(
      {}, 'mode', {
        get: function () { supportsFedCmMode = true; }
      }
    )
  });
} catch(e) {}

if (supportsFedCmMode) {
  // The button mode is supported.
}

使用“使用其他账号”选项

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

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

• 在 chrome://flags 中启用实验性功能 FedCmUseOtherAccount，或注册加入按钮模式 API 来源试用。
• IdP 在 IdP 配置文件中指定了以下内容：

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

参与源试用

您可以在本地尝试使用按钮模式 API，方法是在 Chrome 125 或更高版本中开启 Chrome 标志 chrome://flags#fedcm-button-mode。

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

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

通过源试用，您可以试用新功能，并向 Web 标准社区反馈这些功能的实用性、可行性和有效性。如需了解详情，请参阅面向 Web 开发者的 Origin 试用指南。

按钮模式 API 源试用从 Chrome 125 开始，到 Chrome 130 结束。

1. 前往源试用注册页面。
2. 点击注册按钮，然后填写表单以申请令牌。
3. 以 Web Origin 形式输入 IdP 的来源。
4. 检查第三方匹配，以在其他来源上通过 JavaScript 注入令牌。
5. 点击提交。
6. 在第三方网站上嵌入已签发的令牌。

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

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

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

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

SameSite=None

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

在 FedCM 中，Chrome 会将 Cookie 发送到账号端点、ID 断言端点和断开连接端点。从 Chrome 125 开始，Chrome 将仅发送明确标记为 SameSite=None 的 Cookie 来发送这些经过身份验证的请求。