在 ASP.NET Core 中配置证书身份验证

Microsoft.AspNetCore.Authentication.Certificate 包含类似于 ASP.NET Core 的证书身份验证的实现。 证书身份验证在 TLS 级别发生，远在到达 ASP.NET Core 之前。 更准确地说，这是一个身份验证处理程序，该程序验证证书，然后提供一个事件，可在其中将证书解析为 ClaimsPrincipal。

必须配置服务器以执行证书身份验证，无论使用的是 IIS、Kestrel、Azure Web 应用还是任何其他服务器。

代理和负载均衡器方案

证书身份验证是一种有状态方案，主要用于代理或负载均衡器不处理客户端和服务器之间流量的情况。 如果使用了代理或负载平衡器，则仅当代理或负载均衡器符合以下情况时证书身份验证才起作用：

• 会处理身份验证。
• 将用户身份验证信息传递给应用（例如，在请求头中），应用根据身份验证信息执行操作。

在使用代理和负载平衡器的环境中，证书身份验证的另一种选择是结合使用 Active Directory 联合服务 (ADFS) 和 OpenID Connect (OIDC)。

入门

获取 HTTPS 证书，应用该证书，并配置服务器，将其配置为索要证书。

在 Web 应用中：

• 添加对 Microsoft.AspNetCore.Authentication.Certificate NuGet 包的引用。
• 在 Program.cs 中，调用 builder.Services.AddAuthentication(CertificateAuthenticationDefaults.AuthenticationScheme).AddCertificate(...);。 提供一个委托，使 OnCertificateValidated 能够对与请求一起发送的客户端证书执行任何补充验证。 将该信息转换为 ClaimsPrincipal 并在 context.Principal 属性上设置。

如果身份验证失败，此处理程序会返回一个 403 (Forbidden) 响应，而不是 401 (Unauthorized)，你可能已经想到了。 原因是，身份验证应在初次 TLS 连接期间进行。 它到达处理程序的时间太晚。 无法将连接从匿名连接升级到具有证书的连接。

需要 UseAuthentication 来将 HttpContext.User 设置为从证书创建的 ClaimsPrincipal。 例如：

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddAuthentication(
        CertificateAuthenticationDefaults.AuthenticationScheme)
    .AddCertificate();

var app = builder.Build();

app.UseAuthentication();

app.MapGet("/", () => "Hello World!");

app.Run();

前面的示例演示了添加证书身份验证的默认方法。 处理程序使用通用证书属性构造用户主体。

配置证书验证

CertificateAuthenticationOptions 处理程序具有一些内置验证，这些验证是需要对证书执行的最小程度的验证。 默认启用这些设置中的每一个。

AllowedCertificateTypes = Chained, SelfSigned, or All (Chained | SelfSigned)

默认值：30CertificateTypes.Chained

此检查验证是否只允许使用适当的证书类型。 如果应用使用自签名证书，则此选项需要设置为 CertificateTypes.All 或 CertificateTypes.SelfSigned。

ChainTrustValidationMode

默认值：X509ChainTrustMode.System

客户端提供的证书必须链接到受信任的根证书。 此检查控制哪些信任存储包含这些根证书。

默认情况下，处理程序使用系统信任存储。 如果提供的客户端证书需要链接到系统信任存储中不包含的根证书，可以将此选项设置为 X509ChainTrustMode.CustomRootTrust，以使处理程序使用 CustomTrustStore。

CustomTrustStore

默认值：空 X509Certificate2Collection

如果处理程序的 ChainTrustValidationMode 属性设置为 X509ChainTrustMode.CustomRootTrust，则此 X509Certificate2Collection 包含用于验证客户端证书的、上至（且包括）受信任的根证书的每个证书。

当客户端提供属于多级证书链的证书时，CustomTrustStore 必须包含链中的每个颁发证书。

ValidateCertificateUse

默认值：30true

此检查验证客户端提供的证书是否具有客户端身份验证“增强型密钥使用”(EKU) 或完全没有 EKU。 根据规范，如果未指定 EKU，则所有 EKU 均视为有效。

ValidateValidityPeriod

