Skip to main content

.NET HTTPS Implementation

Introduction​

HTTPS (Hypertext Transfer Protocol Secure) is a secure version of HTTP, the protocol used for transmitting data between a web browser and a website. HTTPS encrypts the data exchanged between client and server, protecting sensitive information from potential eavesdropping and tampering.

In this tutorial, we'll explore how to implement HTTPS in .NET applications. We'll cover:

  • The basics of HTTPS and why it's important
  • Setting up HTTPS in ASP.NET Core applications
  • Working with certificates
  • Common pitfalls and troubleshooting

By the end of this guide, you'll understand how to secure your .NET applications with HTTPS, providing a safer experience for your users.

Understanding HTTPS Basics​

What is HTTPS?​

HTTPS uses TLS (Transport Layer Security) to encrypt communications between a client and a server. This encryption ensures:

  1. Confidentiality: Data cannot be read by unauthorized parties
  2. Integrity: Data cannot be modified during transmission
  3. Authentication: The server you're connecting to is actually who it claims to be

Why HTTPS Matters for .NET Applications​

For .NET developers, implementing HTTPS is crucial because:

  • It protects sensitive user data (login credentials, personal information)
  • Modern browsers mark non-HTTPS sites as "Not Secure"
  • It's required for many modern web features (geolocation, progressive web apps)
  • Search engines prefer HTTPS sites

Implementing HTTPS in ASP.NET Core​

Enabling HTTPS in a New Project​

When you create a new ASP.NET Core project using Visual Studio or the .NET CLI, HTTPS is typically enabled by default. You can verify this in the launchSettings.json file:

json
{
  "iisSettings": {
    "windowsAuthentication": false,
    "anonymousAuthentication": true,
    "iisExpress": {
      "applicationUrl": "http://localhost:5000",
      "sslPort": 5001
    }
  },
  "profiles": {
    "IIS Express": {
      "commandName": "IISExpress",
      "launchBrowser": true,
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    },
    "YourAppName": {
      "commandName": "Project",
      "launchBrowser": true,
      "applicationUrl": "https://localhost:5001;http://localhost:5000",
      "environmentVariables": {
        "ASPNETCORE_ENVIRONMENT": "Development"
      }
    }
  }
}

Notice the https://localhost:5001 URL and the sslPort setting.

Configuring HTTPS in Program.cs​

In ASP.NET Core, you configure HTTPS in your Program.cs file. Here's how to set it up:

csharp
var builder = WebApplication.CreateBuilder(args);

// Add services to the container.
builder.Services.AddControllersWithViews();

// Configure Kestrel to use HTTPS
builder.WebHost.ConfigureKestrel(serverOptions =>
{
    serverOptions.Listen(IPAddress.Any, 5000); // HTTP
    serverOptions.Listen(IPAddress.Any, 5001, listenOptions =>
    {
        listenOptions.UseHttps(httpsOptions =>
        {
            httpsOptions.ServerCertificate = 
                new X509Certificate2("certificate.pfx", "password");
        });
    });
});

var app = builder.Build();

// Configure the HTTP request pipeline.
if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Home/Error");
    // The default HSTS value is 30 days
    app.UseHsts();
}

app.UseHttpsRedirection();
app.UseStaticFiles();

app.UseRouting();
app.UseAuthorization();

app.MapControllerRoute(
    name: "default",
    pattern: "{controller=Home}/{action=Index}/{id?}");

app.Run();

Let's highlight a few important parts:

  1. UseHttps(): Configures Kestrel to use HTTPS with a certificate
  2. UseHsts(): Enables HTTP Strict Transport Security, which tells browsers to always use HTTPS
  3. UseHttpsRedirection(): Automatically redirects HTTP requests to HTTPS

Requiring HTTPS for Your Application​

You can enforce HTTPS across your entire application using the [RequireHttps] attribute:

csharp
// Apply to a controller
[RequireHttps]
public class AccountController : Controller
{
    // Controller actions
}

// Or apply globally in Program.cs
builder.Services.AddControllers(options =>
{
    options.Filters.Add(new RequireHttpsAttribute());
});

Working with SSL Certificates​

Development Certificates​

For development purposes, ASP.NET Core automatically creates a self-signed development certificate. You can manage this certificate using the .NET CLI:

bash
# Create a development certificate
dotnet dev-certs https

