服务器端通行密钥身份验证

概览

下面简要概述了通行密钥身份验证涉及的关键步骤:

通行密钥身份验证流程

  • 定义使用通行密钥进行身份验证所需的质询码和其他选项。将这些信息发送到客户端,以便您将其传递给通行密钥身份验证调用(在 Web 上为 navigator.credentials.get)。用户确认通行密钥身份验证后,通行密钥身份验证调用会得到解析并返回凭据 (PublicKeyCredential)。该凭据包含身份验证断言。
  • 验证身份验证断言。
  • 如果身份验证断言有效,则对用户进行身份验证。

以下各部分将深入探讨每个步骤的具体细节。

创建挑战

在实践中,质询是一个随机字节数组,表示为 ArrayBuffer 对象。

// Example challenge, base64URL-encoded
weMLPOSx1VfSnMV6uPwDKbjGdKRMaUDGxeDEUTT5VN8

为确保挑战赛达到预期目的,您必须:

  1. 确保同一质询绝不使用多次。在每次尝试登录时生成新的质询。在每次登录尝试(无论成功还是失败)后,都应舍弃质询。在一定时长后,也应舍弃该质询。切勿在同一响应中接受同一质询多次。
  2. 确保质询具有加密安全性。质询应几乎不可能被猜到。如需在服务器端创建加密安全的质询,最好依赖您信任的 FIDO 服务器端库。如果您选择自行创建质询,请使用技术栈中内置的加密功能,或寻找专为加密用例设计的库。例如,Node.js 中的 iso-crypto 或 Python 中的 secrets。根据规范,质询必须至少为 16 字节长,才能被视为安全。

创建验证问题后,请将其保存在用户的会话中,以便稍后进行验证。

创建凭证请求选项

以 publicKeyCredentialRequestOptions 对象的形式创建凭据请求选项。

为此,请依赖 FIDO 服务器端库。它通常会提供一个实用函数,可为您创建这些选项。例如,SimpleWebAuthn 提供了 generateAuthenticationOptions。

publicKeyCredentialRequestOptions 应包含通行密钥身份验证所需的所有信息。将此信息传递给 FIDO 服务器端库中负责创建 publicKeyCredentialRequestOptions 对象的函数。

publicKeyCredentialRequestOptions 的某些字段可以是常量。其他参数应在服务器上动态定义:

  • rpId:您希望凭据与哪个 RP ID 相关联,例如 example.com。只有当您在此处提供的 RP ID 与凭证关联的 RP ID 匹配时,身份验证才会成功。如需填充 RP ID,请使用与您在凭据注册期间在 publicKeyCredentialCreationOptions 中设置的 RP ID 相同的值。
  • challenge:通行密钥提供程序将签名的一段数据,用于证明用户在发出身份验证请求时持有通行密钥。查看创建挑战中的详细信息。
  • allowCredentials:此身份验证可接受的凭据数组。传递空数组,让用户从浏览器显示的列表中选择可用的通行密钥。如需了解详情,请参阅从 RP 服务器提取质询和可检测到的凭据深入探究。
  • userVerification:指示是“必须”、“首选”还是“不建议”使用设备屏幕锁定功能进行用户验证。查看从 RP 服务器提取 challenge。
  • timeout:用户完成身份验证所需的时间(以毫秒为单位)。它应该足够长,并且短于 challenge 的生命周期。建议的默认值为 5 分钟,但您可以将其增加到最多 10 分钟,这仍在建议的范围内。如果您预计用户会使用混合工作流(通常需要更长时间),则设置较长的超时时间是合理的。如果操作超时,系统会抛出 NotAllowedError。

创建 publicKeyCredentialRequestOptions 后,将其发送给客户端。

服务器发送的 publicKeyCredentialCreationOptions
服务器发送的选项。challenge 解码在客户端进行。

示例代码:创建凭据请求选项

我们在示例中使用的是 SimpleWebAuthn 库。在这里,我们将凭证请求选项的创建工作交给其 generateAuthenticationOptions 函数。

import {
  generateAuthenticationOptions,
} from '@simplewebauthn/server';

router.post('/signinRequest', csrfCheck, async (req, res) => {

  // Ensure you nest calls in try/catch blocks.
  // If something fails, throw an error with a descriptive error message.
  // Return that message with an appropriate error code to the client.
  try {
    // Use the generateAuthenticationOptions function from SimpleWebAuthn
    const options = await generateAuthenticationOptions({
      rpID: process.env.HOSTNAME,
      allowCredentials: [],
    });
    // Save the challenge in the user session
    req.session.challenge = options.challenge;

    return res.json(options);
  } catch (e) {
    console.error(e);
    return res.status(400).json({ error: e.message });
  }
});

验证用户并让其登录

当 navigator.credentials.get 在客户端上成功解析时,它会返回一个 PublicKeyCredential 对象。

服务器发送的 PublicKeyCredential 对象
navigator.credentials.get 会返回 PublicKeyCredential。

