Swagger UI是否支持客户端证书认证？求ASP.NET Core 5+Swashbuckle示例

Swagger UI本身支持客户端证书认证，但需要结合ASP.NET Core的证书认证中间件配置，以及Swashbuckle的自定义设置来实现完整流程。以下是基于ASP.NET Core 5和Swashbuckle的具体配置步骤：

1. 配置ASP.NET Core客户端证书认证 #

在Startup.cs中先启用证书认证服务，并添加Swagger相关配置：

ConfigureServices 方法 #

using Microsoft.AspNetCore.Authentication.Certificate;
using Microsoft.OpenApi.Models;

public void ConfigureServices(IServiceCollection services)
{
    // 注册客户端证书认证服务
    services.AddAuthentication(CertificateAuthenticationDefaults.AuthenticationScheme)
        .AddCertificate(options =>
        {
            options.AllowedCertificateTypes = CertificateTypes.All;
            // 自定义证书验证逻辑，可根据实际需求调整
            options.Events = new CertificateAuthenticationEvents
            {
                OnCertificateValidated = context =>
                {
                    var cert = context.ClientCertificate;
                    // 示例：验证证书颁发者是否为信任的机构
                    if (cert.Issuer.Contains("CN=YourTrustedCA"))
                    {
                        context.Success();
                    }
                    else
                    {
                        context.Fail("证书颁发者未被信任");
                    }
                    return Task.CompletedTask;
                }
            };
        });

    // 配置Swagger生成器
    services.AddSwaggerGen(c =>
    {
        c.SwaggerDoc("v1", new OpenApiInfo { Title = "Cert-Auth API", Version = "v1" });
        
        // 定义客户端证书安全方案
        c.AddSecurityDefinition("ClientCertificate", new OpenApiSecurityScheme
        {
            Type = SecuritySchemeType.ApiKey,
            Name = "X-Client-Certificate",
            In = ParameterLocation.Header,
            Description = "客户端证书（浏览器会自动弹出选择框，或通过请求头传递证书内容）"
        });
        
        // 为所有接口添加证书认证要求
        c.AddSecurityRequirement(new OpenApiSecurityRequirement
        {
            {
                new OpenApiSecurityScheme
                {
                    Reference = new OpenApiReference
                    {
                        Type = ReferenceType.SecurityScheme,
                        Id = "ClientCertificate"
                    }
                },
                Array.Empty<string>()
            }
        });
    });

    services.AddControllers();
}

Configure 方法 #

public void Configure(IApplicationBuilder app, IWebHostEnvironment env)
{
    if (env.IsDevelopment())
    {
        app.UseDeveloperExceptionPage();
        app.UseSwagger();
        app.UseSwaggerUI(c =>
        {
            c.SwaggerEndpoint("/swagger/v1/swagger.json", "Cert-Auth API v1");
            // 启用Swagger UI的客户端证书支持，触发浏览器证书选择弹窗
            c.ConfigObject.AdditionalItems.Add("clientCertificate", true);
        });
    }

    app.UseHttpsRedirection();

    app.UseRouting();

    // 启用认证和授权中间件（顺序不能错）
    app.UseAuthentication();
    app.UseAuthorization();

    app.UseEndpoints(endpoints =>
    {
        endpoints.MapControllers();
    });
}

2. 关键注意事项 #

• 确保应用以HTTPS模式运行，客户端证书认证依赖HTTPS环境
• 浏览器访问Swagger UI时，会自动弹出证书选择对话框，选择已安装的客户端证书即可发起认证请求
• 若使用Postman等测试工具，需在工具的请求设置中手动配置客户端证书（通常在"Settings" > "Certificates"中添加）

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