CredentialsContainer: get() 方法

options 可选

包含请求选项的对象。它可以包含以下属性

mediation 可选

一个字符串，指示用户是否需要在每次访问客户端应用程序时登录。该值可以是以下之一

• "conditional"：在非模态对话框中向用户展示发现的凭据，以及请求凭据的来源的指示。在实践中，这意味着自动填充可用凭据；有关如何使用此功能的更多详细信息，请参见 使用密码键通过表单自动填充登录；PublicKeyCredential.isConditionalMediationAvailable() 也提供了一些有用的信息。
• "optional"：如果可以在没有用户参与的情况下将凭据传递给给定操作，则将传递凭据，从而无需用户参与即可自动重新认证。如果需要用户参与，则用户代理将要求用户进行身份验证。此值适用于您有理由相信用户不会对看到登录对话框感到意外或困惑的情况 - 例如，在不会自动登录用户的网站上，当用户刚刚点击了“登录/注册”按钮时。
• "required"：始终要求用户进行身份验证，即使将 prevent silent access（见 CredentialsContainer.preventSilentAccess()）设置为 false。此值适用于您希望强制用户身份验证的情况 - 例如，如果希望用户在执行敏感操作时（如确认信用卡付款）或切换用户时重新认证。
• "silent"：不会要求用户进行身份验证。用户代理将自动重新认证用户并将其登录，如果可能的话。如果需要同意，则 Promise 将实现 null。此值适用于您希望在访问 Web 应用程序时自动登录用户（如果可能），但如果不是，则不希望向他们展示令人困惑的登录对话框的情况。相反，您希望等待他们明确点击“登录/注册”按钮。

默认值为 "optional"。

注意：在 联合身份验证 (FedCM API) 请求的情况下，mediation 值为 optional 或 silent 可能会导致尝试自动重新认证。是否发生了这种情况将通过发送到 IdP 的 id_assertion_endpoint 中的 is_auto_selected 参数和发送到信赖方 (RP) 的 IdentityCredential.isAutoSelected 属性传递给身份提供者 (IdP)。这对于性能评估、安全要求（IdP 可能希望拒绝自动重新认证请求并始终要求用户参与）以及一般 UX（IdP 或 RP 可能希望为自动和非自动登录体验呈现不同的 UX）很有用。

signal 可选

一个 AbortSignal 对象实例，它允许中止正在进行的 get() 操作。中止的操作可能会正常完成（通常是在收到中止请求后操作已完成时）或拒绝并显示“AbortError”DOMException。

password 可选

此选项要求浏览器检索存储的 密码 作为 PasswordCredential 对象。它是一个布尔值。

identity 可选

此选项要求浏览器使用 联合凭据管理 API 检索 联合身份凭据 作为 IdentityCredential 对象。

此选项的值是一个 IdentityCredentialRequestOptions 对象，其中包含网站要使用的特定身份提供者的详细信息。

federated 可选

此选项要求浏览器检索 联合身份凭据 作为 FederatedCredential 对象。此接口现已弃用，开发人员应该优先使用 identity 选项（如果可用）。

此选项的值是一个具有以下属性的对象

protocols

一个字符串数组，表示所请求凭据的联合身份提供者的协议（例如，"openidconnect"）。

providers

一个字符串数组，表示凭据的联合身份提供者（例如 "https://www.facebook.com" 或 "https://accounts.google.com"）。

otp 可选

此选项要求浏览器检索 一次性密码 (OTP) 作为 OTPCredential 对象。

此选项的值是一个字符串数组，该数组只能包含字符串值 "sms"。

publicKey 可选

此选项要求浏览器检索 使用 Web 身份验证 API 签名的断言 作为 PublicKeyCredential。

此选项的值是一个 PublicKeyCredentialRequestOptions 对象。

一个Promise，它解析为以下 Credential 子类之一

• PasswordCredential
• IdentityCredential
• FederatedCredential
• OTPCredential
• PublicKeyCredential

如果无法明确地获得单个凭据，则 Promise 将解析为 null。

AbortError DOMException

请求被调用此方法的 AbortController 的 abort() 方法中止。

IdentityCredentialError DOMException

在请求 IdentityCredential 时，对 ID 断言端点 的请求无法验证身份验证，并拒绝，并返回包含原因信息的错误响应。

NetworkError DOMException

