瞭解如何使用 FedCM 處理隱私權保護身分聯盟。
FedCM (Federated Credential Management) 是保護隱私權的機制 採用聯合身分識別服務 (例如「使用以下方式登入...」) 的 使用者登入網站時,不必與 身分識別服務或網站
如要進一步瞭解 FedCM 用途、使用者流程和 API 發展藍圖,請參閱 FedCM API 簡介。
FedCM 開發環境
Chrome 的 IdP 和 RP 皆需要安全內容 (HTTPS 或 localhost) 才能使用 FedCM。
在 Android 版 Chrome 中對程式碼進行偵錯
在本機設定並執行伺服器以對 FedCM 程式碼偵錯。你可以 存取這個伺服器 (透過 USB 傳輸線連接 Android 裝置上的 Chrome) 以及轉送
您可以使用電腦版的開發人員工具,為 Android 裝置上的 Chrome 偵錯,步驟如下: 請參閱「遠端對 Android 偵錯」一文的說明 裝置。
在 Chrome 中封鎖第三方 Cookie
![設定 Chrome 封鎖第三方 Cookie,模擬逐步淘汰第三方 Cookie](https://developers-dot-devsite-v2-prod.appspot.com/static/privacy-sandbox/assets/images/simulate-third-party-cook-8416bea1ab2b.png?authuser=19&hl=zh-tw)
你可以提前測試 FedCM 如何在不使用第三方 Cookie 的情況下運作 實際執行的政策
如要封鎖第三方 Cookie,請使用無痕模式
模式,或選擇「封鎖」
「第三方 Cookie」,在電腦設定中前往 chrome://settings/cookies
或
依序前往「設定」>網站設定 >Cookie。
使用 FedCM API
只要建立已知檔案,就能整合 FedCM。 帳戶的設定檔和端點 清單、宣告核發和 選擇性的用戶端中繼資料。
接著,FedCM 公開了 JavaScript API,讓 RP 能用來簽署 登入 IdP 的服務。。
建立知名檔案
防止追蹤程式濫用
API,已知的檔案必須是
有 /.well-known/web-identity
個網址提供
所有要求的 eTLD+1
IdP。
舉例來說,如果 IdP 端點位於
https://accounts.idp.example/
,它們必須在以下位置提供一個知名的檔案:
https://idp.example/.well-known/web-identity
和 IdP 設定
檔案。以下為已知的檔案內容範例:
{
"provider_urls": ["https://accounts.idp.example/config.json"]
}
JSON 檔案必須包含 provider_urls
屬性和 IdP 陣列
設定檔網址,可指定為
navigator.credentials.get
中的 configURL
(依受限方)。開啟
陣列中的網址字串上限為一個,但可能會隨著
提供意見回饋
建立 IdP 設定檔和端點
IdP 設定檔提供了瀏覽器的必要端點清單。IdPs
將託管這個設定檔以及必要的端點和網址。所有 JSON
回應必須以 application/json
內容類型提供。
設定檔的網址取決於提供給
針對每秒要求數執行 navigator.credentials.get
呼叫。
const credential = await navigator.credentials.get({
identity: {
context: 'signup',
providers: [{
configURL: 'https://accounts.idp.example/config.json',
clientId: '********',
nonce: '******'
}]
}
});
const { token } = credential;
將 IdP 設定檔位置的完整網址指定為 configURL
。時間
在 RP (RP) 上呼叫 navigator.credentials.get()
擷取含有 GET
要求的設定檔,但不含 Origin
標頭或
Referer
標頭。這項要求沒有 Cookie,且不會追蹤重新導向。
這麼做可有效防止 IdP 學習提出要求者的身分,以及哪些
RP 嘗試連線。例如:
GET /config.json HTTP/1.1
Host: accounts.idp.example
Accept: application/json
Sec-Fetch-Dest: webidentity
瀏覽器預期來自 IdP 的 JSON 回應,其中包含以下內容 屬性:
屬性 | 說明 |
---|---|
accounts_endpoint (必填) |
帳戶端點的網址。 |
client_metadata_endpoint (非必要) |
用戶端中繼資料端點的網址。 |
id_assertion_endpoint (必填) |
ID 斷言端點的網址。 |
disconnect (非必要) |
中斷連線端點的網址。 |
login_url (必填) |
使用者用來登入 IdP 的登入頁面網址。 |
branding (非必要) |
內含各種品牌宣傳選項的物件。 |
branding.background_color (非必要) |
品牌宣傳選項,設定「繼續為...」的背景顏色按鈕。使用相關的 CSS 語法
hex-color 、
hsl() ,
rgb() ,或
named-color 。 |
branding.color (非必要) |
品牌宣傳選項,用於設定「繼續為...」的文字顏色按鈕。使用相關的 CSS 語法
hex-color 、
hsl() ,
rgb() ,或
named-color 。 |
branding.icons (非必要) |
品牌宣傳選項,用於設定登入對話方塊中的圖示物件。圖示物件是包含兩個參數的陣列:
|
RP 可以透過 identity.context
值修改 FedCM 對話方塊 UI 的字串
,讓 navigator.credentials.get()
能容納預先定義的驗證方式
定義。選用屬性可以是 "signin"
(預設)、"signup"
或
"use"
或"continue"
。
![如何將品牌宣傳套用到 FedCM 對話方塊](https://developers-dot-devsite-v2-prod.appspot.com/static/privacy-sandbox/assets/images/RZwmFnyJChjlki8QsnBB.png?authuser=19&hl=zh-tw)
以下是 IdP 的回應主體範例:
{
"accounts_endpoint": "/accounts.php",
"client_metadata_endpoint": "/client_metadata.php",
"id_assertion_endpoint": "/assertion.php",
"disconnect_endpoint": "/disconnect.php",
"login_url": "/login",
"branding": {
"background_color": "green",
"color": "#FFEEAA",
"icons": [{
"url": "https://idp.example/icon.ico",
"size": 25
}]
}
}
瀏覽器擷取設定檔後,會將後續要求傳送至 IdP 端點:
![IdP 端點](https://developers-dot-devsite-v2-prod.appspot.com/static/privacy-sandbox/assets/images/idp-endpoints-a67327f46da51.png?authuser=19&hl=zh-tw)
帳戶端點
IdP 的帳戶端點會傳回使用者 目前登入的帳戶如果 IdP 支援多個帳戶,就會 端點將傳回所有已登入的帳戶。
瀏覽器會傳送含有 Cookie 的 GET
要求,其中包含 SameSite=None
,但沒有
client_id
參數、Origin
標頭或 Referer
標頭。這個
有效防止 IdP 得知使用者嘗試簽署的 RP
。例如:
GET /accounts.php HTTP/1.1
Host: accounts.idp.example
Accept: application/json
Cookie: 0x23223
Sec-Fetch-Dest: webidentity
收到要求後,伺服器應:
- 確認要求包含
Sec-Fetch-Dest: webidentity
HTTP 標頭。 - 將工作階段 Cookie 與已登入帳戶的 ID 進行比對。
- 在回應中提供帳戶清單。
瀏覽器預期的 JSON 回應包含 accounts
屬性
,其中包含帳戶資訊的陣列,且具有下列屬性:
屬性 | 說明 |
---|---|
id (必填) |
使用者的專屬 ID。 |
name (必填) |
使用者的名字和姓氏。 |
email (必填) |
使用者的電子郵件地址。 |
given_name (非必要) |
使用者的名字。 |
picture (非必要) |
使用者顯示圖片的網址。 |
approved_clients (非必要) |
使用者註冊的 RP 用戶端 ID 陣列。 |
login_hints (非必要) |
IdP 支援指定的所有可能篩選器類型陣列
帳戶。受限方可以叫用 navigator.credentials.get()
其中 loginHint 屬性
選擇性顯示指定帳戶 |
domain_hints (非必要) |
與帳戶相關聯的所有網域陣列。受限方可以
撥打 navigator.credentials.get() ,
domainHint 屬性,用來篩選
帳戶。 |
回應主體範例:
{
"accounts": [{
"id": "1234",
"given_name": "John",
"name": "John Doe",
"email": "john_doe@idp.example",
"picture": "https://idp.example/profile/123",
"approved_clients": ["123", "456", "789"],
"login_hints": ["demo1", "demo1@idp.example"]
}, {
"id": "5678",
"given_name": "Johnny",
"name": "Johnny",
"email": "johnny@idp.example",
"picture": "https://idp.example/profile/456",
"approved_clients": ["abc", "def", "ghi"],
"login_hints": ["demo2", "demo2@idp.example"],
"domain_hints": ["corp.example"]
}]
}
如果使用者尚未登入,系統會傳回 HTTP 401 (Unauthorized) 回應。
傳回的帳戶清單會供瀏覽器使用,但無法提供給 受限方。
用戶端中繼資料端點
IdP 的用戶端中繼資料端點會傳回依賴方的中繼資料,例如 受限方的隱私權政策和服務條款。受限方應提供自己的 預先提供給 IdP 的隱私權政策和服務條款。這些連結 使用者尚未在 RP 上註冊時,登入對話方塊就會顯示 也就是 IdP
瀏覽器使用 client_id
傳送 GET
要求
navigator.credentials.get
(不使用 Cookie)。例如:
GET /client_metadata.php?client_id=1234 HTTP/1.1
Host: accounts.idp.example
Origin: https://rp.example/
Accept: application/json
Sec-Fetch-Dest: webidentity
收到要求後,伺服器應:
- 決定
client_id
的 RP。 - 回應用戶端中繼資料。
用戶端中繼資料端點的屬性包括:
屬性 | 說明 |
---|---|
privacy_policy_url (非必要) |
受限方隱私權政策網址。 |
terms_of_service_url (非必要) |
受限方服務條款網址。 |
瀏覽器預期端點會收到 JSON 回應:
{
"privacy_policy_url": "https://rp.example/privacy_policy.html",
"terms_of_service_url": "https://rp.example/terms_of_service.html",
}
傳回的用戶端中繼資料會由瀏覽器使用,不會 這些可用頻道
ID 斷言端點
IdP 的 ID 斷言端點會為已登入的使用者傳回宣告。
當使用者使用 navigator.credentials.get()
登入 RP 網站時
呼叫,瀏覽器就會傳送含有 Cookie 的 POST
要求
SameSite=None
,而 application/x-www-form-urlencoded
內容類型
並附帶以下資訊:
屬性 | 說明 |
---|---|
client_id (必填) |
受限方的用戶端 ID。 |
account_id (必填) |
登入使用者的專屬 ID。 |
nonce (非必要) |
RP 提供的要求 Nonce。 |
disclosure_text_shown |
結果會是 "true" 或 "false" (而不是布林值) 的字串。如果沒有顯示揭露文字,結果會是 "false" 。當帳戶端點的回應 approved_clients 屬性清單包含 RP 的用戶端 ID,或瀏覽器過去在沒有 approved_clients 的情況下觀察到註冊當下,就會發生這種情況。 |
is_auto_selected |
如果對 RP 執行自動重新驗證,is_auto_selected 表示 "true" 。否則為 "false" 。這樣就能支援更多安全性相關功能。舉例來說,部分使用者可能偏好較高的安全性層級,而這需要明確在驗證程序中的使用者中介服務。如果 IdP 收到權杖要求時沒有這類中介服務,IdP 處理要求的方式就會有所不同。舉例來說,傳回錯誤代碼,讓 RP 可以使用 mediation: required 再次呼叫 FedCM API。 |
HTTP 標頭範例:
POST /assertion.php HTTP/1.1
Host: accounts.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=true
收到要求後,伺服器應:
- 使用 CORS (跨源資源) 回應要求 分享)。
- 確認要求包含
Sec-Fetch-Dest: webidentity
HTTP 標頭。 - 將
Origin
標頭與client_id
判定的受限方來源進行比對。 如果不相符,則拒絕。 - 將
account_id
與已登入帳戶的 ID 進行比對。拒絕 (如果符合以下情況) 不符合條件 - 以權杖回應。如果要求遭拒,回應時請傳回錯誤 回應。
憑證的核發方式取決於 IdP,但一般情況下,憑證的簽署方式為
帳戶 ID、用戶端 ID、核發者來源、nonce
等資訊,
RP 即可驗證該符記是否為正版
瀏覽器預期的 JSON 回應包含以下屬性:
屬性 | 說明 |
---|---|
token (必填) |
憑證是包含驗證憑證附加資訊的字串。 |
{
"token": "***********"
}
傳回的權杖會由瀏覽器傳遞至 RP,讓 RP 驗證驗證
傳回錯誤回應
id_assertion_endpoint
也可以傳回「錯誤」
回應,其中包含兩個選用欄位:
code
:IdP 可以從 OAuth 2.0 中選擇一個已知錯誤 指定的錯誤 list (invalid_request
、unauthorized_client
、access_denied
、server_error
和temporarily_unavailable
),或使用任意字串。如果是後者,Chrome 轉譯錯誤 UI 並顯示一般錯誤訊息,並將程式碼傳遞至 RP。url
:這個參數識別清楚易懂的網頁,內含 錯誤以向使用者提供該錯誤的額外資訊。這個欄位 很實用,因為瀏覽器無法在 原生使用者介面例如後續步驟連結、客服聯絡資訊 此類資訊等等如果使用者想進一步瞭解錯誤詳情 以及如何修正問題,他們可以透過瀏覽器使用者介面,造訪提供的網頁 瞭解詳情網址必須與 IdPconfigURL
相同的網站。
// id_assertion_endpoint response
{
"error" : {
"code": "access_denied",
"url" : "https://idp.example/error?type=access_denied"
}
}
取消連結端點
透過叫用 IdentityCredential.disconnect()
時,瀏覽器會傳送跨來源
POST
要求含有 SameSite=None
且內容類型為
application/x-www-form-urlencoded
連結到這個端點與
以下資訊:
屬性 | 說明 |
---|---|
account_hint |
IdP 帳戶的提示。 |
client_id |
受限方的用戶端 ID。 |
POST /disconnect.php HTTP/1.1
Host: idp.example
Origin: rp.example
Content-Type: application/x-www-form-urlencoded
Cookie: 0x123
Sec-Fetch-Dest: webidentity
account_hint=account456&client_id=rp123
收到要求後,伺服器應:
- 使用 CORS (跨源資源) 回應要求 分享)。
- 確認要求包含
Sec-Fetch-Dest: webidentity
HTTP 標頭。 - 將
Origin
標頭與client_id
判定的受限方來源進行比對。 如果不相符,則拒絕。 - 將
account_hint
與已登入帳戶的 ID 進行比對。 - 將使用者帳戶與 RP 取消連結。
- 以 JSON 格式以 JSON 格式回應瀏覽器 格式。
回應 JSON 酬載的範例如下所示:
{
"account_id": "account456"
}
如果 IdP 希望瀏覽器中斷所有與 相關聯的帳戶連線,
受限方,請傳遞與任何帳戶 ID 都不相符的字串,例如 "*"
。
登入網址
透過 Login Status API,IdP 必須通知使用者的
登入狀態。不過,狀態可能不同步,例如
工作階段逾時在這種情況下,
瀏覽器可以讓使用者透過登入頁面動態登入 IdP
透過 idp 設定檔的 login_url
指定的網址。
FedCM 對話方塊會顯示一則建議登入的訊息,如 下方圖片。
![A](https://developers-dot-devsite-v2-prod.appspot.com/static/privacy-sandbox/assets/images/blog/fedcm-120-1.png?authuser=19&hl=zh-tw)
當使用者點選「Continue」按鈕時,瀏覽器會開啟彈出式視窗 登入 IdP 的登入頁面。
![這項工具使用上非常簡便,可讓影片內容擁有者透過即時出價的市場機制,在 YouTube 上宣傳自己的影片。](https://developers-dot-devsite-v2-prod.appspot.com/static/privacy-sandbox/assets/images/blog/fedcm-120-2.png?authuser=19&hl=zh-tw)
此對話方塊是擁有第一方 Cookie 的一般瀏覽器視窗。隨便啦 對話方塊是由 IdP 組成,且沒有可用的視窗控點 對 RP 頁面提出跨來源通訊要求。在使用者 IdP 應能執行下列操作:
- 傳送
Set-Login: logged-in
標頭或呼叫navigator.login.setStatus("logged-in")
API,通知瀏覽器 位使用者已登入。 - 呼叫
IdentityProvider.close()
關閉對話方塊。
![A](https://developers-dot-devsite-v2-prod.appspot.com/static/privacy-sandbox/assets/images/blog/fedcm.gif?authuser=19&hl=zh-tw)
將使用者在識別資訊提供者上的登入狀態通知瀏覽器
Login Status API 是一種機制 網站 (尤其是 IdP) 會通知瀏覽器使用者的登入狀態 登入 IdP 的 IP 位址。導入這個 API,瀏覽器就能減少不必要的請求, IdP 服務,並降低潛在的時間攻擊。
IdP 可以傳送 HTTP 標頭,告知瀏覽器使用者的登入狀態
或是在使用者登入 IdP 或
系統會將使用者登出所有 IdP 帳戶。針對每個 IdP (透過
config URL),瀏覽器會保留代表登入狀態的三狀態變數
可能的值為 logged-in
、logged-out
和 unknown
。預設狀態
為 unknown
。
如要表示使用者已登入,請傳送 Set-Login: logged-in
HTTP 標頭
或 IdP 服務中的同網站子資源要求
來源:
Set-Login: logged-in
或者,您也可以呼叫 JavaScript API navigator.login.setStatus("logged-in")
navigator.login.setStatus("logged-in")
這些呼叫會將使用者的登入狀態記錄為 logged-in
。使用者登入時
狀態為 logged-in
,呼叫 FedCM 的 RP 會向 IdP 的
帳戶端點,並在 FedCM 中向使用者顯示可用的帳戶
對話方塊
如要表明使用者已經登出所有帳戶,請在頂層導覽或同網站子資源中傳送 Set-Login:
logged-out
HTTP 標頭
發生下列情況:
Set-Login: logged-out
或者,您也可以呼叫 JavaScript API navigator.login.setStatus("logged-out")
navigator.login.setStatus("logged-out")
這些呼叫會將使用者的登入狀態記錄為 logged-out
。當使用者
登入狀態為 logged-out
,因此呼叫 FedCM 失敗,且不會顯示
要求傳送至 IdP 帳戶端點。
在 IdP 使用登入狀態傳送信號前,系統會設定 unknown
狀態
也能使用 Google Cloud CLI 或
Compute Engine API我們導入 Unknown
來提高轉換效率,因為使用者
您在這個 API 推出時已登入 IdP。IdP 可能沒有
首次叫用 FedCM 時,向瀏覽器發送通知。在本
時,Chrome 會向 IdP 的帳戶端點發出要求,並將
根據帳戶端點的回應
定義狀態:
- 如果端點傳回有效帳戶清單,請將狀態更新為
logged-in
並開啟 FedCM 對話方塊即可顯示這些帳戶。 - 如果端點未傳回任何帳戶,請將狀態更新為「
logged-out
」並 或 FedCM 呼叫失敗
讓使用者透過動態登入流程登入
雖然 IdP 持續將使用者的登入狀態告知瀏覽器,
不符合同步狀態,例如工作階段到期時瀏覽器會嘗試
在登入狀態為
logged-in
,但伺服器未傳回帳戶,因為工作階段已不存在
廣告。在此情況下,瀏覽器可透過動態方式,讓使用者以動態方式登入
從彈出式視窗連線至 IdP。
透過識別資訊提供者登入依賴方
一旦 IdP 的設定和端點可用後,RP 就能呼叫
navigator.credentials.get()
要求允許使用者登入 RP
登入 IdP 服務。
呼叫 API 前,您必須確認 [FedCM] 列於 使用者的瀏覽器]。如要確認 FedCM 是否可用,請在 FedCM 實作:
if ('IdentityCredential' in window) {
// If the feature is available, take action
}
如要要求使用者從 RP 登入 IdP,請按照下列步驟操作: 例如:
const credential = await navigator.credentials.get({
identity: {
providers: [{
configURL: 'https://accounts.idp.example/config.json',
clientId: '********',
nonce: '******'
}]
}
});
const { token } = credential;
providers
屬性會採用 IdentityProvider
的陣列
含有
並列出以下屬性:
屬性 | 說明 |
---|---|
configURL (必填) |
IdP 設定檔的完整路徑。 |
clientId (必填) |
RP 的用戶端 ID,由 IdP 核發。 |
nonce (非必要) |
這個隨機字串,可確保系統針對這個特定要求發出回應。可防止重送攻擊。 |
loginHint (非必要) |
指定login_hints
帳戶端點、FedCM
對話方塊選擇性顯示指定的帳戶。 |
domainHint (非必要) |
指定domain_hints
帳戶端點、FedCM
對話方塊中,選擇性顯示指定的帳戶。 |
瀏覽器處理註冊和登入的方式會因
帳戶清單回應中存在 approved_clients
端點。瀏覽器不會顯示
傳送文字:"To continue with ...." (如果使用者已註冊 RP)。
註冊狀態取決於是否符合下列條件 是否滿足:
- 如果
approved_clients
包含受限方的clientId
, - 如果瀏覽器記住使用者已經註冊 RP,
當 RP 呼叫 navigator.credentials.get()
時,下列活動會
地點:
- 瀏覽器會傳送要求並擷取多份文件:
- 瀏覽器會顯示使用者可用來登入的帳戶清單。 以及服務條款和隱私權政策 (如果有的話)
- 使用者選擇要登入的帳戶後,向 ID 發出的要求 斷言端點會傳送至 IdP,以擷取 產生下一個符記
- RP 可以驗證權杖來驗證使用者。
![login API 呼叫](https://developers-dot-devsite-v2-prod.appspot.com/static/privacy-sandbox/assets/images/login-api-call-a55fdb8f753e8.png?authuser=19&hl=zh-tw)
RP 應支援不支援 FedCM 的瀏覽器 使用者應該要能使用現有的非 FedCM 登入程序。結束時間 逐步淘汰第三方 Cookie 或許不會發生問題
RP 伺服器驗證權杖後,RP 就會註冊使用者,或 讓使用者登入並開始新的工作階段。
登入提示 API
使用者登入後,有時會要求依賴方 (RP) 提出要求 重新驗證但使用者可能不確定自己使用的是哪個帳戶。 如果 RP 能指定用來登入的帳戶,代表 讓使用者選擇帳戶。
受限方可透過叫用的方式,選擇顯示特定帳戶
包含 loginHint
屬性的 navigator.credentials.get()
,其中包含下列其中一個屬性:
從帳戶清單擷取 login_hints
個值
端點,如以下程式碼範例所示:
return await navigator.credentials.get({
identity: {
providers: [{
configURL: "https://idp.example/manifest.json",
clientId: "123",
nonce: nonce,
loginHint : "demo1@example.com"
}]
}
});
如果沒有與 loginHint
相符的帳戶,FedCM 對話方塊會顯示登入提示。
這可讓使用者登入與要求提示相符的 IdP 帳戶
受限方。使用者輕觸提示後,系統會開啟彈出式視窗,其中顯示
設定檔中指定的登入網址。連結
並附上登入提示和網域提示查詢參數。
網域提示 API
在某些情況下,RP 只會知道有一個帳戶所連結的帳戶 必須允許某些網域登入該網站。這在 存取網站僅供企業存取的企業情境 網域。為了提供更優質的使用者體驗,FedCM API 僅允許 RP API 顯示可能用於登入 RP 的帳戶。這麼做可避免情況 使用者嘗試透過公司外部的帳戶登入 RP 網域,只有在之後才會提供錯誤訊息 (或者忽略 登入失敗) 因為使用的帳戶類型不正確。
受限方可透過叫用,選擇性地只顯示相符的帳戶
包含 domainHint
屬性的 navigator.credentials.get()
,其中包含下列其中一個屬性:
從帳戶清單擷取 domain_hints
個值
端點,如以下程式碼範例所示:
return await navigator.credentials.get({
identity: {
providers: [{
configURL: "https://idp.example/manifest.json",
clientId: "abc",
nonce: nonce,
domainHint : "corp.example"
}]
}
});
如果沒有與 domainHint
相符的帳戶,FedCM 對話方塊會顯示登入提示。
這可讓使用者登入與要求提示相符的 IdP 帳戶
受限方。使用者輕觸提示後,系統會開啟彈出式視窗,其中顯示
設定檔中指定的登入網址。連結
並附上登入提示和網域提示查詢參數。
![如果沒有帳戶與 domainHint 相符,系統會顯示登入提示範例。](https://developers-dot-devsite-v2-prod.appspot.com/static/privacy-sandbox/assets/images/blog/fedcm-123.jpg?authuser=19&hl=zh-tw)
domainHint
時的登入提示範例。顯示錯誤訊息
IdP 有時可能無法出於正當理由核發權杖,例如 就像用戶端未獲授權時一樣,伺服器暫時無法使用。如果 IdP 會傳回「錯誤」該 RP 就能抓取回應, 通知使用者,指出顯示瀏覽器使用者介面 IdP 的 IP 位址。
![A](https://developers-dot-devsite-v2-prod.appspot.com/static/privacy-sandbox/assets/images/blog/fedcm-120-4.png?authuser=19&hl=zh-tw)
try {
const cred = await navigator.credentials.get({
identity: {
providers: [
{
configURL: "https://idp.example/manifest.json",
clientId: "1234",
},
],
}
});
} catch (e) {
const code = e.code;
const url = e.url;
}
在初次驗證後自動重新驗證使用者
FedCM 自動重新驗證 (簡稱「auto-reauthn」) 可讓使用者在進行搜尋時,自動重新驗證 返回 FedCM。「最初 驗證」這表示使用者建立帳戶,或登入 RP 的 ,在 FedCM 登入對話方塊中輕觸「以下列身分繼續...」按鈕 在同一瀏覽器執行個體上 首次使用同一個應用程式
在使用者建立 聯合帳戶防止追蹤 (這是 FedCM 的主要目標之一) 但使用者過一陣子後就沒那麼麻煩了 使用者授予權限,允許 RP 和 IdP 之間通訊 強制執行其他明確的使用者,對於隱私權或安全性沒有助益 確認他們先前確認過的內容。
透過自動重新驗證,瀏覽器會根據您選用的選項變更行為
呼叫 navigator.credentials.get()
時指定 mediation
。
const cred = await navigator.credentials.get({
identity: {
providers: [{
configURL: "https://idp.example/fedcm.json",
clientId: "1234",
}],
},
mediation: 'optional', // this is the default
});
// `isAutoSelected` is `true` if auto-reauthn was performed.
const isAutoSelected = cred.isAutoSelected;
mediation
是 Credential Management 中的屬性
API
運作方式
方式
如同
PasswordCredential
和
FederatedCredential
而且還受到
PublicKeyCredential
屬性接受以下四個值:
'optional'
(預設):可能的話,需要透過中介服務進行自動重新驗證。三 建議您在登入頁面選擇這個選項。'required'
:一律需要中介服務才能繼續操作,例如按下 「繼續」按鈕。如果您預期使用者會遇到 在每次需要驗證時明確授予權限。'silent'
:如果情況允許,自動重新驗證,且不需要 中介服務。我們建議在其他網頁上選取這個選項 以及您想讓使用者保持登入狀態的登入頁面 例如運送網站上的商品頁面,或是新聞中的文章頁面 網站。'conditional'
:用於 WebAuthn,目前不適用於 FedCM。
使用此呼叫時,系統會在下列情況下自動重新驗證:
- 可以使用 FedCM。例如:使用者尚未停用 FedCM 為全域或設定中的 RP。
- 使用者只透過一個 FedCM API 登入這個網站 。
- 使用者已透過該帳戶登入 IdP。
- 系統並未在過去 10 分鐘內進行自動重新驗證。
- 尚未呼叫 RP
之後每月
navigator.credentials.preventSilentAccess()
先前的登入。
符合這些條件時,系統就會嘗試自動重新驗證
FedCM navigator.credentials.get()
一叫用,就會啟動。
如果設為 mediation: optional
,系統可能會自動重新驗證
無法使用,原因如下:
只有瀏覽器知道RP 可以檢查 RP 是否執行自動重新驗證
檢查 isAutoSelected
屬性。
這有助於評估 API 效能,並據此改善使用者體驗。
此外,如果未提供,系統會提示使用者以明確方式登入
使用者中介服務,即 mediation: required
的流程。
使用「preventSilentAccess()
」執行中介服務
使用者登出後立即自動驗證,不會導致
良好的使用者體驗因此,FedCM 有 10 分鐘的安靜期
自動重新驗證以防止發生這種行為這代表系統會自動重新驗證
最多每 10 分鐘一次,除非使用者在
10 分鐘。受限方應呼叫 navigator.credentials.preventSilentAccess()
以
在使用者登出時,明確要求瀏覽器停用自動重新驗證功能
請務必明確輸入 RP,例如按下登出按鈕
function signout() {
navigator.credentials.preventSilentAccess();
location.href = '/signout';
}
使用者可以在設定中選擇不使用自動重新驗證
使用者可以透過設定選單停用自動重新驗證功能:
- 如果你使用電腦版 Chrome,請前往
chrome://password-manager/settings
>登入 。 - 在 Android Chrome 中開啟「設定」>密碼管理工具 >輕觸 右上角的齒輪圖示 >自動登入。
如果停用切換按鈕,使用者就能選擇停用自動重新驗證行為 。如果使用者 在 Chrome 執行個體上登入 Google 帳戶,然後同步處理作業
將 IdP 與 RP 中斷連線
如果使用者先前已透過 FedCM 使用 IdP 登入 RP,
瀏覽器在本機上記住這個關係
帳戶。受限方可透過叫用
IdentityCredential.disconnect()
函式。您可以從
頂層 RP 影格RP 必須傳遞 configURL
,也就是所用的 clientId
(位於 IdP 之下),以及要中斷 IdP 連線的 accountHint
。帳戶
提示可以是任意字串,只要中斷連線端點可以識別
像是電子郵件地址或使用者 ID (不一定)
與帳戶清單端點提供的帳戶 ID 相符:
// Disconnect an IdP account "account456" from the RP "https://idp.com/". This is invoked on the RP domain.
IdentityCredential.disconnect({
configURL: "https://idp.com/config.json",
clientId: "rp123",
accountHint: "account456"
});
IdentityCredential.disconnect()
會傳回 Promise
。這麼做可能會擲回
例外狀況:
- 使用者尚未透過 FedCM 使用 IdP 登入 RP。
- 這個 API 是從沒有 FedCM 權限政策的 iframe 中叫用。
- configURL 無效,或缺少中斷連線的端點。
- 無法執行內容安全政策 (CSP) 檢查。
- 目前有待處理的取消連結要求。
- 使用者在瀏覽器設定中停用 FedCM。
當 IdP 中斷連線的端點傳回 回應,RP 和 IdP 與 問題就會解決未連結帳戶的 ID 為 端點。
在跨來源 iframe 中呼叫 FedCM
您可以從跨來源 iframe 中使用
identity-credentials-get
權限政策 (如果上層頁框允許)。目的地:
方法是將 allow="identity-credentials-get"
屬性附加至 iframe 代碼
如下所示:
<iframe src="https://fedcm-cross-origin-iframe.glitch.me" allow="identity-credentials-get"></iframe>
您可以在範例中查看實際使用狀況。
或者,如果上層頁框要求限制來源呼叫 FedCM,
傳送包含允許來源清單的 Permissions-Policy
標頭。
Permissions-Policy: identity-credentials-get=(self "https://fedcm-cross-origin-iframe.glitch.me")
如要進一步瞭解權限政策的運作方式,請參閱: 瀏覽器功能及相關權限 政策。