当前位置：首页 > news >正文

从零开始：用Speakeasy为你的Node.js应用添加双因素认证

news 2026/5/28 13:22:22

从零开始：用Speakeasy为你的Node.js应用添加双因素认证

【免费下载链接】speakeasy**NOT MAINTAINED** Two-factor authentication for Node.js. One-time passcode generator (HOTP/TOTP) with support for Google Authenticator.项目地址: https://gitcode.com/gh_mirrors/sp/speakeasy

在当今数字化时代，账户安全面临着越来越多的威胁，单靠密码已经难以保障账户的绝对安全。双因素认证（2FA）作为一种强大的安全措施，能够显著提升账户的安全性。Speakeasy作为一款专为Node.js设计的双因素认证库，支持HOTP和TOTP算法，并且兼容Google Authenticator等主流认证应用，是为你的Node.js应用快速集成双因素认证的理想选择。

为什么选择Speakeasy？

Speakeasy是一个功能强大的一次性密码生成器，非常适合用于双因素认证场景。它全面支持Google Authenticator及其他双因素认证设备，遵循OATH（开放认证倡议）标准化的一次性密码生成算法，包括RFC 4226定义的基于HMAC的一次性密码（HOTP）算法和RFC 6238定义的基于时间的一次性密码（TOTP）算法。

该库经过充分测试，具备对自定义令牌长度、认证窗口、SHA256和SHA512等哈希算法的强大支持，还包含密钥生成器等实用工具，能够满足各种双因素认证需求。

快速安装Speakeasy

要在你的Node.js项目中使用Speakeasy，只需通过npm进行安装：

npm install --save speakeasy

实现双因素认证的三大步骤

假设你有一个用户想要启用双因素认证，并且打算使用Google Authenticator、Duo Security、Authy等应用进行双因素认证，整个过程分为以下三个步骤：

步骤一：生成密钥

使用Speakeasy的密钥生成器来获取密钥：

var secret = speakeasy.generateSecret(); // 返回一个包含secret.ascii、secret.hex和secret.base32的对象 // 还会返回secret.otpauth_url，稍后会用到

这将生成一个长度为32的密钥，作为用户的密钥。此时，我们需要先验证用户从该密钥获取的令牌是否有效，然后再将其设置为用户的密钥。因此，需要将密钥的某种编码形式（推荐使用secret.base32）暂时存储起来，以便后续进行令牌验证。

// 示例：将密钥存储在某个地方（具体实现方式因项目而异） user.two_factor_temp_secret = secret.base32;

步骤二：显示二维码

接下来，需要向用户显示一个二维码，以便他们将密钥扫描到认证应用中。Google Authenticator等类似应用可以识别包含otpauth://协议URL的二维码，而secret.otpauth_url可以直接提供这个URL。

你可以使用二维码模块生成存储secret.otpauth_url数据的二维码，然后将其显示给用户。以下是一种简单的方法，生成可放入网页<img>标签的PNG数据URL：

// 使用qrcode包 // npm install --save qrcode var QRCode = require('qrcode'); // 获取认证器URL的数据URL QRCode.toDataURL(secret.otpauth_url, function(err, data_url) { console.log(data_url); // 在网页的<img>标签中显示此数据URL // 示例： write('<img src="' + data_url + '">'); });

请用户将此二维码扫描到他们的认证应用中。

步骤三：验证令牌

最后，需要确保服务器端的令牌与客户端的令牌匹配。最佳实践是在完全为用户启用双因素认证之前进行令牌检查。以下代码适用于首次及后续的令牌检查。

用户扫描二维码后，要求他们输入在应用中看到的令牌，然后根据密钥进行验证：

// 假设用户输入的令牌是132890 var userToken = '132890'; // 假设我们像上面那样将用户的临时密钥存储在user对象中： // （具体实现方式因项目而异） var base32secret = user.two_factor_temp_secret;

// 使用verify()方法检查令牌与密钥是否匹配 var verified = speakeasy.totp.verify({ secret: base32secret, encoding: 'base32', token: userToken });

如果verified为true，则令牌验证成功；否则验证失败。

如果验证成功，现在可以将密钥保存到用户的账户中，并在需要使用双因素认证（如登录时）使用上述相同的过程对用户进行认证。

// 示例：保存用户的令牌（具体实现方式因项目而异） user.two_factor_secret = user.two_factor_temp_secret; user.two_factor_enabled = true

至此，你已成功实现双因素认证！

Speakeasy的一般用法

生成密钥

// 生成密钥 var secret = speakeasy.generateSecret({length: 20}); // 通过secret.ascii、secret.hex或secret.base32访问密钥

获取当前时间的基于时间的令牌

// 基于base-32密钥生成基于时间的令牌 // 如果将`totp`替换为`hotp`（即speakeasy.hotp()）并在选项中提供`counter`，也可以使用HOTP（基于计数器的令牌） var token = speakeasy.totp({ secret: secret.base32, encoding: 'base32' }); // 返回当前时间的密钥令牌 // 将其与用户输入进行比较

验证令牌

// 验证给定的令牌 var tokenValidates = speakeasy.totp.verify({ secret: secret.base32, encoding: 'base32', token: '123456', window: 6 }); // 如果令牌匹配则返回true

验证令牌并计算时间差

TOTP每隔step时间步长（以秒为单位）递增一次。默认情况下，时间步长为30秒。你可以使用step选项更改时间步长，单位为秒。

// 验证给定的令牌是否在服务器时间步长的3个时间步长（±2分钟）内 var tokenDelta = speakeasy.totp.verifyDelta({ secret: secret.base32, encoding: 'base32', token: '123456', window: 2, step: 60 }); // 返回{delta: 0}，其中delta是给定令牌与当前时间步长的时间步差