Federated Credential Management API 开发者指南

了解如何使用 FedCM 进行可保护隐私的身份联合。

FedCM（联合凭据管理）是一种适用于联合身份服务（例如“使用以下账号登录”）的隐私保护方法；借助该方法，用户可以登录网站，而无需与身份服务或网站共享其个人信息。

如需详细了解 FedCM 用例、用户流和 API 路线图，请参阅 FedCM API 简介。

FedCM 开发环境

您需要在 Chrome 中的 IdP 和 RP 上都拥有安全上下文（HTTPS 或 localhost），才能使用 FedCM。

在 Android 版 Chrome 上调试代码

在本地设置并运行服务器以调试您的 FedCM 代码。您可以在使用具有端口转发功能的 USB 线连接的 Android 设备上，在 Chrome 中访问此服务器。

按照远程调试 Android 设备中的说明，您可以使用桌面设备上的开发者工具调试 Android 版 Chrome。

在 Chrome 上阻止第三方 Cookie

通过将 Chrome 配置为屏蔽第三方 Cookie 来模拟逐步淘汰这些 Cookie
将 Chrome 配置为屏蔽第三方 Cookie 来模拟逐步淘汰第三方 Cookie 的情形

在实际强制执行 FedCM 之前，您可以先在 Chrome 上测试 FedCM 如何在不使用第三方 Cookie 的情况下工作。

如需阻止第三方 Cookie，请使用无痕模式，或者在 chrome://settings/cookies 或移动设备的桌面设备设置中选择“阻止第三方 Cookie”，或在移动设备上依次转到设置 > 网站设置 > Cookie。

使用 FedCM API

如需与 FedCM 集成，您可以为帐号列表、断言发布以及可选的客户端元数据创建知名文件、配置文件和端点。

FedCM 会公开 JavaScript API，RP 可使用这些 API 通过 IdP 登录。

创建一个众所周知的文件

为防止跟踪器滥用 API，必须通过 IdP 的 eTLD+1 的 /.well-known/web-identity 提供一个知名文件。

例如，如果 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 配置文件网址，这些网址可被 RP 在 navigator.credentials.get 中指定为 configURL 的路径部分。该数组中网址字符串的数量不得超过一个，但该数量可能会随着您的反馈而发生变化。

创建 IdP 配置文件和端点

IdP 配置文件提供了浏览器所需端点的列表。IdP 将托管此配置文件以及所需的端点和网址。所有 JSON 响应都必须使用 application/json 内容类型提供。

配置文件的网址由提供给在 RP 上执行的 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 上调用 navigator.credentials.get() 时，浏览器会使用不带 Origin 标头或 Referer 标头的 GET 请求来提取配置文件。该请求没有 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（可选） 品牌选项，用于设置图标对象（显示在登录对话框中）。图标对象是一个包含两个参数的数组：
  • url（必需）：图标图片的网址。不支持 SVG 图片。
  • size（可选）：图标尺寸，应用假定为方形和单一分辨率。此数字必须大于或等于 25。

RP 可以通过 navigator.credentials.get() 的 identity.context 值修改 FedCM 对话框界面中的字符串，以适应预定义的身份验证上下文。可选属性可以是 "signin"（默认）、"signup"、"use" 或 "continue" 中的一个。

如何将品牌应用于 FedCM 对话框
品牌如何应用于 FedCM 对话框

以下是 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 端点
IdP 端点

账号端点

IdP 的帐号端点会返回用户当前在 IdP 上登录的帐号列表。如果 IdP 支持多个帐号，此端点将返回所有已登录的帐号。

浏览器发送 GET 请求，其中包含带有 SameSite=None 的 Cookie，但不带 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

收到请求后，服务器应执行以下操作：

  1. 验证请求是否包含 Sec-Fetch-Dest: webidentity HTTP 标头。
  2. 将会话 Cookie 与已登录帐号的 ID 进行匹配。
  3. 返回帐号列表进行响应。