默认值：30true

此检查验证证书是否在其有效期内。 对于每次请求，处理程序都会确保在出示时有效的证书在其当前会话期间没有过期。

RevocationFlag

默认值：30X509RevocationFlag.ExcludeRoot

一个标志，该标志指定将检查链中的哪些证书，确认其的吊销状态。

仅当证书链接到根证书时才对证书执行吊销检查。

RevocationMode

默认值：30X509RevocationMode.Online

一个标志，该标志指定如何执行吊销检查。

指定联机检查可能会导致在联系证书颁发机构时发生长时间延迟。

仅当证书链接到根证书时才对证书执行吊销检查。

我可以将我的应用配置为仅在某些路径上索要证书吗？

这不可能。 请记住，证书交换是在 HTTPS 会话开始时完成的，它是由服务器在该连接上收到第一个请求之前完成的，因此无法基于任何请求字段限定作用域。

处理程序事件

处理程序有两个事件：

• OnAuthenticationFailed：在身份验证期间发生异常且你能够作出反应时调用。
• OnCertificateValidated：在对证书进行了验证、通过验证并创建了默认主体后调用。 此事件使你能够执行自己的验证并增强或替换主体。 示例包括：

  • 确定你的服务是否知道该证书。

  • 构造你自己的主体。 请考虑以下示例：

    builder.Services.AddAuthentication(
            CertificateAuthenticationDefaults.AuthenticationScheme)
        .AddCertificate(options =>
        {
            options.Events = new CertificateAuthenticationEvents
            {
                OnCertificateValidated = context =>
                {
                    var claims = new[]
                    {
                        new Claim(
                            ClaimTypes.NameIdentifier,
                            context.ClientCertificate.Subject,
                            ClaimValueTypes.String, context.Options.ClaimsIssuer),
                        new Claim(
                            ClaimTypes.Name,
                            context.ClientCertificate.Subject,
                            ClaimValueTypes.String, context.Options.ClaimsIssuer)
                    };
    
                    context.Principal = new ClaimsPrincipal(
                        new ClaimsIdentity(claims, context.Scheme.Name));
                    context.Success();
    
                    return Task.CompletedTask;
                }
            };
        });
    

如果发现入站证书不符合额外的验证要求，请调用 context.Fail("failure reason") 并附带失败原因。

为了获得更好的功能，请调用注册了“依赖关系注入”且连接到数据库或其他类型用户存储的服务。 通过使用传入委托的上下文来访问服务。 请考虑以下示例：

builder.Services.AddAuthentication(
        CertificateAuthenticationDefaults.AuthenticationScheme)
    .AddCertificate(options =>
    {
        options.Events = new CertificateAuthenticationEvents
        {
            OnCertificateValidated = context =>
            {
                var validationService = context.HttpContext.RequestServices
                    .GetRequiredService<ICertificateValidationService>();

                if (validationService.ValidateCertificate(context.ClientCertificate))
                {
                    var claims = new[]
                    {
                        new Claim(
                            ClaimTypes.NameIdentifier,
                            context.ClientCertificate.Subject,
                            ClaimValueTypes.String, context.Options.ClaimsIssuer),
                        new Claim(
                            ClaimTypes.Name,
                            context.ClientCertificate.Subject,
                            ClaimValueTypes.String, context.Options.ClaimsIssuer)
                    };

                    context.Principal = new ClaimsPrincipal(
                        new ClaimsIdentity(claims, context.Scheme.Name));
                    context.Success();
                }

                return Task.CompletedTask;
            }
        };
    });

从概念上讲，证书验证与授权相关。 在授权策略中而不是在 OnCertificateValidated 中添加（例如）对颁发者或指纹的检查是完全可以接受的。

将服务器配置为索要证书

Kestrel

在 Program.cs 中，按如下所示配置 Kestrel：

var builder = WebApplication.CreateBuilder(args);

builder.Services.Configure<KestrelServerOptions>(options =>
{
    options.ConfigureHttpsDefaults(options =>
        options.ClientCertificateMode = ClientCertificateMode.RequireCertificate);
});