# Trust the development certificate
dotnet dev-certs https --trust

# Check if the development certificate is trusted
dotnet dev-certs https --check --trust

The output will confirm if your certificate is valid and trusted.

Production Certificates​

For production environments, you'll need a valid SSL certificate from a trusted Certificate Authority (CA). Options include:

  1. Commercial CAs: DigiCert, Comodo, etc.
  2. Let's Encrypt: Free, automated certificates
  3. Certificate from your hosting provider: Azure, AWS, etc.

Here's how to use a certificate in a production environment:

csharp
// In Program.cs
if (app.Environment.IsDevelopment())
{
    // Use development certificate
}
else
{
    // Use production certificate
    builder.WebHost.ConfigureKestrel(serverOptions =>
    {
        serverOptions.Listen(IPAddress.Any, 443, listenOptions =>
        {
            // Load certificate from file
            listenOptions.UseHttps("production-cert.pfx", "certPassword");
            
            // Or load from certificate store
            // var cert = CertificateLoader.LoadFromStore("thumbprint");
            // listenOptions.UseHttps(cert);
        });
    });
}

Loading Certificates from Different Sources​

You can load certificates from various sources:

csharp
// From a file
var cert1 = new X509Certificate2("certificate.pfx", "password");

// From certificate store
var store = new X509Store(StoreName.My, StoreLocation.LocalMachine);
store.Open(OpenFlags.ReadOnly);
var cert2 = store.Certificates.Find(
    X509FindType.FindByThumbprint, 
    "thumbprint", 
    false
)[0];
store.Close();

// From Azure Key Vault (requires Microsoft.Azure.KeyVault NuGet package)
var keyVaultClient = new KeyVaultClient(
    new KeyVaultClient.AuthenticationCallback(GetToken));
var secret = await keyVaultClient.GetSecretAsync(
    "https://myvault.vault.azure.net/secrets/mycertificate");
var privateKeyBytes = Convert.FromBase64String(secret.Value);
var cert3 = new X509Certificate2(
    privateKeyBytes, 
    (string)null, 
    X509KeyStorageFlags.MachineKeySet | 
    X509KeyStorageFlags.PersistKeySet | 
    X509KeyStorageFlags.Exportable);

Making HTTPS Requests in .NET​

Using HttpClient​

When your application needs to consume HTTPS APIs, you'll use HttpClient. Here's how to make secure HTTPS requests:

csharp
// Basic HTTPS GET request
public async Task<string> GetSecureDataAsync()
{
    using var client = new HttpClient();
    var response = await client.GetAsync("https://api.example.com/data");
    response.EnsureSuccessStatusCode();
    return await response.Content.ReadAsStringAsync();
}

// POST request with JSON
public async Task<User> CreateUserAsync(User user)
{
    using var client = new HttpClient();
    var content = new StringContent(
        JsonSerializer.Serialize(user),
        Encoding.UTF8,
        "application/json");
        
    var response = await client.PostAsync("https://api.example.com/users", content);
    response.EnsureSuccessStatusCode();
    
    var responseContent = await response.Content.ReadAsStringAsync();
    return JsonSerializer.Deserialize<User>(responseContent);
}

Handling Certificate Validation​

Sometimes you need custom certificate validation, especially when dealing with self-signed certificates in non-production environments:

csharp
public HttpClient CreateClientWithCustomValidation()
{
    var handler = new HttpClientHandler();
    
    // Only use in development/testing scenarios
    if (Environment.GetEnvironmentVariable("ASPNETCORE_ENVIRONMENT") == "Development")
    {
        handler.ServerCertificateCustomValidationCallback = 
            (message, cert, chain, errors) => true; // Accept any certificate
    }
    
    return new HttpClient(handler);
}

// A more secure custom validation approach
public HttpClient CreateClientWithBetterValidation()
{
    var handler = new HttpClientHandler();
    handler.ServerCertificateCustomValidationCallback = (message, cert, chain, errors) =>
    {
        // Accept certificates from trusted roots, but also specific self-signed certs
        if (errors == SslPolicyErrors.None)
            return true;
            
        // Check if it's our specific self-signed cert
        if (cert.GetCertHashString() == "expected-thumbprint")
            return true;
            
        return false;
    };
    
    return new HttpClient(handler);
}

