启用在 ASP.NET Core TOTP 身份验证器应用的 QR 代码生成Enable QR Code generation for TOTP authenticator apps in ASP.NET Core

QR 代码需要 ASP.NET Core 2.0 或更高版本。QR Codes requires ASP.NET Core 2.0 or later.

ASP.NET Core 附带的单个身份验证的身份验证器应用程序的支持。ASP.NET Core ships with support for authenticator applications for individual authentication. 两个身份验证 (2FA) 身份验证器应用程序,使用基于时间的一次性密码算法 (TOTP),是推荐的方法用于 2FA 的行业。Two factor authentication (2FA) authenticator apps, using a Time-based One-time Password Algorithm (TOTP), are the industry recommended approach for 2FA. 2FA 使用 TOTP 优于 SMS 2FA。2FA using TOTP is preferred to SMS 2FA. 身份验证器应用程序提供了哪些用户必须输入其用户名和密码确认后一个 6 到 8 位代码。An authenticator app provides a 6 to 8 digit code which users must enter after confirming their username and password. 通常智能手机上安装验证器应用。Typically an authenticator app is installed on a smart phone.

ASP.NET Core web 应用程序模板支持身份验证器,但不提供对 QRCode 生成的支持。The ASP.NET Core web app templates support authenticators, but don't provide support for QRCode generation. QRCode 生成器简化 2FA 的安装程序。QRCode generators ease the setup of 2FA. 本文档将指导你完成添加QR 码生成到 2FA 配置页。This document will guide you through adding QR Code generation to the 2FA configuration page.

如使用外部身份验证提供程序,不会发生双因素身份验证GoogleFacebookTwo factor authentication does not happen using an external authentication provider, such as Google or Facebook. 受保护的外部登录名通过任何机制提供外部登录提供程序。External logins are protected by whatever mechanism the external login provider provides. 例如,请考虑Microsoft身份验证提供程序需要硬件密钥或另一种 2FA 方法。Consider, for example, the Microsoft authentication provider requires a hardware key or another 2FA approach. 如果默认模板强制实施"local"2FA 然后会要求用户以满足两个 2FA 方法,这是不常使用的方案。If the default templates enforced "local" 2FA then users would be required to satisfy two 2FA approaches, which is not a commonly used scenario.

将 QR 代码添加到 2FA 配置页Adding QR Codes to the 2FA configuration page

使用这些说明qrcode.jshttps://davidshimjs.github.io/qrcodejs/存储库。These instructions use qrcode.js from the https://davidshimjs.github.io/qrcodejs/ repo.

  • 按照中的说明基架标识生成 /Areas/Identity/Pages/Account/Manage/EnableAuthenticator.cshtmlFollow the instructions in Scaffold Identity to generate /Areas/Identity/Pages/Account/Manage/EnableAuthenticator.cshtml.
  • 在中 /Areas/Identity/Pages/Account/Manage/EnableAuthenticator.cshtml,找到Scripts文件的末尾部分:In /Areas/Identity/Pages/Account/Manage/EnableAuthenticator.cshtml, locate the Scripts section at the end of the file:
  • 在中Pages/Account/Manage/EnableAuthenticator.cshtml (Razor 页面) 或Views/Manage/EnableAuthenticator.cshtml (MVC) 中,找到Scripts文件的末尾部分:In Pages/Account/Manage/EnableAuthenticator.cshtml (Razor Pages) or Views/Manage/EnableAuthenticator.cshtml (MVC), locate the Scripts section at the end of the file:
@section Scripts {
    @await Html.PartialAsync("_ValidationScriptsPartial")
}
  • 更新Scripts部分,以添加对引用qrcodejs您添加的库和生成 QR 代码的调用。Update the Scripts section to add a reference to the qrcodejs library you added and a call to generate the QR Code. 其外观应按如下所示:It should look as follows:
@section Scripts {
    @await Html.PartialAsync("_ValidationScriptsPartial")

    <script type="text/javascript" src="~/lib/qrcode.js"></script>
    <script type="text/javascript">
        new QRCode(document.getElementById("qrCode"),
            {
                text: "@Html.Raw(Model.AuthenticatorUri)",
                width: 150,
                height: 150
            });
    </script>
}
  • 删除的段落,提供了指向这些说明。Delete the paragraph which links you to these instructions.

运行你的应用,并确保可以扫描 QR 代码并验证身份验证者证明的代码。Run your app and ensure that you can scan the QR code and validate the code the authenticator proves.

更改 QR 代码中的站点名称Change the site name in the QR Code

QR 代码中的站点名称是来自在最初创建你的项目时选择的项目名称。The site name in the QR Code is taken from the project name you choose when initially creating your project. 您可以通过查找对其进行更改GenerateQrCodeUri(string email, string unformattedKey)中的方法 /Areas/Identity/Pages/Account/Manage/EnableAuthenticator.cshtml.csYou can change it by looking for the GenerateQrCodeUri(string email, string unformattedKey) method in the /Areas/Identity/Pages/Account/Manage/EnableAuthenticator.cshtml.cs.

QR 代码中的站点名称是来自在最初创建你的项目时选择的项目名称。The site name in the QR Code is taken from the project name you choose when initially creating your project. 您可以通过查找对其进行更改GenerateQrCodeUri(string email, string unformattedKey)中的方法Pages/Account/Manage/EnableAuthenticator.cshtml.cs (Razor 页面) 文件或Controllers/ManageController.cs (MVC) 文件。You can change it by looking for the GenerateQrCodeUri(string email, string unformattedKey) method in the Pages/Account/Manage/EnableAuthenticator.cshtml.cs (Razor Pages) file or the Controllers/ManageController.cs (MVC) file.

模板中的默认代码如下所示:The default code from the template looks as follows:

private string GenerateQrCodeUri(string email, string unformattedKey)
{
    return string.Format(
        AuthenticatorUriFormat,
        _urlEncoder.Encode("Razor Pages"),
        _urlEncoder.Encode(email),
        unformattedKey);
}

对的调用中的第二个参数string.Format是你的站点名称,从你的解决方案名称。The second parameter in the call to string.Format is your site name, taken from your solution name. 可以更改为任何值,但它必须始终为 URL 编码。It can be changed to any value, but it must always be URL encoded.

使用不同的 QR 代码库Using a different QR Code library

QR 代码库可以替换你首选的库。You can replace the QR Code library with your preferred library. 包含 HTMLqrCode元素在其中可以通过任何机制将 QR 代码库提供。The HTML contains a qrCode element into which you can place a QR Code by whatever mechanism your library provides.

QR 码的格式正确 URL 现已推出:The correctly formatted URL for the QR Code is available in the:

  • AuthenticatorUri 模型的属性。AuthenticatorUri property of the model.
  • data-url 中的属性qrCodeData元素。data-url property in the qrCodeData element.

TOTP 客户端和服务器时间倾斜TOTP client and server time skew

TOTP (基于时间的一次性密码) 身份验证依赖于服务器和身份验证器的设备具有准确的时间。TOTP (Time-based One-Time Password) authentication depends on both the server and authenticator device having an accurate time. 令牌仅持续 30 秒。Tokens only last for 30 seconds. 如果 TOTP 2FA 登录名失败,则检查服务器时间是准确的并且最好是同步到准确的 NTP 服务。If TOTP 2FA logins are failing, check that the server time is accurate, and preferably synchronized to an accurate NTP service.