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

Eiji Kitamura

自 Chrome 125 起，Button Mode API 將在電腦上開始進行來源試用。透過 Button Mode API，即使使用者在 API 呼叫時沒有有效的 IdP 工作階段，身分識別資訊提供者也能使用 FedCM API。使用者隨後即可透過聯合帳戶登入網站，不必前往 IdP 網站。與現有小工具流程相比，按鈕模式的 FedCM 使用者介面更顯眼，因為這類介面會受到使用者手勢的限制，且能更準確反映使用者登入意圖。

Button Mode API

API 叫用後，FedCM 使用者介面就會顯示為電腦右上角的 Widget，或是行動裝置上的底部功能表，使用者登陸依附方 (RP) 時可能會看到。這稱為「小工具」模式。如要顯示小工具，使用者必須先登入 IdP，才能前往 RP。FedCM 本身沒有可靠的方法，可讓使用者先登入 IdP，再使用 IdP 上的帳戶登入 RP。FedCM 即將新增這項功能。

新的 Button Mode API 新增了名為「button」的 UI 模式。與小工具模式不同，按鈕模式不適合在使用者進入 RP 時立即叫用。而是要在使用者啟動登入流程時 (例如按下「使用 IdP 登入」按鈕) 呼叫。

按下按鈕後，FedCM 會透過擷取帳戶端點或儲存在瀏覽器的登入狀態，檢查使用者是否已登入 IdP。如果使用者尚未登入，FedCM 會透過彈出式視窗，要求使用者使用 IdP 提供的 login_url 登入 IdP。如果瀏覽器知道使用者已登入 IdP，或使用者透過彈出式視窗登入 IdP，FedCM 就會開啟模式對話方塊，讓使用者選擇要登入的 IdP 帳戶。選取帳戶後，使用者即可使用 IdP 帳戶登入 RP。

在按鈕模式 UI 中，顯示的登入對話方塊比小工具模式大，因此品牌圖示也應放大，以維持視覺一致性。小工具模式的圖示大小下限為 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.
}

使用其他帳戶選項

如果 IdP 支援多個帳戶或取代現有帳戶，RP 可以在帳戶選擇工具中允許使用者「使用其他帳戶」。

如要啟用使用其他帳戶的選項，請按照下列步驟操作：

• 在 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 註冊第三方來源試用。

您可以透過來源試用程序試用新功能，並向網路標準社群提供意見，協助評估這些功能的實用性、實用性和有效性。詳情請參閱網頁開發人員適用的來源試用指南。

Button Mode API 來源試用從 Chrome 125 開始，並於 Chrome 130 結束。

1. 前往來源試用註冊頁面。
2. 按一下「註冊」按鈕並填寫表單，即可要求權杖。
3. 以「Web Origin」的形式輸入 IdP 的來源。
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 替換成您自己的權杖。

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，連同這些已通過驗證的請求一併傳送。