注意

通过在调用 ConfigureHttpsDefaults 之前调用 Listen 创建的终结点将不会应用默认值。

IIS

在 IIS 管理器中完成以下步骤：

1. 从“连接”选项卡中选择你的站点。
2. 双击“功能视图”窗口中的”SSL 设置”选项。
3. 选中“需要 SSL”复选框，并在“客户端证书”部分中选择“需要”单选按钮。

Azure 和自定义 Web 代理

有关如何配置证书转发中间件的信息，请参阅托管和部署文档。

在 Azure Web 应用中使用证书身份验证

不需要针对 Azure 配置转发。 转发配置由证书转发中间件设置。

注意

此方案需要证书转发中间件。

有关详细信息，请参阅在 Azure 应用服务中的代码中使用 TLS/SSL 证书（Azure 文档）。

在自定义 Web 代理中使用证书身份验证

AddCertificateForwarding 方法用于指定：

• 客户端标头名称。
• 如何加载证书（使用 HeaderConverter 属性）。

在自定义 Web 代理中，证书作为自定义请求头传递，例如 X-SSL-CERT。 要使用它，请在 Program.cs 中配置证书转发：

builder.Services.AddCertificateForwarding(options =>
{
    options.CertificateHeader = "X-SSL-CERT";

    options.HeaderConverter = headerValue =>
    {
        X509Certificate2? clientCertificate = null;

        if (!string.IsNullOrWhiteSpace(headerValue))
        {
            clientCertificate = new X509Certificate2(StringToByteArray(headerValue));
        }

        return clientCertificate!;

        static byte[] StringToByteArray(string hex)
        {
            var numberChars = hex.Length;
            var bytes = new byte[numberChars / 2];

            for (int i = 0; i < numberChars; i += 2)
            {
                bytes[i / 2] = Convert.ToByte(hex.Substring(i, 2), 16);
            }

            return bytes;
        }
    };
});

如果应用由 NGINX 通过配置 proxy_set_header ssl-client-cert $ssl_client_escaped_cert 反向代理，或使用 NGINX 入口部署在 Kubernetes 上，则客户端证书将以 URL 编码形式传递给应用。 要使用证书，请按如下方式对其进行解码：

builder.Services.AddCertificateForwarding(options =>
{
    options.CertificateHeader = "ssl-client-cert";

    options.HeaderConverter = (headerValue) =>
    {
        X509Certificate2? clientCertificate = null;

        if (!string.IsNullOrWhiteSpace(headerValue))
        {
            clientCertificate = X509Certificate2.CreateFromPem(
                WebUtility.UrlDecode(headerValue));
        }

        return clientCertificate!;
    };
});

在 Program.cs 中添加中间件。 UseCertificateForwarding 在调用 UseAuthentication 和 UseAuthorization 之前被调用：

var app = builder.Build();

app.UseCertificateForwarding();

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

可以使用单独的类来实现验证逻辑。 由于本例中使用了相同的自签名证书，因此请确保只有你的证书能使用。 验证客户端证书和服务器证书的指纹是否均匹配，否则任何证书都可以使用并足以进行身份验证。 这将在 AddCertificate 方法中使用。 如果使用的是中间证书或子证书，还可以在此处验证主题或颁发者。

using System.Security.Cryptography.X509Certificates;

namespace CertAuthSample.Snippets;

public class SampleCertificateValidationService : ICertificateValidationService
{
    public bool ValidateCertificate(X509Certificate2 clientCertificate)
    {
        // Don't hardcode passwords in production code.
        // Use a certificate thumbprint or Azure Key Vault.
        var expectedCertificate = new X509Certificate2(
            Path.Combine("/path/to/pfx"), "1234");

        return clientCertificate.Thumbprint == expectedCertificate.Thumbprint;
    }
}

使用证书和 IHttpClientFactory 实现 HttpClient

在下面的示例中，使用了处理程序中的 ClientCertificates 属性将客户端证书添加到 HttpClientHandler。 之后可以使用 ConfigurePrimaryHttpMessageHandler 方法在 HttpClient 的命名实例中使用此处理程序。 这在 Program.cs 中设置：

