Integrating Have I Been Pwned API in ASP.NET Core for Password Breach Checks

Date- May 25,2026 188

haveibeenpwned aspnetcore

Overview

The Have I Been Pwned API is a powerful tool designed to help developers and organizations determine if a user’s password has been compromised in data breaches. By leveraging this API, applications can proactively warn users to change their passwords, thus improving overall security. This service is vital in an era where data breaches are rampant, and users often reuse passwords across multiple sites.

The API operates on a simple principle: when a password is checked, it is hashed using the SHA-1 algorithm, and only the first five characters of the hash are sent to the API. The API responds with the count of occurrences of that password in known breaches, allowing the application to determine if a password is safe or not. This approach not only maintains user privacy but also minimizes the amount of data sent over the network.

Real-world use cases include applications that require user registration or password changes. By integrating this API, developers can enhance user experience and security by preventing users from selecting compromised passwords. This integration can be particularly useful in applications dealing with sensitive data, such as financial services or healthcare.

Prerequisites

ASP.NET Core: Basic understanding of creating and managing an ASP.NET Core application.
HTTP Client: Familiarity with making HTTP requests in .NET.
NuGet Packages: Knowledge of how to install and manage NuGet packages in your project.
JSON Handling: Understanding JSON serialization and deserialization.

Setting Up the ASP.NET Core Project

To begin, you need to set up an ASP.NET Core project. This will serve as the foundation for integrating the Have I Been Pwned API.

dotnet new webapp -n PasswordBreachCheck

This command creates a new ASP.NET Core web application named PasswordBreachCheck. Next, navigate to the project directory:

cd PasswordBreachCheck

Ensure that your project runs correctly by executing:

dotnet run

You should see the default web application running. This project will serve as the basis for integrating our password breach check functionality.

Adding Necessary NuGet Packages

To work with HTTP requests and JSON, you need to add the System.Net.Http and Newtonsoft.Json packages. You can do this using the following commands:

dotnet add package Microsoft.Extensions.Http
dotnet add package Newtonsoft.Json

Creating the Service for API Integration

Next, we will create a service class that handles communication with the Have I Been Pwned API. This class will encapsulate the logic to make HTTP requests and process responses.

using System.Net.Http;
using System.Security.Cryptography;
using System.Text;
using System.Threading.Tasks;
using Newtonsoft.Json;

public class PasswordBreachService
{
    private readonly HttpClient _httpClient;

    public PasswordBreachService(HttpClient httpClient)
    {
        _httpClient = httpClient;
    }

    public async Task CheckPasswordBreachAsync(string password)
    {
        var hash = CalculateSha1Hash(password);
        var prefix = hash.Substring(0, 5);
        var response = await _httpClient.GetAsync($"https://api.pwnedpasswords.com/range/{prefix}");

        response.EnsureSuccessStatusCode();
        var content = await response.Content.ReadAsStringAsync();
        return ParseBreachCount(content, hash.Substring(5).ToUpper());
    }

    private string CalculateSha1Hash(string password)
    {
        using (var sha1 = SHA1.Create())
        {
            var bytes = Encoding.ASCII.GetBytes(password);
            var hash = sha1.ComputeHash(bytes);
            return BitConverter.ToString(hash).Replace("-", "").ToLower();
        }
    }

    private int ParseBreachCount(string content, string hashSuffix)
    {
        foreach (var line in content.Split('\n'))
        {
            var parts = line.Split(':');
            if (parts[0].Equals(hashSuffix, StringComparison.OrdinalIgnoreCase))
            {
                return int.Parse(parts[1]);
            }
        }
        return 0;
    }
}

This service class, PasswordBreachService, is structured to perform the following tasks:

Constructor: Accepts an HttpClient instance for making HTTP requests.
CheckPasswordBreachAsync: Accepts a password, calculates its SHA-1 hash, and sends a GET request to the Have I Been Pwned API using the first five characters of the hash.
CalculateSha1Hash: Converts the password into its SHA-1 hash format.
ParseBreachCount: Parses the API response to find the count of breaches for the provided password hash suffix.

Each method is designed to handle specific parts of the API integration, ensuring that the class adheres to the single responsibility principle.

Configuring Dependency Injection

ASP.NET Core uses Dependency Injection (DI) to manage service lifetimes and dependencies. To utilize the PasswordBreachService, you must configure it in the Startup.cs file.

