https_setup.md

HTTPS and Certificate Handling Setup for Kestrel (.NET Core 3.1 / .NET 8)

This document details how to configure HTTPS for the ASP.NET Core application using the Kestrel web server, ensuring secure communication for the webhook endpoint.

1. Configuration Methods

ASP.NET Core offers several ways to configure Kestrel endpoints, including HTTPS. The recommended approach for flexibility, especially across different environments (development, staging, production), is using appsettings.json combined with environment variables or other configuration providers.

a) Using appsettings.json (Recommended)

This method allows defining endpoints, ports, and certificate details in the configuration file. Sensitive information like the certificate password should ideally be overridden by more secure sources in production (e.g., environment variables, Azure Key Vault, GCP Secret Manager).

Example appsettings.json:

{
  "Kestrel": {
    "Endpoints": {
      "Http": {
        "Url": "http://*:80" // Optional: Listen on HTTP as well, consider redirection
      },
      "Https": {
        "Url": "https://*:443", // Listen on all network interfaces on port 443
        "Certificate": {
          "Path": "path/to/your/certificate.pfx", // Path to the certificate file
          "Password": "YourCertificatePassword" // Password for the PFX file
        }
      }
    }
  },
  // Other settings...
}

• Url: https://*:443 binds HTTPS to port 443 on all available network interfaces. This is crucial for accessibility when deployed.
• Certificate:Path: The path to your .pfx or .pem certificate file. Use relative or absolute paths as appropriate for your deployment.
• Certificate:Password: The password for the certificate file. Security Note: Avoid storing the actual password directly in appsettings.json under source control. Use User Secrets in development and environment variables, Key Vault, or GCP Secret Manager in production. You can reference environment variables like "Password": "${CERT_PASSWORD}" (syntax might vary slightly based on config provider setup).

b) Using Program.cs / Startup.cs

You can also configure Kestrel programmatically when building the host.

Example (Program.cs for .NET 6+ style):

public static void Main(string[] args)
{
    var builder = WebApplication.CreateBuilder(args);

    // Load configuration to get certificate path and password
    var configuration = builder.Configuration;
    var certPath = configuration["Kestrel:Endpoints:Https:Certificate:Path"];
    var certPassword = configuration["Kestrel:Endpoints:Https:Certificate:Password"]; // Get from secure source

    builder.WebHost.ConfigureKestrel(serverOptions =>
    {
        serverOptions.Listen(System.Net.IPAddress.Any, 443, listenOptions =>
        {
            if (!string.IsNullOrEmpty(certPath) && !string.IsNullOrEmpty(certPassword))
            {
                listenOptions.UseHttps(certPath, certPassword);
            }
            else
            {
                // Fallback or error handling if cert config is missing
                Console.WriteLine("Warning: HTTPS certificate not configured properly.");
                // Consider using development certificate if in Development environment
                // listenOptions.UseHttps(); // Uses dev cert if available
            }
        });

        // Optional: Listen on HTTP as well
        serverOptions.Listen(System.Net.IPAddress.Any, 80);
    });

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

    var app = builder.Build();

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

    app.UseHttpsRedirection(); // Recommended to redirect HTTP to HTTPS
    // ... other middleware

    app.MapControllers();

    app.Run();
}

Note for .NET Core 3.1: The configuration logic would reside within ConfigureWebHostDefaults in Program.cs or potentially within Startup.cs if using a custom Kestrel setup there.

2. Certificate Types and Management

• Development: Use the ASP.NET Core development certificate (dotnet dev-certs https --trust). Kestrel uses this automatically in the Development environment if no specific certificate is configured.
• Production (GCP/Windows Server):
  • Obtain a valid SSL certificate from a Certificate Authority (CA) (e.g., Let's Encrypt, DigiCert, GoDaddy).
  • PFX Format: Typically, you'll use a .pfx file containing both the public key and the private key, protected by a password.
  • Storage:
    • File System: Place the .pfx file securely on the server (e.g., in a non-web-accessible directory with restricted permissions) and reference its path in the configuration.
    • Windows Certificate Store: Import the certificate into the Windows Certificate Store (Local Machine Personal store is common for service accounts). You can then configure Kestrel to load it by Subject Name or Thumbprint via appsettings.json or code. This is often preferred for manageability on Windows. Example appsettings.json for Certificate Store:

      "Certificate": {
        "Subject": "CN=my-gcp-server.com", // Or use Thumbprint
        "Store": "My",
        "Location": "LocalMachine",
        "AllowInvalid": false // Set to true for self-signed certs if needed (not recommended for prod)
      }

3. Secure Password Handling

As mentioned, never commit certificate passwords to source control. Use:

• Environment Variables: Set Kestrel__Endpoints__Https__Certificate__Password (using double underscore __ for nesting) or a custom variable like CERT_PASSWORD.
• Cloud Secret Management: GCP Secret Manager or Azure Key Vault are ideal for storing and retrieving secrets securely at runtime.
• User Secrets (Development Only): dotnet user-secrets set "Kestrel:Endpoints:Https:Certificate:Password" "YourPassword"

4. Firewall Configuration

Ensure that the firewall on the Windows Server (and any GCP firewall rules) allows incoming traffic on port 443 (and port 80 if used for redirection).

By following these steps, the Kestrel server will be configured to listen securely over HTTPS on port 443, using a specified certificate, ready to receive webhook requests.