var clientCertificate =
    new X509Certificate2(
      Path.Combine(_environment.ContentRootPath, "sts_dev_cert.pfx"), "1234");

builder.Services.AddHttpClient("namedClient", c =>
{
}).ConfigurePrimaryHttpMessageHandler(() =>
{
    var handler = new HttpClientHandler();
    handler.ClientCertificates.Add(clientCertificate);
    return handler;
});

然后可以使用 IHttpClientFactory 获取具有该处理程序和证书的命名实例。 使用具有在 Program.cs 中定义的客户端名称的 CreateClient 方法来获取实例。 可根据需要使用客户端发送 HTTP 请求：

public class SampleHttpService
{
    private readonly IHttpClientFactory _httpClientFactory;

    public SampleHttpService(IHttpClientFactory httpClientFactory)
        => _httpClientFactory = httpClientFactory;

    public async Task<JsonDocument> GetAsync()
    {
        var httpClient = _httpClientFactory.CreateClient("namedClient");
        var httpResponseMessage = await httpClient.GetAsync("https://example.com");

        if (httpResponseMessage.IsSuccessStatusCode)
        {
            return JsonDocument.Parse(
                await httpResponseMessage.Content.ReadAsStringAsync());
        }

        throw new ApplicationException($"Status code: {httpResponseMessage.StatusCode}");
    }
}

如果将正确的证书发送到服务器，则会返回数据。 如果未发送证书或发送的证书不正确，则会返回 HTTP 403 状态代码。

在 PowerShell 中创建证书

创建证书是设置此流程最难的部分。 可以使用 New-SelfSignedCertificate PowerShell cmdlet 创建根证书。 创建证书时，请使用强密码。 如图所示添加 KeyUsageProperty 参数和 KeyUsage 参数非常重要。

创建根 CA

New-SelfSignedCertificate -DnsName "root_ca_dev_damienbod.com", "root_ca_dev_damienbod.com" -CertStoreLocation "cert:\LocalMachine\My" -NotAfter (Get-Date).AddYears(20) -FriendlyName "root_ca_dev_damienbod.com" -KeyUsageProperty All -KeyUsage CertSign, CRLSign, DigitalSignature

$mypwd = ConvertTo-SecureString -String "1234" -Force -AsPlainText

Get-ChildItem -Path cert:\localMachine\my\"The thumbprint..." | Export-PfxCertificate -FilePath C:\git\root_ca_dev_damienbod.pfx -Password $mypwd

Export-Certificate -Cert cert:\localMachine\my\"The thumbprint..." -FilePath root_ca_dev_damienbod.crt

注意

-DnsName 参数值必须与应用的部署目标匹配。 例如，用于开发的“localhost”。

在受信任的根中安装

根证书必须在主机系统上受信任。 默认情况下，只有由证书颁发机构创建的根证书才会受信任。 有关如何信任 Windows 上的根证书的信息，请参阅 Windows 文档或 Import-Certificate PowerShell cmdlet。

中间证书

现在可以从根证书创建中间证书。 这并不是所有用例所必需的，但有可能需要创建多个证书或需要激活或禁用证书组。 TextExtension 参数是设置证书基本约束中的路径长度所必需的。

然后可以将中间证书添加为 Windows 主机系统中受信任的中间证书。

$mypwd = ConvertTo-SecureString -String "1234" -Force -AsPlainText

$parentcert = ( Get-ChildItem -Path cert:\LocalMachine\My\"The thumbprint of the root..." )

New-SelfSignedCertificate -certstorelocation cert:\localmachine\my -dnsname "intermediate_dev_damienbod.com" -Signer $parentcert -NotAfter (Get-Date).AddYears(20) -FriendlyName "intermediate_dev_damienbod.com" -KeyUsageProperty All -KeyUsage CertSign, CRLSign, DigitalSignature -TextExtension @("2.5.29.19={text}CA=1&pathlength=1")

Get-ChildItem -Path cert:\localMachine\my\"The thumbprint..." | Export-PfxCertificate -FilePath C:\git\AspNetCoreCertificateAuth\Certs\intermediate_dev_damienbod.pfx -Password $mypwd