Warning: Always avoid disabling certificate validation in production code as it undermines the security that HTTPS provides.

Real-World Example: Secure API with Authentication​

Let's build a complete example of a secure API with JWT authentication:

  1. First, create a new API project:
bash
dotnet new webapi -n SecureApi
cd SecureApi
  1. Add necessary packages:
bash
dotnet add package Microsoft.AspNetCore.Authentication.JwtBearer
  1. Configure JWT authentication in Program.cs:
csharp
using Microsoft.AspNetCore.Authentication.JwtBearer;
using Microsoft.IdentityModel.Tokens;
using System.Text;

var builder = WebApplication.CreateBuilder(args);

// Add services to the container
builder.Services.AddControllers();

// Configure JWT authentication
builder.Services.AddAuthentication(options =>
{
    options.DefaultAuthenticateScheme = JwtBearerDefaults.AuthenticationScheme;
    options.DefaultChallengeScheme = JwtBearerDefaults.AuthenticationScheme;
})
.AddJwtBearer(options =>
{
    options.TokenValidationParameters = new TokenValidationParameters
    {
        ValidateIssuer = true,
        ValidateAudience = true,
        ValidateLifetime = true,
        ValidateIssuerSigningKey = true,
        ValidIssuer = builder.Configuration["Jwt:Issuer"],
        ValidAudience = builder.Configuration["Jwt:Audience"],
        IssuerSigningKey = new SymmetricSecurityKey(
            Encoding.UTF8.GetBytes(builder.Configuration["Jwt:Key"]))
    };
    
    // Only allow HTTPS
    options.RequireHttpsMetadata = true;
});

var app = builder.Build();

// Configure the HTTP request pipeline
if (app.Environment.IsDevelopment())
{
    app.UseDeveloperExceptionPage();
}

app.UseHttpsRedirection();
app.UseRouting();

app.UseAuthentication();
app.UseAuthorization();

app.MapControllers();

app.Run();
  1. Create an authentication controller:
csharp
using Microsoft.AspNetCore.Mvc;
using Microsoft.IdentityModel.Tokens;
using System;
using System.IdentityModel.Tokens.Jwt;
using System.Security.Claims;
using System.Text;

[ApiController]
[Route("api/[controller]")]
public class AuthController : ControllerBase
{
    private readonly IConfiguration _configuration;
    
    public AuthController(IConfiguration configuration)
    {
        _configuration = configuration;
    }
    
    [HttpPost("login")]
    public IActionResult Login([FromBody] LoginModel login)
    {
        // In a real app, validate credentials against a database
        if (IsValidUser(login))
        {
            var token = GenerateJwtToken(login.Username);
            return Ok(new { Token = token });
        }
        
        return Unauthorized();
    }
    
    private bool IsValidUser(LoginModel login)
    {
        // Demo validation - replace with database check
        return login.Username == "demo" && login.Password == "Password123!";
    }
    
    private string GenerateJwtToken(string username)
    {
        var securityKey = new SymmetricSecurityKey(
            Encoding.UTF8.GetBytes(_configuration["Jwt:Key"]));
        var credentials = new SigningCredentials(
            securityKey, SecurityAlgorithms.HmacSha256);
            
        var claims = new[]
        {
            new Claim(ClaimTypes.Name, username),
            // Add more claims as needed
            new Claim(JwtRegisteredClaimNames.Jti, Guid.NewGuid().ToString())
        };
        
        var token = new JwtSecurityToken(
            issuer: _configuration["Jwt:Issuer"],
            audience: _configuration["Jwt:Audience"],
            claims: claims,
            expires: DateTime.Now.AddHours(1),
            signingCredentials: credentials
        );
        
        return new JwtSecurityTokenHandler().WriteToken(token);
    }
}

public class LoginModel
{
    public string Username { get; set; }
    public string Password { get; set; }
}
  1. Create a protected controller:
csharp
using Microsoft.AspNetCore.Authorization;
using Microsoft.AspNetCore.Mvc;

[ApiController]
[Route("api/[controller]")]
public class SecureDataController : ControllerBase
{
    [HttpGet]
    [AllowAnonymous]
    public IActionResult GetPublicData()
    {
        return Ok(new { Message = "This data is public" });
    }
    