response 是一个 AuthenticatorAssertionResponse。它表示通行密钥提供方对客户端指令的响应,该指令旨在创建尝试使用通行密钥在 RP 上进行身份验证所需的内容。其中包含:

  • response.authenticatorData和response.clientDataJSON,例如在通行密钥注册步骤中。
  • response.signature,其中包含这些值的签名。

将 PublicKeyCredential 对象发送给服务器。

在服务器上,执行以下操作:

数据库架构
建议的数据库架构。如需详细了解此设计,请参阅服务器端通行密钥注册。
  • 收集验证断言和验证用户身份所需的信息:
    • 获取您在生成身份验证选项时存储在会话中的预期 challenge。
    • 获取预期的来源和 RP ID。
    • 在数据库中查找用户。如果使用可检测到的凭据,您将无法知道是哪个用户在发出身份验证请求。如需了解详情,您有两种选择:
      • 方法 1:使用 PublicKeyCredential 对象中的 response.userHandle。在用户表中,查找与 userHandle 匹配的 passkey_user_id。
      • 选项 2:使用 PublicKeyCredential 对象中存在的凭据 id。在公钥凭据表中,查找与 PublicKeyCredential 对象中的凭据 id 匹配的凭据 id。然后,使用 Users 表的外键 passkey_user_id 查找对应的用户。
    • 在数据库中查找与您收到的身份验证断言匹配的公钥凭据信息。为此,请在公钥凭据表中查找与 PublicKeyCredential 对象中存在的凭据 id 匹配的凭据 id。
  • 验证身份验证断言。将此验证步骤交给 FIDO 服务器端库,该库通常会为此提供一个实用函数。例如,SimpleWebAuthn 提供了 verifyAuthenticationResponse。如需了解其背后的运作机制,请参阅附录:验证身份验证响应。

  • 无论验证是否成功,都请删除质询,以防止重放攻击。

  • 让用户登录。如果验证成功,请更新会话信息,将用户标记为已登录。您可能还需要向客户端返回一个 user 对象,以便前端可以使用与新登录的用户关联的信息。

示例代码:验证并让用户登录

我们在示例中使用的是 SimpleWebAuthn 库。在这里,我们将身份验证响应的验证工作交给其 verifyAuthenticationResponse 函数。

import {
  verifyAuthenticationResponse,
} from '@simplewebauthn/server';
import { isoBase64URL } from '@simplewebauthn/server/helpers';

router.post('/signinResponse', csrfCheck, async (req, res) => {
  const response = req.body;
  const expectedChallenge = req.session.challenge;
  const expectedOrigin = getOrigin(req.get('User-Agent'));
  const expectedRPID = process.env.HOSTNAME;

  // Ensure you nest verification function calls in try/catch blocks.
  // If something fails, throw an error with a descriptive error message.
  // Return that message with an appropriate error code to the client.
  try {
    // Find the credential stored to the database by the credential ID
    const cred = Credentials.findById(response.id);
    if (!cred) {
      throw new Error('Credential not found.');
    }
    // Find the user - Here alternatively we could look up the user directly
    // in the Users table via userHandle
    const user = Users.findByPasskeyUserId(cred.passkey_user_id);
    if (!user) {
      throw new Error('User not found.');
    }
    // Prepare credential information for verification
    const credential = {
      id: cred.id,
      publicKey: isoBase64URL.toBuffer(cred.publicKey),
      transports: cred.transports,
    };

    // Verify the credential
    const { verified, authenticationInfo } = await verifyAuthenticationResponse({
      response,
      expectedChallenge,
      expectedOrigin,
      expectedRPID,
      credential,
      requireUserVerification: false,
    });

    if (!verified) {
      throw new Error('User verification failed.');
    }

    // Kill the challenge for this session.
    delete req.session.challenge;

    req.session.username = user.username;
    req.session['signed-in'] = 'yes';

    return res.json(user);
  } catch (e) {
    delete req.session.challenge;

    console.error(e);
    return res.status(400).json({ error: e.message });
  }
});

附录:验证身份验证响应

验证身份验证响应包括以下检查:

  • 确保 RP ID 与您的网站匹配。
  • 确保请求的来源与您网站的登录来源一致。对于 Android 应用,请参阅验证来源。
  • 检查设备是否能够提供您给它的质询。
  • 验证用户在身份验证期间是否遵循了您作为 RP 规定的要求。如果您要求进行用户验证,请确保 authenticatorData 中的 uv(用户已验证)标志为 true。检查 authenticatorData 中的 up(用户在场)标志是否为 true,因为通行密钥始终需要用户在场。
  • 验证签名。如需验证签名,您需要:
    • 签名,即已签名的质询:response.signature
    • 用于验证签名的公钥。
    • 原始签名数据。这是要验证其签名的数据。
    • 用于创建签名的加密算法。

如需详细了解这些步骤,请查看 SimpleWebAuthn 的 verifyAuthenticationResponse 源代码,或深入了解规范中的完整验证列表。