Export-Certificate -Cert cert:\localMachine\my\"The thumbprint..." -FilePath intermediate_dev_damienbod.crt

从中间证书创建子证书

可以从中间证书创建子证书。 这是最终实体，不需要创建更多的子证书。

$parentcert = ( Get-ChildItem -Path cert:\LocalMachine\My\"The thumbprint from the Intermediate certificate..." )

New-SelfSignedCertificate -certstorelocation cert:\localmachine\my -dnsname "child_a_dev_damienbod.com" -Signer $parentcert -NotAfter (Get-Date).AddYears(20) -FriendlyName "child_a_dev_damienbod.com"

$mypwd = ConvertTo-SecureString -String "1234" -Force -AsPlainText

Get-ChildItem -Path cert:\localMachine\my\"The thumbprint..." | Export-PfxCertificate -FilePath C:\git\AspNetCoreCertificateAuth\Certs\child_a_dev_damienbod.pfx -Password $mypwd

Export-Certificate -Cert cert:\localMachine\my\"The thumbprint..." -FilePath child_a_dev_damienbod.crt

从根证书创建子证书

还可以直接从根证书创建子证书。

$rootcert = ( Get-ChildItem -Path cert:\LocalMachine\My\"The thumbprint from the root cert..." )

New-SelfSignedCertificate -certstorelocation cert:\localmachine\my -dnsname "child_a_dev_damienbod.com" -Signer $rootcert -NotAfter (Get-Date).AddYears(20) -FriendlyName "child_a_dev_damienbod.com"

$mypwd = ConvertTo-SecureString -String "1234" -Force -AsPlainText

Get-ChildItem -Path cert:\localMachine\my\"The thumbprint..." | Export-PfxCertificate -FilePath C:\git\AspNetCoreCertificateAuth\Certs\child_a_dev_damienbod.pfx -Password $mypwd

Export-Certificate -Cert cert:\localMachine\my\"The thumbprint..." -FilePath child_a_dev_damienbod.crt

示例根 - 中间证书 - 证书

$mypwdroot = ConvertTo-SecureString -String "1234" -Force -AsPlainText
$mypwd = ConvertTo-SecureString -String "1234" -Force -AsPlainText

New-SelfSignedCertificate -DnsName "root_ca_dev_damienbod.com", "root_ca_dev_damienbod.com" -CertStoreLocation "cert:\LocalMachine\My" -NotAfter (Get-Date).AddYears(20) -FriendlyName "root_ca_dev_damienbod.com" -KeyUsageProperty All -KeyUsage CertSign, CRLSign, DigitalSignature

Get-ChildItem -Path cert:\localMachine\my\0C89639E4E2998A93E423F919B36D4009A0F9991 | Export-PfxCertificate -FilePath C:\git\root_ca_dev_damienbod.pfx -Password $mypwdroot

Export-Certificate -Cert cert:\localMachine\my\0C89639E4E2998A93E423F919B36D4009A0F9991 -FilePath root_ca_dev_damienbod.crt

$rootcert = ( Get-ChildItem -Path cert:\LocalMachine\My\0C89639E4E2998A93E423F919B36D4009A0F9991 )

New-SelfSignedCertificate -certstorelocation cert:\localmachine\my -dnsname "child_a_dev_damienbod.com" -Signer $rootcert -NotAfter (Get-Date).AddYears(20) -FriendlyName "child_a_dev_damienbod.com" -KeyUsageProperty All -KeyUsage CertSign, CRLSign, DigitalSignature -TextExtension @("2.5.29.19={text}CA=1&pathlength=1")

Get-ChildItem -Path cert:\localMachine\my\BA9BF91ED35538A01375EFC212A2F46104B33A44 | Export-PfxCertificate -FilePath C:\git\AspNetCoreCertificateAuth\Certs\child_a_dev_damienbod.pfx -Password $mypwd

Export-Certificate -Cert cert:\localMachine\my\BA9BF91ED35538A01375EFC212A2F46104B33A44 -FilePath child_a_dev_damienbod.crt

