如何通过编程配置Kestrel，使其在生产环境无需开发证书？

问题 #

使用.NET 6编写Kestrel服务，指定端口监听所有IP并通过配置加载SSL证书。开发机和有开发证书的UAT服务器运行正常，但部署到无开发证书的生产环境时启动失败，报错：

Unable to configure HTTPS endpoint. No server certificate was specified, and the default developer certificate could not be found...

在UAT服务器移除开发证书后也会复现该问题，重新安装证书则恢复正常。希望找到无需在生产服务器安装开发证书的解决办法。

相关代码：

WebApplicationBuilder builder = WebApplication.CreateBuilder(options);

builder.Host.UseWindowsService(options => options.ServiceName = "Windows Kestrel Server");

builder.WebHost.ConfigureKestrel(serverOptions =>
  {
      int Port = builder.Configuration.GetValue<int>("Port");
      
      serverOptions.ListenAnyIP(Port, listenOptions =>
      {
          listenOptions.UseHttps(httpsOptions =>
          {
              listenOptions.UseHttps((stream, clientHelloInfo, state, cancellationToken) =>
              {
                  string? StoreName = builder.Configuration.GetSection("CertificateStore").Value;
                  string? CertName = builder.Configuration.GetSection("CertificateName").Value;

                  if (StoreName == null)
                    StoreName = "My";
                  if (string.IsNullOrEmpty(CertName))
                    CertName = clientHelloInfo.ServerName;
                  X509Certificate2? Cert = null;
                  try
                  {
                      Cert = CertificateLoader.LoadFromStoreCert(CertName, StoreName, StoreLocation.LocalMachine, allowInvalid: false);
                  }
                  catch { };
                  try
                  {
                      if (Cert == null)
                          Cert = CertificateLoader.LoadFromStoreCert(CertName, StoreName, StoreLocation.CurrentUser, allowInvalid: false);
                  }
                  catch { };
                  
                  return new ValueTask<SslServerAuthenticationOptions>(new SslServerAuthenticationOptions { ServerCertificate = Cert});

              }, state: null!);
              
          });
      });
  });

解决方案 #

核心原因 #

代码存在两处关键问题：

1. 嵌套调用listenOptions.UseHttps，先触发无参数的默认HTTPS配置逻辑，导致Kestrel优先尝试加载开发证书
2. 证书加载失败时静默忽略异常，返回null证书，触发Kestrel的 fallback 逻辑去查找开发证书

修复措施 #

1. 移除冗余的HTTPS配置调用
   直接使用带证书选择回调的UseHttps重载，无需先调用空参数版本，避免触发默认证书加载逻辑

2. 完善证书加载的错误处理

   • 移除空catch块，添加错误日志便于排查
   • 证书加载失败时主动抛出异常，避免Kestrel尝试 fallback 到开发证书

3. 优化后的代码示例

WebApplicationBuilder builder = WebApplication.CreateBuilder(options);

builder.Host.UseWindowsService(options => options.ServiceName = "Windows Kestrel Server");

builder.WebHost.ConfigureKestrel(serverOptions =>
{
    int Port = builder.Configuration.GetValue<int>("Port");
    
    serverOptions.ListenAnyIP(Port, listenOptions =>
    {
        // 直接使用带回调的UseHttps重载，跳过默认证书逻辑
        listenOptions.UseHttps((stream, clientHelloInfo, state, cancellationToken) =>
        {
            string storeName = builder.Configuration.GetSection("CertificateStore").Value ?? "My";
            string certName = builder.Configuration.GetSection("CertificateName").Value ?? clientHelloInfo.ServerName;
            X509Certificate2? cert = null;
            var logger = builder.Logging.CreateLogger("CertificateLoader");

            try
            {
                cert = CertificateLoader.LoadFromStoreCert(certName, storeName, StoreLocation.LocalMachine, allowInvalid: false);
            }
            catch (Exception ex)
            {
                logger.LogError(ex, "加载LocalMachine存储区证书失败：{CertName}", certName);
            }

            if (cert == null)
            {
                try
                {
                    cert = CertificateLoader.LoadFromStoreCert(certName, storeName, StoreLocation.CurrentUser, allowInvalid: false);
                }
                catch (Exception ex)
                {
                    logger.LogError(ex, "加载CurrentUser存储区证书失败：{CertName}", certName);
                }
            }

            // 证书未找到时主动抛出异常，阻止Kestrel fallback到开发证书
            if (cert == null)
            {
                throw new InvalidOperationException($"未在存储区'{storeName}'找到名称为'{certName}'的证书");
            }

            return new ValueTask<SslServerAuthenticationOptions>(new SslServerAuthenticationOptions { ServerCertificate = cert });
        }, state: null!);
    });
});

4. 更简洁的配置文件方式
   无需手写证书加载代码，直接在appsettings.json中配置Kestrel端点：

"Kestrel": {
  "Endpoints": {
    "Https": {
      "Url": "https://*:你的端口号",
      "Certificate": {
        "StoreName": "My",
        "StoreLocation": "LocalMachine",
        "Subject": "你的证书主题名称"
      }
    }
  }
}

这种方式下Kestrel会直接加载配置的证书，不会触发开发证书的 fallback 逻辑。

额外注意事项 #

• 确保生产环境的证书已正确安装到指定存储区，且服务运行账号拥有读取证书的权限
• 避免在生产环境启用开发证书相关的配置（如ASPNETCORE_ENVIRONMENT设为Production）

内容的提问来源于stack exchange，提问作者Brian Boyington