可发现凭据深入探讨

Eiji Kitamura
Maud Nalpas

虽然 FIDO 凭据（如通行密钥）旨在取代密码，但它们中的大多数还可以让用户无需键入用户名。这使用户能够通过从他们为当前网站拥有的通行密钥列表中选择帐户来进行身份验证。

早期版本的安全密钥被设计为两步身份验证方法，并且需要潜在凭据的 ID，因此需要输入用户名。安全密钥无需知道 ID 即可找到的凭据称为可发现凭据。今天创建的大多数 FIDO 凭据都是可发现凭据；特别是存储在密码管理器中或现代安全密钥上的通行密钥。

为确保您的凭据创建为通行密钥（可发现凭据），请在创建凭据时指定 residentKey 和 requireResidentKey。

依赖方 (RP) 可以通过在通行密钥身份验证期间省略 allowCredentials 来使用可发现凭据。在这些情况下，浏览器或系统会向用户显示可用通行密钥的列表，该列表由创建时设置的 user.name 属性标识。如果用户选择一个，则 user.id 值将包含在生成的签名中。然后，服务器可以使用该值或返回的凭据 ID 来查找帐户，而不是键入的用户名。

帐户选择器 UI（如前面讨论的那些）永远不会显示不可发现的凭据。

requireResidentKey 和 residentKey

要创建通行密钥，请在 navigator.credentials.create() 上指定 authenticatorSelection.residentKey 和 authenticatorSelection.requireResidentKey，并使用以下指示的值。

async function register () {
  // ...

  const publicKeyCredentialCreationOptions = {
    // ...
    authenticatorSelection: {
      authenticatorAttachment: 'platform',
      residentKey: 'required',
      requireResidentKey: true,
    }
  };

  const credential = await navigator.credentials.create({
    publicKey: publicKeyCredentialCreationOptions
  });

  // This does not run until the user selects a passkey.
  const credential = {};
  credential.id = cred.id;
  credential.rawId = cred.id; // Pass a Base64URL encoded ID string.
  credential.type = cred.type;

  // ...
}

residentKey:

  • 'required'：必须创建可发现凭据。如果无法创建，则返回 NotSupportedError。
  • 'preferred'：RP 首选创建可发现凭据，但也接受不可发现的凭据。
  • 'discouraged'：RP 首选创建不可发现的凭据，但也接受可发现的凭据。

requireResidentKey:

  • 此属性为了向后兼容 WebAuthn Level 1（规范的旧版本）而保留。如果 residentKey 为 'required'，则将其设置为 true，否则设置为 false。

allowCredentials

RP 可以使用 navigator.credentials.get() 上的 allowCredentials 来控制通行密钥身份验证体验。通行密钥身份验证体验通常有三种类型

借助可发现凭据，RP 可以显示模态帐户选择器，供用户选择要登录的帐户，然后进行用户验证。这适用于由专用于通行密钥身份验证的按钮发起的通行密钥身份验证流程。

要实现这种用户体验，请在 navigator.credentials.get() 中省略 allowCredentials 参数或向其传递空数组。

async function authenticate() {
  // ...

  const publicKeyCredentialRequestOptions = {
    // Server generated challenge:
    challenge: ****,
    // The same RP ID as used during registration:
    rpId: 'example.com',
    // You can omit `allowCredentials` as well:
    allowCredentials: []
  };

  const credential = await navigator.credentials.get({
    publicKey: publicKeyCredentialRequestOptions,
    signal: abortController.signal
  });

  // This does not run until the user selects a passkey.
  const credential = {};
  credential.id = cred.id;
  credential.rawId = cred.id; // Pass a Base64URL encoded ID string.
  credential.type = cred.type;
  
  // ...
}

显示通行密钥表单自动填充

如果大多数用户都使用通行密钥并在本地设备上可用，则上述模态帐户选择器效果良好。对于没有本地通行密钥的用户，模态对话框仍然会出现，并会为用户提供从另一台设备出示通行密钥的选项。在将用户过渡到通行密钥的过程中，您可能希望避免为尚未设置通行密钥的用户显示该 UI。

相反，通行密钥的选择可以折叠到传统登录表单字段的自动填充提示中，与保存的用户名和密码一起显示。这样，拥有通行密钥的用户可以通过选择他们的通行密钥来“填充”登录表单，拥有保存的用户名/密码对的用户可以选择这些，而两者都没有的用户仍然可以键入他们的用户名和密码。