    [HttpGet("protected")]
    [Authorize] // Requires authentication
    public IActionResult GetProtectedData()
    {
        return Ok(new { 
            Message = $"This is protected data for {User.Identity.Name}" 
        });
    }
}
  1. Add configuration to appsettings.json:
json
{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Warning"
    }
  },
  "AllowedHosts": "*",
  "Jwt": {
    "Key": "YourSuperSecretKeyThatShouldBeAtLeast128bitsSomethingLongAndComplexGoesHere",
    "Issuer": "https://yourapp.com",
    "Audience": "https://yourapp.com"
  }
}

Testing the secure API:

  1. Start your application with dotnet run
  2. Use an HTTP client like Postman to:
    • Get a token with POST https://localhost:5001/api/auth/login and credentials
    • Access protected endpoint with GET https://localhost:5001/api/securedata/protected using the bearer token

Common HTTPS Issues and Solutions​

Certificate Problems​

  1. Untrusted Development Certificate

    • Issue: Browser warnings about untrusted certificate
    • Solution: Run dotnet dev-certs https --trust

  2. Certificate Expiration

    • Issue: HTTPS stops working when certificates expire
    • Solution: Set up monitoring and automatic renewal (especially with Let's Encrypt)

  3. Certificate Chain Issues

    • Issue: Incomplete certificate chain causing trust issues
    • Solution: Ensure intermediate certificates are included in your deployment

Configuration Issues​

  1. CORS with HTTPS
    • Issue: Cross-origin requests fail with mixed content
    • Solution: Update CORS policy to specifically allow HTTPS:
csharp
builder.Services.AddCors(options =>
{
    options.AddPolicy("SecurePolicy", policy =>
    {
        policy.WithOrigins("https://trustedsite.com")
              .AllowAnyMethod()
              .AllowAnyHeader();
    });
});

// In the request pipeline
app.UseCors("SecurePolicy");
  1. HSTS Configuration
    • Issue: Improper HSTS settings can cause access issues
    • Solution: Configure appropriate max-age:
csharp
app.UseHsts(options =>
{
    options.MaxAge(days: 365);
    options.IncludeSubdomains();
    options.Preload();
});
  1. Proxy or Load Balancer Issues
    • Issue: HTTPS termination at proxy causes issues with redirects
    • Solution: Configure forwarded headers middleware:
csharp
builder.Services.Configure<ForwardedHeadersOptions>(options =>
{
    options.ForwardedHeaders = ForwardedHeaders.XForwardedFor | 
                               ForwardedHeaders.XForwardedProto;
});

// Place early in the pipeline
app.UseForwardedHeaders();

Performance Considerations​

HTTPS does introduce some overhead, but modern optimizations minimize the impact:

  1. Connection Reuse: Keep connections alive to avoid repeated handshakes
  2. OCSP Stapling: Improves certificate validation performance
  3. HTTP/2 Support: Only available over HTTPS, improves performance

Configure Kestrel for optimal HTTPS performance:

csharp
builder.WebHost.ConfigureKestrel(serverOptions =>
{
    serverOptions.Listen(IPAddress.Any, 443, listenOptions =>
    {
        listenOptions.UseHttps(httpsOptions =>
        {
            // Use HTTP/2
            listenOptions.Protocols = HttpProtocols.Http1AndHttp2;
            
            // Configure TLS for better performance
            httpsOptions.SslProtocols = SslProtocols.Tls13 | SslProtocols.Tls12;
        });
    });
});

Summary​

In this tutorial, we've covered:

  • The fundamentals of HTTPS and why it's essential
  • How to implement HTTPS in ASP.NET Core applications
  • Working with certificates in development and production
  • Making secure HTTPS requests with HttpClient
  • Building a complete secure API example
  • Troubleshooting common HTTPS issues

HTTPS is no longer optional for modern web applications—it's a requirement. By following the practices outlined in this tutorial, you can ensure your .NET applications are secure and trustworthy.

Additional Resources​

Exercises​

  1. Create a new ASP.NET Core web application and configure it to use HTTPS with a development certificate.
  2. Implement a secure API endpoint that requires authentication and can only be accessed via HTTPS.
  3. Write a client application that makes HTTPS requests to your secure API.
  4. Configure your application to use HSTS with appropriate settings.
  5. Research how to implement HTTPS certificate pinning in .NET for additional security.

If you spot any mistakes on this website, please let me know at [email protected]. I’d greatly appreciate your feedback! :)