public class Startup
{
    public void ConfigureServices(IServiceCollection services)
    {
        services.AddHttpClient();
        services.AddControllersWithViews();
    }

    public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
    {
        // Configuration omitted for brevity...
    }
}

This configuration does two things:

Registers the PasswordBreachService with the dependency injection container.
Sets up an HttpClient specifically for the service, which is managed by the DI container.

Creating the Controller

Now, create a controller that will handle HTTP requests for checking passwords against the breach database. The controller will utilize the PasswordBreachService to perform the checks.

using Microsoft.AspNetCore.Mvc;
using System.Threading.Tasks;

public class PasswordController : Controller
{
    private readonly PasswordBreachService _passwordBreachService;

    public PasswordController(PasswordBreachService passwordBreachService)
    {
        _passwordBreachService = passwordBreachService;
    }

    [HttpPost("/checkpassword")]
    public async Task CheckPassword(string password)
    {
        var breachCount = await _passwordBreachService.CheckPasswordBreachAsync(password);
        return Json(new { breachCount });
    }
}

This PasswordController contains:

Dependency Injection: The controller receives an instance of PasswordBreachService through its constructor.
CheckPassword Action: A POST action that accepts a password, checks it against the breach database, and returns the breach count as a JSON response.

Creating the Frontend Form

Next, we need a simple frontend form to allow users to input their passwords for breach checks. In the Views directory, create a new view named CheckPassword.cshtml.

@{
    ViewData["Title"] = "Check Password Breach";
}
Check Your Password

This HTML code includes:

A simple form with an input for the password and a submit button.
A jQuery script that handles the form submission, sends the password to the controller, and displays the result.

Testing the Application

Run your application again using the dotnet run command. Navigate to the appropriate route to access the form. Enter a password and submit the form to see the results. If the password has been breached, you will see a message indicating the number of times it has been pwned.

Edge Cases & Gotchas

When integrating with the Have I Been Pwned API, there are several edge cases and gotchas to consider:

Network Issues: Ensure proper error handling for network failures or timeouts. If the API is unreachable, inform the user gracefully.
Rate Limiting: The API has rate limits. Avoid hammering the API with requests; implement caching strategies for repeated checks.
Input Validation: Always validate user input before processing to prevent unnecessary API calls and potential abuse.

Performance & Best Practices

To ensure optimal performance when integrating with the Have I Been Pwned API, consider the following best practices:

Asynchronous Patterns: Use asynchronous programming (as demonstrated in the examples) to prevent blocking the main thread and improve responsiveness.
Caching: Implement caching for previously checked passwords to reduce the number of API calls, especially for common passwords.
Batch Requests: If checking multiple passwords, consider batching requests to minimize latency and improve overall performance.

Real-World Scenario

Let’s consider a realistic scenario where you need to implement password checks during user registration and password change workflows. The following is a mini-project that encapsulates all previous implementations.

using Microsoft.AspNetCore.Mvc;
using System.Threading.Tasks;

public class UserController : Controller
{
    private readonly PasswordBreachService _passwordBreachService;

    public UserController(PasswordBreachService passwordBreachService)
    {
        _passwordBreachService = passwordBreachService;
    }

    [HttpPost("/register")]
    public async Task Register(string username, string password)
    {
        var breachCount = await _passwordBreachService.CheckPasswordBreachAsync(password);
        if (breachCount > 0)
        {
            return BadRequest("Password has been pwned. Please choose a different password.");
        }
        // Register the user (omitted for brevity)
        return Ok("User registered successfully.");
    }

    [HttpPost("/changepassword")]
    public async Task ChangePassword(string oldPassword, string newPassword)
    {
        var breachCount = await _passwordBreachService.CheckPasswordBreachAsync(newPassword);
        if (breachCount > 0)
        {
            return BadRequest("New password has been pwned. Please choose a different password.");
        }
        // Change the password (omitted for brevity)
        return Ok("Password changed successfully.");
    }
}

This UserController demonstrates how to check passwords during user registration and password changes. It provides feedback to users if their chosen passwords are compromised, ensuring a more secure experience.

Conclusion

Integrating the Have I Been Pwned API enhances security in applications by preventing the use of compromised passwords.
Understanding how to work with HTTP requests and JSON in ASP.NET Core is crucial for API integrations.
Implementing best practices, such as caching and handling edge cases, improves the robustness of your implementation.
Consider utilizing this API in user registration and password management workflows for a more secure application.