$parentcert = ( Get-ChildItem -Path cert:\LocalMachine\My\BA9BF91ED35538A01375EFC212A2F46104B33A44 )

New-SelfSignedCertificate -certstorelocation cert:\localmachine\my -dnsname "child_b_from_a_dev_damienbod.com" -Signer $parentcert -NotAfter (Get-Date).AddYears(20) -FriendlyName "child_b_from_a_dev_damienbod.com" 

Get-ChildItem -Path cert:\localMachine\my\141594A0AE38CBBECED7AF680F7945CD51D8F28A | Export-PfxCertificate -FilePath C:\git\AspNetCoreCertificateAuth\Certs\child_b_from_a_dev_damienbod.pfx -Password $mypwd

Export-Certificate -Cert cert:\localMachine\my\141594A0AE38CBBECED7AF680F7945CD51D8F28A -FilePath child_b_from_a_dev_damienbod.crt

使用根证书、中间证书或子证书时，可以根据需要使用指纹或公钥验证证书：

using System.Security.Cryptography.X509Certificates;

namespace CertAuthSample.Snippets;

public class SampleCertificateThumbprintsValidationService : ICertificateValidationService
{
    private readonly string[] validThumbprints = new[]
    {
        "141594A0AE38CBBECED7AF680F7945CD51D8F28A",
        "0C89639E4E2998A93E423F919B36D4009A0F9991",
        "BA9BF91ED35538A01375EFC212A2F46104B33A44"
    };

    public bool ValidateCertificate(X509Certificate2 clientCertificate)
        => validThumbprints.Contains(clientCertificate.Thumbprint);
}

证书验证缓存

ASP.NET Core 5.0 及更高版本支持启用缓存验证结果的功能。 缓存极大地提高了证书身份验证的性能，因为验证是一种高成本操作。

默认情况下，证书身份验证禁用缓存。 若要启用缓存，请调用 Program.cs 中的 AddCertificateCache：

builder.Services.AddAuthentication(
        CertificateAuthenticationDefaults.AuthenticationScheme)
    .AddCertificate()
    .AddCertificateCache(options =>
    {
        options.CacheSize = 1024;
        options.CacheEntryExpiration = TimeSpan.FromMinutes(2);
    });

默认的缓存实现将结果存储在内存中。 可以通过实现 ICertificateValidationCache 并注册“依赖项注入”来提供自己的缓存。 例如，services.AddSingleton<ICertificateValidationCache, YourCache>()。

可选客户端证书

本部分提供必须使用证书来保护应用子集的应用的相关信息。 例如，应用中的 Razor 页或控制器可能要求提供客户端证书。 这会带来挑战，因为客户端证书：

• 是 TLS 功能，而不是 HTTP 功能。
• 是按连接进行协商的，并且通常是在连接开始时，在任何 HTTP 数据可用之前进行协商。

可以通过两种方法实现可选的客户端证书：

1. 使用单独的主机名 (SNI) 和重定向。 虽然会增加配置工作，但仍建议使用这种方法，因为它适用于大多数环境和协议。
2. HTTP 请求期间重新协商。 这种方法有多项限制，不建议使用。

分离主机 (SNI)

在连接开始时，仅服务器名称指示 (SNI)† 是已知的。 可以按主机名配置客户端证书，以便某台主机需要特定证书而其他主机不会需要。

• 设置域和子域的绑定：
  • 例如，在 contoso.com 和 myClient.contoso.com 上设置绑定。 contoso.com 主机不需要客户端证书，但 myClient.contoso.com 需要。
  • 有关详细信息，请参阅。
    • ASP.NET Core 中的 Kestrel Web 服务器：
      • ListenOptions.UseHttps
      • ClientCertificateMode
    • IIS
      • 托管 IIS
      • 在 IIS 上配置安全性
    • HTTP.sys：配置 Windows Server

ASP.NET Core 5 及更高版本针对“重定向以获取可选客户端证书”添加了更方便的的支持。 有关详细信息，请参阅可选证书的示例。

