Enable QR code generation for TOTP authenticator apps in ASP.NET Core

ASP.NET Core includes support for authenticator applications for user authentication. Two-factor authentication (2FA) authenticator apps use a Time-based One-time Password Algorithm (TOTP), the industry-recommended approach for 2FA. (TOTP-based 2FA is preferred over SMS 2FA.) Users typically install the authenticator app on a smartphone. The app provides a 6 to 8 digit code that the user enters after they confirm their username and password.

Two-factor authentication doesn't happen by using an external authentication provider, such as Google or Facebook. External sign ins are protected by whatever mechanism the external authentication provider supports. For example, the Microsoft authentication provider requires a hardware key or another 2FA approach. When the default templates require 2FA for both the web app and the external authentication provider, users need to satisfy two 2FA approaches. Requiring two 2FA approaches deviates from established security practices, which typically rely on a single, strong 2FA method for authentication.

If you're working with Blazor in ASP.NET Core 8.0 or later, you can find similar guidance in the following articles:

• Enable QR code generation for TOTP authenticator apps in an ASP.NET Core Blazor Web App
• Enable QR code generation for TOTP authenticator apps in ASP.NET Core Blazor WebAssembly with ASP.NET Core Identity

Add QR codes to the 2FA configuration page

The following instructions use the qrcode.js file from the https://davidshimjs.github.io/qrcodejs/ repo.

1. Download the 'qrcode.js' JavaScript library to the wwwroot\lib folder in your project.

2. Follow the instructions in Scaffold Identity to generate the /Areas/Identity/Pages/Account/Manage/EnableAuthenticator.cshtml file.

3. In the /Areas/Identity/Pages/Account/Manage/EnableAuthenticator.cshtml file, locate the Scripts section at the end of the file:

   @section Scripts {
      <partial name="_ValidationScriptsPartial" />
   }
   

4. Create a new JavaScript file named qr.js in the wwwroot/js folder, and add the following code that generates the QR code:

   window.addEventListener("load", () => {
   const uri = document.getElementById("qrCodeData").getAttribute('data-url');
   new QRCode(document.getElementById("qrCode"),
      {
         text: uri,
         width: 150,
         height: 150
      });
   });
   

5. Update the Scripts section to add a reference to the qrcode.js library you previously downloaded.

6. Add the qr.js file with the call that generates the QR code:

   @section Scripts {
      <partial name="_ValidationScriptsPartial" />
      <script type="text/javascript" src="~/lib/qrcode.js"></script>
      <script type="text/javascript" src="~/js/qr.js"></script>
   }
   

7. Delete the paragraph that links you to these instructions.

8. Run your app. Confirm you can scan the QR code and validate the code the authenticator provides.

Change the site name in the QR code

The site name in the QR code comes from the project name you select when you create your project. You can change it by looking for the GenerateQrCodeUri(string email, string unformattedKey) method in the /Areas/Identity/Pages/Account/Manage/EnableAuthenticator.cshtml.cs file.

Here's the default code from the template:

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

The second parameter in the call to string.Format is your site name, which is obtained from your solution name. You can change it to any value, but it must always be URL encoded.

Use a different QR code library

You can replace the QR code library with your preferred library. The HTML contains a qrCode element into which you can place a QR code by whatever mechanism your library provides.

You can find the correctly formatted URL for the QR code in the following locations:

• AuthenticatorUri property of the model
• data-url property in the qrCodeData element

Check TOTP client and server times

TOTP (Time-based One-Time Password) authentication depends on both the server and authenticator device having an accurate time. Tokens only last for 30 seconds. If TOTP 2FA sign-in fails, confirm the server time is accurate, and preferably synchronized to an accurate NTP service.

Related content

• Enable QR code generation for TOTP authenticator apps in an ASP.NET Core Blazor Web App
• Enable QR code generation for TOTP authenticator apps in ASP.NET Core Blazor WebAssembly with ASP.NET Core Identity