浏览器需要的 JSON 响应包括 accounts 属性以及一系列具有以下属性的帐号信息：

媒体资源 说明
id（必需） 用户的唯一 ID。
name（必需） 用户的姓氏和姓氏。
email（必需） 用户的电子邮件地址。
given_name（可选） 用户的名字。
picture（可选） 用户头像图片的网址。
approved_clients（可选） 用户注册的 RP 客户端 ID 数组。
login_hints（可选） IdP 支持指定帐号的所有可能过滤条件类型的数组。RP 可以使用 loginHint 属性调用 navigator.credentials.get()，以选择性地显示指定的帐号。
domain_hints（可选） 一个数组，包含与该帐号相关联的所有网域。RP 可以使用 domainHint 属性调用 navigator.credentials.get() 来过滤帐号。

响应正文示例：

{
  "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)。

返回的帐号列表会被浏览器使用，并且不会提供给 RP。

客户端元数据端点

IdP 的客户端元数据端点返回依赖方的元数据，例如 RP 的隐私权政策和服务条款。RP 应提前向 IdP 提供其隐私权政策和服务条款的链接。如果用户尚未通过 IdP 在 RP 上注册，登录对话框中会显示这些链接。

浏览器使用不带 Cookie 的 client_id navigator.credentials.get 发送 GET 请求。例如：

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

收到请求后，服务器应执行以下操作：

  1. 确定 client_id 的 RP。
  2. 使用客户端元数据进行响应。

客户端元数据端点的属性包括：

媒体资源 说明
privacy_policy_url（可选） RP 隐私权政策网址。
terms_of_service_url（可选） RP 服务条款网址。

浏览器期望端点返回 JSON 响应：

{
  "privacy_policy_url": "https://rp.example/privacy_policy.html",
  "terms_of_service_url": "https://rp.example/terms_of_service.html",
}

返回的客户端元数据被浏览器使用，并且不可供 RP 使用。

ID 断言端点

IdP 的 ID 断言端点会为已登录的用户返回断言。当用户使用 navigator.credentials.get() 调用登录 RP 网站时，浏览器会向此端点发送一个 POST 请求（其中包含具有 SameSite=None 的 Cookie，内容类型为 application/x-www-form-urlencoded），其中包含以下信息：

媒体资源 说明
client_id（必需） RP 的客户端标识符。
account_id（必需） 登录用户的唯一 ID。
nonce（可选） 请求 Nonce，由 RP 提供。
disclosure_text_shown 返回 "true" 或 "false" 字符串（而不是布尔值）。如果未显示披露文字，则结果为 "false"。如果 RP 的客户端 ID 包含在帐号端点的响应的 approved_clients 属性列表中，或者浏览器在过去检测到注册时刻（缺少 approved_clients），就会发生这种情况。
is_auto_selected 如果对 RP 执行了自动重新身份验证，is_auto_selected 表示 "true"。否则为 "false"。这有助于支持更多与安全相关的功能。例如，有些用户可能更喜欢更高的安全等级，这就要求在身份验证时明确指定用户中介。如果 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

收到请求后，服务器应执行以下操作：

  1. 使用 CORS（跨域资源共享）响应请求。
  2. 验证请求是否包含 Sec-Fetch-Dest: webidentity HTTP 标头。
  3. 将 Origin 标头与由 client_id 确定的 RP 源进行匹配。如果不匹配，则拒绝。
  4. 将 account_id 与已登录帐号的 ID 进行匹配。如果不匹配，则拒绝。
  5. 使用令牌进行响应。如果请求被拒绝，则使用错误响应进行响应。

令牌的颁发方式由 IdP 决定，但一般而言，它会使用帐号 ID、客户端 ID、颁发者来源、nonce 等信息进行签名，以便 RP 可以验证令牌的真实性。

浏览器需要包含以下属性的 JSON 响应：

媒体资源 说明
token（必需） 令牌是一个字符串，其中包含有关身份验证的声明。 
{
  "token": "***********"
}

返回的令牌由浏览器传递给 RP，以便 RP 可以验证身份验证。

返回错误响应

id_assertion_endpoint 还可以返回“错误”响应，其中包含两个可选字段：

  • code：IdP 可以从 OAuth 2.0 指定的错误列表中选择一个已知错误（invalid_request、unauthorized_client、access_denied、server_error 和 temporarily_unavailable），也可以使用任意字符串。如果是后者，Chrome 会呈现错误界面并显示一般错误消息，并将代码传递给 RP。
  • url：用于识别包含错误相关信息的人类可读网页，以便向用户提供与错误有关的其他信息。此字段对用户非常有用，因为浏览器无法在原生界面中提供丰富的错误消息。例如，后续步骤链接、客户服务联系信息等。如果用户想要详细了解错误详情及修正方法，可以从浏览器界面访问所提供的页面，以查看详情。该网址必须与 IdP configURL 属于同一网站。
// id_assertion_endpoint response
{
  "error" : {
     "code": "access_denied",
     "url" : "https://idp.example/error?type=access_denied"
  }
}

断开端点连接

通过调用 IdentityCredential.disconnect()，浏览器会向此断开连接端点发送一个包含 Cookie SameSite=None、内容类型为 application/x-www-form-urlencoded 的跨源 POST 请求，其中包含以下信息：

媒体资源 说明
account_hint IdP 账号的提示。
client_id RP 的客户端标识符。 
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

收到请求后，服务器应执行以下操作：

  1. 使用 CORS（跨域资源共享）响应请求。
  2. 验证请求是否包含 Sec-Fetch-Dest: webidentity HTTP 标头。
  3. 将 Origin 标头与由 client_id 确定的 RP 源进行匹配。如果不匹配，则拒绝。
  4. 将 account_hint 与已登录的账号的 ID 进行匹配。
  5. 断开用户帐号与 RP 的连接。
  6. 以 JSON 格式使用已识别的用户帐号信息响应浏览器。

响应 JSON 载荷示例如下所示：

{
  "account_id": "account456"
}

相反，如果 IdP 希望浏览器断开与 RP 关联的所有帐号的关联，请传递一个与任何帐号 ID 都不匹配的字符串，例如 "*"。

登录网址

借助 Login status API，IdP 必须将用户的登录状态告知浏览器。但是，状态可能不同步，例如当会话过期时。在这种情况下，浏览器可以动态地让用户通过 IdP 配置文件的 login_url 指定的登录页面网址登录 IdP。

FedCM 对话框会显示一条建议登录的消息，如下图所示。

A
一个建议登录 IdP 的 FedCM 对话框。

当用户点击 Continue 按钮时，浏览器会打开一个显示 IdP 登录页面的弹出式窗口。

An
点击“登录 IdP”按钮后显示的示例对话框。

该对话框是一个包含第一方 Cookie 的常规浏览器窗口。对话框中的操作由 IdP 决定，没有窗口句柄可以向 RP 页面发出跨源通信请求。用户登录后，IdP 应执行以下操作：

  • 发送 Set-Login: logged-in 标头或调用 navigator.login.setStatus("logged-in") API 以通知浏览器用户已登录。
  • 调用 IdentityProvider.close() 以关闭对话框。
A
用户在使用 FedCM 登录 IdP 后登录了 RP。

将用户在身份提供方处的登录状态告知浏览器

Login status API 是一种机制，在这种机制中，网站（尤其是 IdP）会向浏览器通知用户在 IdP 上的登录状态。借助此 API，浏览器可以减少向 IdP 发送的不必要请求并缓解潜在的计时攻击。

当用户在 IdP 上登录或退出其所有 IdP 帐号时，IdP 可以通过以下两种方式向浏览器表明用户的登录状态：发送 HTTP 标头或调用 JavaScript API。对于每个 IdP（由其配置网址标识），浏览器都会保留一个表示登录状态的三态变量，该变量可能具有 logged-in、logged-out 和 unknown 值。默认状态为 unknown。

如需表明用户已登录，请在顶级导航栏中发送 Set-Login: logged-in HTTP 标头，或在 IdP 源站发送同网站子资源请求：

Set-Login: logged-in

或者，在顶级导航栏中从 IdP 来源调用 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 标头，或在 IdP 来源处发送同网站子资源请求：

Set-Login: logged-out

或者，在顶级导航栏中从 IdP 来源调用 JavaScript API navigator.login.setStatus("logged-out")：

navigator.login.setStatus("logged-out")

这些调用会将用户的登录状态记录为 logged-out。当用户的登录状态为 logged-out 时，如果不向 IdP 的帐号端点发出请求，调用 FedCM 会静默失败。

unknown 状态是在 IdP 使用 LoginStatus API 发送信号之前设置的。引入了 Unknown 以改进过渡，因为在此 API 发布时，用户可能已经登录 IdP。IdP 可能没有机会在首次调用 FedCM 时向浏览器发出信号。在这种情况下，Chrome 会向 IdP 的帐号端点发出请求，并根据来自帐号端点的响应更新状态：

  • 如果端点返回活跃帐号列表，请将状态更新为 logged-in，并打开 FedCM 对话框以显示这些帐号。
  • 如果端点未返回任何帐号，请将状态更新为 logged-out 并失败 FedCM 调用。

让用户通过动态登录流程登录

即使 IdP 不断将用户的登录状态告知浏览器，它也可能不同步，例如当会话过期时。当登录状态为 logged-in 时，浏览器会尝试向帐号端点发送基于凭据的请求，但由于会话不再可用，服务器不会返回任何帐号。在这种情况下，浏览器可以动态让用户通过弹出式窗口登录 IdP。

登录到身份提供方的依赖方

IdP 的配置和端点可用后，RP 可以调用 navigator.credentials.get() 来请求允许用户使用 IdP 登录 RP。

在调用该 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（必需） 由 IdP 签发的 RP 的客户端标识符。
nonce（可选） 一个随机字符串，用于确保系统针对此特定请求发出响应。防止重放攻击。
loginHint（可选） 通过指定帐号端点提供的某个 login_hints 值，FedCM 对话框会选择性地显示指定的帐号。
domainHint（可选） 通过指定帐号端点提供的某个 domain_hints 值，FedCM 对话框会选择性地显示指定的帐号。

浏览器处理注册和登录用例的方式有所不同，具体取决于帐号列表端点响应中是否存在 approved_clients。如果用户已经注册 RP，浏览器不会显示披露文字“To continue with ....”。

注册状态取决于是否满足以下条件：

  • 如果 approved_clients 包含 RP 的 clientId，
  • 如果浏览器记住用户已注册 RP。
用户使用 FedCM 登录 RP

当 RP 调用 navigator.credentials.get() 时，会发生以下 activity：

  1. 浏览器发送请求并提取多个文档：
    1. 知名文件和用于声明端点的 IdP 配置文件。
    2. 帐号列表。
    3. 可选：从客户端元数据端点获取的 RP 的隐私权政策和服务条款的网址。
  2. 浏览器会显示用户可以用于登录的帐号列表，以及服务条款和隐私权政策（如果有）。
  3. 用户选择登录帐号后，系统会向 IdP 发送对 ID 断言端点的请求，以检索令牌。
  4. RP 可以验证令牌以对用户进行身份验证。
login API 调用
登录 API 调用

RP 应支持不支持 FedCM 的浏览器，因此用户应该能够使用现有的非 FedCM 登录流程。在完全淘汰第三方 Cookie 之前，这应该不会出现问题。

RP 服务器验证令牌后，RP 可能会注册用户，或者允许用户登录并启动新会话。

登录提示 API

用户登录后，有时依赖方 (RP) 会要求用户重新进行身份验证。但是，用户可能不确定自己使用的是哪个帐号。如果 RP 可以指定要使用哪个帐号登录，则用户会更轻松地选择帐号。

RP 可以通过使用从帐号列表端点中提取的其中一个 login_hints 值来调用 navigator.credentials.get()，以选择性地显示特定帐号，如以下代码示例所示：loginHint

return await navigator.credentials.get({
  identity: {
    providers: [{
      configURL: "https://idp.example/manifest.json",
      clientId: "123",
      nonce: nonce,
      loginHint : "demo1@example.com"
    }]
  }
});

如果没有与 loginHint 匹配的帐号，FedCM 对话框会显示登录提示，允许用户登录与 RP 请求的提示匹配的 IdP 帐号。当用户点按提示时，系统将使用配置文件中指定的登录网址打开一个弹出式窗口。然后，该链接会被附加登录提示和网域提示查询参数。

域提示 API

在某些情况下，RP 已经知道只有与特定网域关联的帐号才能登录该网站。在企业场景中，这尤其常见，因为在这种情况下要访问的网站仅限于企业网域。为了提供更好的用户体验，FedCM API 允许 RP 仅显示可用于登录 RP 的帐号。这样可以防止用户尝试使用公司网域以外的帐号登录 RP，但系统稍后却收到错误消息（或在登录不起作用的情况下使系统静音），因为未使用正确的帐号类型。

RP 可以通过使用从帐号列表端点提取的某个 domain_hints 值来调用 navigator.credentials.get()，以选择性地仅显示匹配的帐号，如以下代码示例所示：domainHint

return await navigator.credentials.get({
  identity: {
    providers: [{
      configURL: "https://idp.example/manifest.json",
      clientId: "abc",
      nonce: nonce,
      domainHint : "corp.example"
    }]
  }
});

如果没有与 domainHint 匹配的帐号，FedCM 对话框会显示登录提示，允许用户登录与 RP 请求的提示匹配的 IdP 帐号。当用户点按提示时，系统将使用配置文件中指定的登录网址打开一个弹出式窗口。然后，该链接会被附加登录提示和网域提示查询参数。

没有帐号与 domainHint 匹配的登录提示示例。
没有与 domainHint 匹配的账号时的登录提示示例。

显示错误消息

有时，IdP 可能会因正当原因无法颁发令牌，例如当客户端未经授权时，服务器暂时不可用。如果 IdP 返回“错误”响应，RP 可以捕获该响应，而且 Chrome 会通过显示包含 IdP 提供的错误信息的浏览器界面来通知用户。

A
一个 FedCM 对话框，在用户尝试登录失败后显示错误消息。该字符串与错误类型相关联。
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 自动重新身份验证（简称“自动重新验证”）可让用户在通过 FedCM 进行初始身份验证后返回时自动重新进行身份验证。这里的“初始身份验证”表示用户首次在同一浏览器实例上点按 FedCM 登录对话框中的“Continue as...”按钮，以登录 RP 的网站或登录 RP 的网站。

虽然在用户创建联合帐号以防止跟踪之前提供明确的用户体验（这是 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 是凭据管理 API 中的一个属性，其行为方式与 PasswordCredential 和 FederatedCredential相同，并且部分受 PublicKeyCredential 支持。该属性接受以下四个值：

  • 'optional'（默认）：如果可能，自动重新验证；否则，需要中介。我们建议您在登录页面上选择此选项。
  • 'required'：始终需要中介才能继续，例如，点击界面上的“继续”按钮。如果您的用户希望在每次需要进行身份验证时都明确授予权限，请选择此选项。
  • 'silent'：如果可能，自动重新验证身份；如果没有，则静默失败，无需中介。我们建议在专用登录页面以外的页面（例如，货运网站上的商品页面或新闻网站上的文章页面）上选择此选项，以便用户保持登录状态。
  • 'conditional'：用于 WebAuthn，目前不适用于 FedCM。

在以下情况下，使用此调用会自动重新进行身份验证：

  • FedCM 可供使用。例如，用户尚未在设置中全局停用 FedCM 或为 RP 停用 FedCM。
  • 用户仅通过一个具有 FedCM API 的帐号在此浏览器上登录了网站。
  • 用户使用该帐号登录 IdP。
  • 自动重新验证未在过去 10 分钟内发生。
  • 上次登录后，RP 未调用 navigator.credentials.preventSilentAccess()。

满足这些条件后，系统会在调用 FedCM navigator.credentials.get() 后立即尝试自动重新验证用户身份。

如果设置为 mediation: optional，则自动重新身份验证可能不可用，原因只有浏览器知道；RP 可以通过检查 isAutoSelected 属性来检查是否已执行自动重新身份验证。

这有助于评估 API 性能并相应地改善用户体验。 此外，当该功能不可用时，系统可能会通过明确的用户中介（一个具有 mediation: required 的流程）提示用户登录。

用户通过 FedCM 自动重新进行身份验证。

使用 preventSilentAccess() 强制执行中介

在用户退出后立即自动重新进行身份验证，这不会带来非常好的用户体验。因此，FedCM 在自动重新身份验证后会留出 10 分钟的静默期以防止此行为。这意味着，自动重新验证最多每 10 分钟进行一次，除非用户在 10 分钟内重新登录。当用户明确从 RP 退出（例如，通过点击退出按钮）时，RP 应调用 navigator.credentials.preventSilentAccess() 以明确请求浏览器停用自动重新身份验证功能。

function signout() {
  navigator.credentials.preventSilentAccess();
  location.href = '/signout';
}

用户可以在设置中选择停用自动重新验证

用户可以通过“设置”菜单选择停用自动重新验证功能：

  • 若使用桌面版 Chrome，请前往 chrome://password-manager/settings > 自动登录。
  • 在 Android Chrome 上，依次打开设置 > 密码管理工具 > 点按右上角的齿轮图标 >“自动登录”。

通过停用此切换开关，用户可以完全停用自动重新身份验证行为。如果用户在 Chrome 实例上登录 Google 帐号并启用了同步功能，则此设置会存储在设备之间并保持同步。

断开 IdP 与 RP 的连接

如果用户之前已通过 FedCM 使用 IdP 登录 RP，浏览器会将这种关系在本地记忆为已关联帐号的列表。RP 可以通过调用 IdentityCredential.disconnect() 函数发起断开连接。可以从顶级 RP 帧调用此函数。RP 需要传递 configURL、其在 IdP 下使用的 clientId 以及 accountHint，以便 IdP 断开连接。帐号提示可以是任意字符串，前提是断开连接端点可以识别帐号，例如电子邮件地址或用户 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。此 promise 可能会由于以下原因抛出异常：

  • 用户未通过 FedCM 使用 IdP 登录 RP。
  • 此 API 是从没有 FedCM 权限政策的 iframe 中调用的。
  • config网址 无效或缺少断开连接端点。
  • 内容安全政策 (CSP) 检查失败。
  • 有一个待处理的断开连接请求。
  • 用户在浏览器设置中停用了 FedCM。

当 IdP 的断开连接端点返回响应时，RP 和 IdP 在浏览器中会断开连接，并且 promise 得到解析。已断开连接帐号的 ID 在来自断开连接端点的响应中指定。

从跨源 iframe 中调用 FedCM

如果父框架允许，您可以使用 identity-credentials-get 权限政策在跨源 iframe 中调用 FedCM。为此，请将 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")

您可以参阅使用权限政策控制浏览器功能，详细了解权限政策的运作方式。