README.md

ASP.NET Core + Let's Encrypt

HTTPS made easy.

---

Let's Encrypt is a free, automated, and open Certificate Authority. This project provides API for ASP.NET Core projects to use Let's Encrypt.

When enabled, your web server will use the Let's Encrypt certificate authority and automatically generate an HTTPS certificate when the server starts up. It then configures Kestrel to use this certificate for all HTTPs traffic. See usage instructions below to get started.

Created and developed by @natemcmaster with ❤️ from Seattle ☕

Special thanks to my sponsors!

• @bordenit

Will this work for me?

That depends on which kind of web server you are using. This library only works with Kestrel, which is the default server configuration for ASP.NET Core projects. Other servers, such as IIS and HTTP.sys, are not supported. Furthermore, this only works when Kestrel is the edge server.

Not sure? Read "Web Server Scenarios" below for more details.

Using ☁️ Azure App Services (aka WebApps)? This library isn't for you, but you can still get free HTTPS certificates from Let's Encrypt. See "Securing An Azure App Service with Let's Encrypt" by Scott Hanselman for more details.

Usage

Install this package into your project using NuGet (see details here).

The primary API usage is to call IServiceCollection.AddLetsEncrypt in the Startup class ConfigureServices method.

using Microsoft.Extensions.DependencyInjection;

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

A few required options should be set, typically via the appsettings.json file.

// appsettings.json
{
    "LetsEncrypt": {
        // Set this to automatically accept Let's Encrypt's terms of service.
        // If you don't set this in config, you will need to press "y" whenever the application starts
        "AcceptTermsOfService": true,

        // You must at least one domain name
        "DomainNames": [ "example.com", "www.example.com" ],

        // You must specify an email address to register with letsencrypt.org
        "EmailAddress": "[email protected]"
    }
}

Additional options

Certificates are stored to the machine's X.509 store by default. Certificates can be stored in additional locations by using extension methods after calling AddLetsEncrypt() in the Startup class.

Multiple storage locations can be configured.

Save generated certificates and account information to a directory

using McMaster.AspNetCore.LetsEncrypt;

public void ConfigureServices(IServiceCollection services)
{
    services
        .AddLetsEncrypt()
        .PersistDataToDirectory(new DirectoryInfo("C:/data/LetsEncrypt/"), "Password123");
}

Save generated certificates to Azure Key Vault

Install McMaster.AspNetCore.LetsEncrypt.Azure.

public void ConfigureServices(IServiceCollection services)
{
    services
        .AddLetsEncrypt()
        .PersistCertificatesToAzureKeyVault(o =>
        {
            o.AzureKeyVaultEndpoint = "https://[url].vault.azure.net/";
        });
}

Testing in development

See the developer docs for details on how to test Let's Encrypt in a non-production environment.

Web Server Scenarios

I recommend also reading Microsoft's official documentation on hosting and deploying ASP.NET Core.

ASP.NET Core with Kestrel

✅ supported

In this scenario, ASP.NET Core is hosted by the Kestrel server (the default, in-process HTTP server) and that web server exposes its ports directly to the internet. This library will configure Kestrel with a Let's Encrypt auto-generated certificate.

ASP.NET Core with IIS

❌ NOT supported

In this scenario, ASP.NET Core is hosted by IIS and that web server exposes its ports directly to the internet. IIS does not support dynamically configuring HTTPS certificates, so this library cannot support this scenario, but you can still configure Let's Encrypt using a different tool. See "Using Let's Encrypt with IIS On Windows" for details.

Azure App Service uses this for ASP.NET Core 2.2 and newer, which is why this library cannot support that scenario.. Older versions of ASP.NET Core on Azure App Service run with IIS as the reverse proxy (see below), which is also an unsupported scenario.

ASP.NET Core with Kestrel Behind a TCP Load Balancer (aka SSL pass-thru)

✅ supported

In this scenario, ASP.NET Core is hosted by the Kestrel server (the default, in-process HTTP server) and that web server exposes its ports directly to a local network. A TCP load balancer such as nginx forwards traffic without decrypting it to the host running Kestrel. This library will configure Kestrel with a Let's Encrypt auto-generated certificate.

ASP.NET Core with Kestrel Behind a Reverse Proxy

❌ NOT supported

In this scenario, HTTPS traffic is decrypted by a different web server that is beyond the control of ASP.NET Core. This library cannot support this scenario because HTTPS certificates must be configured by the reverse proxy server.

This is commonly done by web hosting providers. For example, ☁️ Azure App Services (aka WebApps) often runs older versions of ASP.NET Core in a reverse proxy.

If you are running the reverse proxy, you can still get free HTTPS certificates from Let's Encrypt, but you'll need to use a different method. See "Let's Encrypt Nginx" for details.