当 RP 正在进行密码和通行密钥混合使用的迁移时，这种用户体验是理想的。

要实现这种用户体验，除了向 allowCredentials 属性传递空数组或省略该参数之外，还要在 navigator.credentials.get() 上指定 mediation: 'conditional'，并使用 autocomplete="username webauthn" 注释 HTML username 输入字段，或使用 autocomplete="password webauthn" 注释 password 输入字段。

对 navigator.credentials.get() 的调用不会导致显示任何 UI，但如果用户聚焦注释的输入字段，则任何可用的通行密钥都将包含在自动填充选项中。如果用户选择一个，他们将完成常规的设备解锁验证，然后 .get() 返回的 Promise 才会使用结果解析。如果用户未选择通行密钥，则 Promise 永远不会解析。

async function authenticate() {
  // ...

  const publicKeyCredentialRequestOptions = {
    // Server generated challenge:
    challenge: ****,
    // The same RP ID as used during registration:
    rpId: 'example.com',
    // You can omit `allowCredentials` as well:
    allowCredentials: []
  };

  const cred = await navigator.credentials.get({
    publicKey: publicKeyCredentialRequestOptions,
    signal: abortController.signal,
    // Specify 'conditional' to activate conditional UI
    mediation: 'conditional'
  });

  // This does not run until the user selects a passkey.
  const credential = {};
  credential.id = cred.id;
  credential.rawId = cred.id; // Pass a Base64URL encoded ID string.
  credential.type = cred.type;
  
  // ...
}

<input type="text" name="username" autocomplete="username webauthn" ...>

您可以在 通过表单自动填充使用通行密钥登录 以及 在 Web 应用中通过表单自动填充实现通行密钥 代码实验室中了解如何构建这种用户体验。

重新身份验证

在某些情况下，例如在将通行密钥用于重新身份验证时，用户的标识符已为人所知。在这种情况下，我们希望在浏览器或操作系统不显示任何形式的帐户选择器的情况下使用通行密钥。这可以通过在 allowCredentials 参数中传递凭据 ID 列表来实现。

在这种情况下，如果任何命名的凭据在本地可用，系统会立即提示用户解锁设备。如果不可用，系统会提示用户出示持有有效凭据的另一台设备（手机或安全密钥）。

要实现这种用户体验，请为登录用户提供凭据 ID 列表。RP 应该能够查询它们，因为用户已经是已知的。在 navigator.credentials.get() 的 allowCredentials 属性中提供凭据 ID 作为 PublicKeyCredentialDescriptor 对象。

async function authenticate() {
  // ...

  const publicKeyCredentialRequestOptions = {
    // Server generated challenge:
    challenge: ****,
    // The same RP ID as used during registration:
    rpId: 'example.com',
    // Provide a list of PublicKeyCredentialDescriptors:
    allowCredentials: [{
      id: ****,
      type: 'public-key',
      transports: [
        'internal',
        'hybrid'
      ]
    }, {
      id: ****,
      type: 'public-key',
      transports: [
        'internal',
        'hybrid'
      ]
    }, ...]
  };

  const credential = await navigator.credentials.get({
    publicKey: publicKeyCredentialRequestOptions,
    signal: abortController.signal
  });

  // This does not run until the user selects a passkey.
  const credential = {};
  credential.id = cred.id;
  credential.rawId = cred.id; // Pass a Base64URL encoded ID string.
  credential.type = cred.type;
  
  // ...
}

PublicKeyCredentialDescriptor 对象由以下各项组成

  • id：RP 在通行密钥注册时获得的公钥凭据的 ID。
  • type：此字段通常为 'public-key'。
  • transports：设备（持有此凭据）支持的传输方式的提示，浏览器使用此提示来优化提示用户出示外部设备的 UI。如果提供此列表，则该列表应包含在每次凭据注册期间调用 getTransports() 的结果。

摘要

可发现凭据通过允许用户跳过输入用户名，使通行密钥登录体验更加用户友好。通过结合使用 residentKey、requireResidentKey 和 allowCredentials，RP 可以实现以下登录体验

  • 显示模态帐户选择器。
  • 显示通行密钥表单自动填充。
  • 重新身份验证。

明智地使用可发现凭据。通过这样做，您可以设计出复杂但用户会觉得无缝且更愿意参与的通行密钥登录体验。