Implementing TOTP Two-Factor Authentication in .NET Web API

Introduction Two-factor authentication (2FA) adds an extra layer of security to your application by requiring users to provide a second form of verification during login. In this article, we'll walk through a practical implementation of time-based one-time password (TOTP) 2FA in ASP.NET Core, complete with QR code setup and OTP validation. Why 2FA Matters Before diving into the code, let's understand why 2FA is crucial: Mitigates password-related risks Adds defense against phishing attacks Complies with modern security standards Protects sensitive user data The Implementation Blueprint Our solution includes three core components: Traditional email/password login with 2FA check OTP verification endpoint QR code generation for authenticator apps 1. Get Authenticator QR Code for 2FA setup Get logged in user and create QR Code by generating a totp token. Encrypt the token with user email as encryption secret to bind the token with email. Send the encrypted token and QR to response. [HttpGet("GetAuthenticatorQrCode")] public async Task GetTwoFactorAuthenticatorQr() { var user = await GetLoggedInUserId(); var totpSecretToken = Base32Encoding.ToString(KeyGeneration.GenerateRandomKey(20)); string encodedIssuer = Uri.EscapeDataString(_applicationConfiguration.AuthenticatorIssuerName); string encodedEmail = Uri.EscapeDataString(user.Email); string otpAuthUri = $"otpauth://totp/{encodedIssuer}:{encodedEmail}?secret={totpSecretToken}&issuer={encodedIssuer}&algorithm=SHA1&digits=6&period=30"; using var qrGenerator = new QRCodeGenerator(); using var qrCodeData = qrGenerator.CreateQrCode(otpAuthUri, QRCodeGenerator.ECCLevel.Q); using var qrCode = new PngByteQRCode(qrCodeData); string base64QrCode = Convert.ToBase64String(qrCode.GetGraphic(20)); var qrBase64 = $"data:image/png;base64,{base64QrCode}"; var encryptedToken = EncryptionHelper.Encrypt(totpSecretToken, user.Email); return Ok(new NewAuthenticatorQrResponse { Base64QrCode = qrBase64, Secret = encryptedToken, }); } 2. Update User Authenticator Get encrypted token and OTP from user via DTO of request. Get logged in user and decrypt the token by user email. Validate if provided OTP is valid. If valid, set the encrypted token to user data for future verifications. [HttpPut("UpdateUserAuthenticator")] public async Task UpdateUserAuthenticator(AuthenticatorUpdateDto dto) { var user = await GetLoggedInUserId(); var totpSecret = EncryptionHelper.Decrypt(dto.Secret, user.Email); var isValidOtp = IsAuthenticatorOtpValid(totpSecret, dto.Otp); if (!isValidOtp) return Ok(false); user.AuthenticatorToken = dto.Secret; _unitOfWork.Users.Update(user); await _unitOfWork.SaveAsync(); return Ok(true); } 3. Login User API Check if user credentials are ok and create a temporary token with user id and send as response for next OTP verification step. [AllowAnonymous] [HttpPost("UserLogin")] public async Task UserLogin(LoginRequestDto dto) { #region User Validation // Validates user credentials #endregion var userSecret = EncryptionHelper.Encrypt(user.Id.ToString(), _cryptoConfiguration.SigningKey); var response = new AuthResponse() { UserOtpSecret = userSecret }; return Ok(response); } 4. User Login With OTP Check if user credentials are ok and create a temporary token with user id and send as response for next OTP verification step. [AllowAnonymous] [HttpPost("UserLoginWithOtp")] public async Task UserLoginWithOtp(LoginWithOtpDto dto) { #region DTO Validation // Validates DTO #endregion var userIdString = EncryptionHelper.Decrypt(dto.UserOtpSecret, _cryptoConfiguration.SigningKey); if (!long.TryParse(userIdString, out long userId)) return Ok(false); var user = await _unitOfWork.Login.GetUserById(userId); var totpSecret = EncryptionHelper.Decrypt(user.AuthenticatorToken, user.Email); var isValidOtp = IsAuthenticatorOtpValid(totpSecret, dto.Otp); if (!isValidOtp) return Ok(false); var (jwtToken, jwtExpiry) = GenerateJWTToken(user); var (refreshToken, refreshExpiry) = GenerateRefreshToken(); var token = new UserToken { JWTToken = jwtToken, JWTExpires = jwtExpiry, RefreshToken = refreshToken, RefreshExpires = refreshExpiry }; await _unitOfWork.Login.SaveUserToken(token); return Ok(token); } Is Authenticator OTP Valid Helper Methods Checks the provided OTP against a secret token and returns boolean response. Allowed two future windows to mitigate issues with server and client system clock slight mismatches. private static bool IsAuthenticatorOtpValid(string secret, string otp) { if (string.IsNullOrEmpty(secret) || string.IsNullOrEmpty(otp)) return false; var totp = new Totp(Base32En

Feb 16, 2025 - 09:23

Implementing TOTP Two-Factor Authentication in .NET Web API

Introduction

Two-factor authentication (2FA) adds an extra layer of security to your application by requiring users to provide a second form of verification during login. In this article, we'll walk through a practical implementation of time-based one-time password (TOTP) 2FA in ASP.NET Core, complete with QR code setup and OTP validation.

Why 2FA Matters

Before diving into the code, let's understand why 2FA is crucial:

Mitigates password-related risks
Adds defense against phishing attacks
Complies with modern security standards
Protects sensitive user data

The Implementation Blueprint

Our solution includes three core components:

Traditional email/password login with 2FA check
OTP verification endpoint
QR code generation for authenticator apps

1. Get Authenticator QR Code for 2FA setup

Get logged in user and create QR Code by generating a totp token. Encrypt the token with user email as encryption secret to bind the token with email. Send the encrypted token and QR to response.

[HttpGet("GetAuthenticatorQrCode")]
public async Task<IActionResult> GetTwoFactorAuthenticatorQr()
{
    var user = await GetLoggedInUserId();

    var totpSecretToken = Base32Encoding.ToString(KeyGeneration.GenerateRandomKey(20));
    string encodedIssuer = Uri.EscapeDataString(_applicationConfiguration.AuthenticatorIssuerName);
    string encodedEmail = Uri.EscapeDataString(user.Email);
    string otpAuthUri = $"otpauth://totp/{encodedIssuer}:{encodedEmail}?secret={totpSecretToken}&issuer={encodedIssuer}&algorithm=SHA1&digits=6&period=30";

    using var qrGenerator = new QRCodeGenerator();
    using var qrCodeData = qrGenerator.CreateQrCode(otpAuthUri, QRCodeGenerator.ECCLevel.Q);
    using var qrCode = new PngByteQRCode(qrCodeData);

    string base64QrCode = Convert.ToBase64String(qrCode.GetGraphic(20));

    var qrBase64 = $"data:image/png;base64,{base64QrCode}";
    var encryptedToken = EncryptionHelper.Encrypt(totpSecretToken, user.Email);

    return Ok(new NewAuthenticatorQrResponse
    {
        Base64QrCode = qrBase64,
        Secret = encryptedToken,
    });
}

2. Update User Authenticator

Get encrypted token and OTP from user via DTO of request. Get logged in user and decrypt the token by user email. Validate if provided OTP is valid. If valid, set the encrypted token to user data for future verifications.

[HttpPut("UpdateUserAuthenticator")]
public async Task<IActionResult> UpdateUserAuthenticator(AuthenticatorUpdateDto dto)
{
    var user = await GetLoggedInUserId();

    var totpSecret = EncryptionHelper.Decrypt(dto.Secret, user.Email);

    var isValidOtp = IsAuthenticatorOtpValid(totpSecret, dto.Otp);
    if (!isValidOtp)
        return Ok(false);

    user.AuthenticatorToken = dto.Secret;
    _unitOfWork.Users.Update(user);
    await _unitOfWork.SaveAsync();

    return Ok(true);
}

3. Login User API

Check if user credentials are ok and create a temporary token with user id and send as response for next OTP verification step.

[AllowAnonymous]
[HttpPost("UserLogin")]
public async Task<IActionResult> UserLogin(LoginRequestDto dto)
{
    #region User Validation
    // Validates user credentials
    #endregion

    var userSecret = EncryptionHelper.Encrypt(user.Id.ToString(), _cryptoConfiguration.SigningKey);
    var response = new AuthResponse() { UserOtpSecret = userSecret };
    return Ok(response);
}

4. User Login With OTP

Check if user credentials are ok and create a temporary token with user id and send as response for next OTP verification step.

[AllowAnonymous]
[HttpPost("UserLoginWithOtp")]
public async Task<IActionResult> UserLoginWithOtp(LoginWithOtpDto dto)
{
    #region DTO Validation
    // Validates DTO
    #endregion

    var userIdString = EncryptionHelper.Decrypt(dto.UserOtpSecret, _cryptoConfiguration.SigningKey);
    if (!long.TryParse(userIdString, out long userId))
        return Ok(false);

    var user = await _unitOfWork.Login.GetUserById(userId);

    var totpSecret = EncryptionHelper.Decrypt(user.AuthenticatorToken, user.Email);

    var isValidOtp = IsAuthenticatorOtpValid(totpSecret, dto.Otp);
    if (!isValidOtp)
        return Ok(false);

    var (jwtToken, jwtExpiry) = GenerateJWTToken(user);
    var (refreshToken, refreshExpiry) = GenerateRefreshToken();

    var token = new UserToken
    {
        JWTToken = jwtToken,
        JWTExpires = jwtExpiry,
        RefreshToken = refreshToken,
        RefreshExpires = refreshExpiry
    };

    await _unitOfWork.Login.SaveUserToken(token);
    return Ok(token);
}

Is Authenticator OTP Valid Helper Methods

Checks the provided OTP against a secret token and returns boolean response. Allowed two future windows to mitigate issues with server and client system clock slight mismatches.

private static bool IsAuthenticatorOtpValid(string secret, string otp)
{
    if (string.IsNullOrEmpty(secret) || string.IsNullOrEmpty(otp))
        return false;

    var totp = new Totp(Base32Encoding.ToBytes(secret));
    return totp.VerifyTotp(otp, out _, new VerificationWindow(previous: 0, future: 2));
}

Conclusion

Integrating TOTP-based 2FA with QR codes in a .NET application improves security. By leveraging Otp.NET for generating TOTP codes and QRCoder for creating QR codes, users can securely authenticate using Google Authenticator, Microsoft Authenticator, or similar apps. Implement this setup to enhance your application's security and safeguard user accounts effectively.