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

Eiji Kitamura

从 Chrome 125 开始，Button Mode API 将启动 源试用。借助 Button Mode API，身份提供方可以使用 FedCM API，即使其用户在调用 API 时没有有效的 IdP 会话，也是如此。 然后，用户无需 已前往 IdP 网站。按钮模式下的 FedCM 界面更加显眼 与现有 widget 流程相比，该流程由用户控制 并更好地反映用户的登录意图。

按钮模式 API

FedCM 界面已作为微件显示在右上角 桌面上为一角，在移动设备上显示为底部动作条 也就是用户到达信赖方 (RP) 时。这称为 widget 模式下创建的。要显示微件，用户必须登录 IdP 在进入 RP 之前。FedCM 本身没有可靠的方法 用户必须先登录 IdP，然后才能让用户登录 RP 使用 IdP 提供的账号登录。FedCM 即将添加一种方法来实现这一点。

<ph type="x-smartling-placeholder">

</ph>

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

新的 Button Mode API 添加了一种名为 button 模式的新界面模式。取消 微件模式，则在用户进入 RP而是在用户启动登录流程时调用 例如按“通过 IdP 登录”按钮。

按下该按钮后，FedCM 会立即检查用户是否已登录 通过提取到账号的 IdP 端点或 将登录状态信息存储到 浏览器。如果 用户尚未登录，FedCM 要求用户使用 login_url IdP 提供的凭据。如果浏览器知道用户 已经登录到 IdP，或者用户立即使用 FedCM 会打开一个模态对话框，供用户选择 IdP 登录。选择账号后，用户可以继续登录 通过 IdP 账号登录到 RP。

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

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

在按钮模式下，模式对话框会在桌面版 Chrome 的顶部中央显示，并带有一个较大的图标。

访问 Chrome 125，亲自体验一下 https://fedcm-rp-demo.glitch.me/button_flow.

<ph type="x-smartling-placeholder">

</ph>

用户使用 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 推出此功能时添加。

浏览器会向 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

注意 ：如果出现问题，使用按钮模式的 FedCM API 调用 使用微件模式时，它会延迟响应 。这是因为用户在 IdP 的登录状态是 并发送错误信号，很快就会让 RP 有关用户 IdP 登录状态的提示。在按钮模式下，系统会要求用户 无论如何都登录 IdP 无需担心会泄露用户的 IdP 登录 状态发送到 RP。

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

功能检测

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

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 或注册 Button Mode API 源试用。
• IdP 在 IdP 配置中指定以下内容： 文件：

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

参与源试用

您可以在本地试用 Button Mode API，只需启用 Chrome 浏览器即可 标志 chrome://flags#fedcm-button-mode（Chrome 125 或更高版本）。

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

• 注册第三方源试用 代表 RP。

通过源试用，您可以试用新功能并提供反馈 Web 标准社区的易用性、实用性和有效性。对于 请参阅适用于 Web 的源试用指南 开发者。

Chrome 125 至 Chrome 提供 Button Mode API 源试用 130。

1. 转到源试用注册 页面。
2. 点击 Register（注册）按钮，然后填写申请令牌的表单。
3. 在 Web Origin 字段中输入 IdP 的来源。
4. 检查第三方匹配，以便在其他 来源。
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 替换为您自己的令牌。

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

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

CORS

Chrome 将强制执行 针对 ID 的 CORS 断言 端点 从 Chrome 125 开始。

CORS（跨源资源共享）是一个系统， HTTP 标头，用于确定浏览器是否屏蔽前端 JavaScript 代码 禁止访问跨源请求的响应ID 断言端点 IdP 服务器必须使用额外的标头响应请求。通过 以下是从 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 将仅使用 Cookie 发送这些已凭据化的请求 已明确标记为 SameSite=None。