在请求 IdentityCredential 时，身份提供者 (IdP) 在 60 秒内没有响应，提供的凭据无效/未找到，或者浏览器对 IdP 的登录状态设置为 "logged-out"（有关 FedCM 登录状态的更多信息，请参见 使用登录状态 API 更新登录状态）。在后一种情况下，拒绝可能会有所延迟，以避免将 IdP 登录状态泄露给 RP。

NotAllowedError DOMException

在以下情况之一中抛出

• 以下 权限策略 之一阻止了使用此 API
  • identity-credentials-get
  • publickey-credentials-get
  • otp-credentials
• 调用来源是 不透明来源。

SecurityError DOMException

调用域不是有效的域。

依赖方可以通过使用 `identity` 选项调用 `get()` 来向身份提供者 (IdP) 发出请求，使用身份联合让用户登录依赖方。一个典型的请求看起来像这样

async function signIn() {
  const identityCredential = await navigator.credentials.get({
    identity: {
      providers: [
        {
          configURL: "https://accounts.idp.example/config.json",
          clientId: "********",
          nonce: "******",
        },
      ],
    },
  });
}

查看 联合凭据管理 (FedCM) API 以获取有关此工作原理的更多详细信息。此调用将启动 FedCM 登录流程 中描述的登录流程。

类似的调用，包括 `context` 和 `loginHint` 扩展，看起来像这样

async function signIn() {
  const identityCredential = await navigator.credentials.get({
    identity: {
      context: "signup",
      providers: [
        {
          configURL: "https://accounts.idp.example/config.json",
          clientId: "********",
          nonce: "******",
          loginHint: "[email protected]",
        },
      ],
    },
  });
}

如果 IdP 无法验证对 ID 断言端点 的请求，它将拒绝从 `CredentialsContainer.get()` 返回的 Promise。

async function signIn() {
  try {
    const identityCredential = await navigator.credentials.get({
      identity: {
        providers: [
          {
            configURL: "https://accounts.idp.example/config.json",
            clientId: "********",
            nonce: "******",
          },
        ],
      },
    });
  } catch (e) {
    // Handle the error in some way, for example provide information
    // to help the user succeed in a future sign-in attempt
    console.error(e);
  }
}

以下代码片段显示了使用 WebAuthn `publicKey` 选项的典型 `get()` 调用

const publicKey = {
  challenge: new Uint8Array([139, 66, 181, 87, 7, 203, ...]),
  rpId: "acme.com",
  allowCredentials: [{
    type: "public-key",
    id: new Uint8Array([64, 66, 25, 78, 168, 226, 174, ...])
  }],
  userVerification: "required",
}

navigator.credentials.get({ publicKey })

一个成功的 `get()` 调用将返回一个 Promise，该 Promise 解析为一个 PublicKeyCredential 对象实例，代表之前通过 WebAuthn create() 创建的公钥凭据，现在已用于对用户进行身份验证。其 PublicKeyCredential.response 属性包含一个 AuthenticatorAssertionResponse 对象，提供对包括鉴证器数据、签名和用户句柄在内的几个有用信息片的访问。

navigator.credentials.get({ publicKey }).then((publicKeyCredential) => {
  const response = publicKeyCredential.response;

  // Access authenticator data ArrayBuffer
  const authenticatorData = response.authenticatorData;

  // Access client JSON
  const clientJSON = response.clientDataJSON;

  // Access signature ArrayBuffer
  const signature = response.signature;

  // Access userHandle ArrayBuffer
  const userHandle = response.userHandle;
});

其中一些数据需要存储在服务器上——例如 `signature` 用于证明鉴证器拥有用于创建凭据的真实私钥，以及 `userHandle` 用于将用户与凭据、登录尝试和其他数据关联起来。

有关整个流程如何工作的更多信息，请参阅 对用户进行身份验证。

下面的代码在收到短信消息时会触发浏览器的权限流程。如果授予权限，则 Promise 将解析为一个 `OTPCredential` 对象。然后将包含的 `code` 值设置为 <input> 表单元素的值，然后提交。

navigator.credentials
  .get({
    otp: { transport: ["sms"] },
    signal: ac.signal,
  })
  .then((otp) => {
    input.value = otp.code;
    if (form) form.submit();
  })
  .catch((err) => {
    console.error(err);
  });