• 对于需要客户端证书但没有的 Web 应用的请求：
  • 使用客户端证书保护的子域重定向到同一页面。
  • 例如，重定向到 myClient.contoso.com/requestedPage。 由于对 myClient.contoso.com/requestedPage 的请求是与 contoso.com/requestedPage 不同的主机名，因此客户端建立了不同的连接，并提供了客户端证书。
  • 有关详细信息，请参阅 ASP.NET Core 简介。

† 服务器名称指示 (SNI) 是一种 TLS 扩展，可将虚拟域作为 SSL 协商的一部分包括在内。 这实际上表示虚拟域名或主机名可用于标识网络终结点。

重新协商

TLS 重新协商是一个过程，通过该过程，客户端和服务器可以重新评估单个连接的加密要求，包括请求客户端证书（如果以前未提供）。 TLS 重新协商存在安全风险，不建议执行，因为：

• 在 HTTP/1.1 中，服务器需要先缓冲或使用正在传输的 HTTP 数据，例如 POST 请求正文，以确保连接对于重新协商是清楚明了的。 否则，重新协商可能会停止响应或失败。
• HTTP/2 和 HTTP/3 明确禁止重新协商。
• 重新协商会带来安全风险。 TLS 1.3 删除了对整个连接的重新协商，并将其替换为一个新的扩展，用于在连接开始后仅请求客户端证书。 此机制通过相同的 API 公开，并且仍受之前的缓冲和 HTTP 协议版本约束的限制。

此功能的实现和配置因服务器和框架版本而异。

IIS

IIS 会代表你管理客户端证书协商。 应用程序的一个子部分可以启用 SslRequireCert 选项来协商这些请求的客户端证书。 有关详细信息，请参阅 IIS 文档中的配置。

在重新协商之前，IIS 将自动缓冲任何请求正文数据，且不超过配置的大小限制。 超过限制的请求将被拒绝，并收到 413 响应。 此限额默认为 48KB，可通过设置 uploadReadAheadSize 进行配置。

HttpSys

HttpSys 有两个设置可控制客户端证书协商，这两个设置都应设置。 第一种是 http add sslcert clientcertnegotiation=enable/disable 下的 netsh.exe。 此标志指示是否应在连接开始时协商客户端证书，并且对于可选客户端证书，应将其设置为 disable。 有关详细信息，请参阅 netsh 文档。

另一个设置是 ClientCertificateMethod。 当设置为 AllowRenegotation 时，可以在请求期间重新协商客户端证书。

注意 在尝试重新协商之前，应用程序应缓冲或使用任何请求正文数据，否则请求可能会失去响应。

应用程序可以先检查 ClientCertificate 属性以查看证书是否可用。 如果不可用，请确保在调用 GetClientCertificateAsync 以协商证书之前已使用请求正文。 注意，如果客户端拒绝提供证书，则 GetClientCertificateAsync 可以返回 null 证书。

注意ClientCertificate 属性的行为在 .NET 6 中发生了更改。 有关详细信息，请参阅此 GitHub 问题。

Kestrel

Kestrel 使用 ClientCertificateMode 选项控制客户端证书协商。

ClientCertificateMode.DelayCertificate 是 .NET 6 或更高版本中提供的新选项。 经过相应设置后，应用可以检查 ClientCertificate 属性以查看证书是否可用。 如果不可用，请确保在调用 GetClientCertificateAsync 以协商证书之前已使用请求正文。 注意 GetClientCertificateAsync 如果客户端拒绝提供一个空证书，则可以返回该证书。

注意 在尝试重新协商之前，应用程序应缓冲或使用任何请求正文数据，否则 GetClientCertificateAsync 可能引发 InvalidOperationException: Client stream needs to be drained before renegotiation.。

如果以编程方式按 SNI 主机名配置 TLS 设置，则调用 UseHttps 重载（.NET 6 或更高版本），它采用 TlsHandshakeCallbackOptions 并通过 TlsHandshakeCallbackContext.AllowDelayedClientCertificateNegotation 控制客户端证书重新协商。

在此 GitHub 讨论问题中提供关于可选客户端证书的问题、评论和其他反馈。