添加Basic认证后Swagger UI弹窗反复出现问题排查

你的Swagger Basic认证弹窗反复出现，通常是由于凭证验证失败或路径匹配逻辑未覆盖所有Swagger相关请求导致的，以下是具体问题和修复步骤：

1. 核心问题：未注册Swagger凭证配置 #

你的SwaggerBasicAuthMiddleware依赖IOptions<List<SwaggerCredential>>获取凭证，但如果未在服务容器中注册该配置，credentials.Value会是空列表，导致每次验证都无法匹配用户，始终返回401，触发弹窗反复出现。

修复步骤： #

• 在appsettings.json中添加凭证配置：

"SwaggerCredentials": [
  {
    "Username": "your-swagger-user",
    "Password": "your-swagger-pass"
  }
]

• 在ConfigureServices方法中注册配置：

services.Configure<List<SwaggerCredential>>(Configuration.GetSection("SwaggerCredentials"));

• 确保SwaggerCredential类定义正确：

public class SwaggerCredential
{
    public string Username { get; set; }
    public string Password { get; set; }
}

2. 路径匹配逻辑不兼容生产环境子路径 #

生产环境中你的应用部署在/myapp子路径下，若未设置PathBase，context.Request.Path会包含/myapp前缀，导致原逻辑中StartsWithSegments("/swagger")无法匹配/myapp/swagger/v1/swagger.json请求，该请求会被OIDC认证拦截，而非Basic认证中间件处理。

修复步骤： #

方案A：设置PathBase（推荐）

在Configure方法开头添加生产环境的PathBase配置：

if (!env.IsDevelopment())
{
    app.UsePathBase("/myapp");
}

方案B：修改路径匹配逻辑

替换中间件中的路径判断逻辑，兼容子路径：

// 原判断逻辑
// if (context.Request.Path.StartsWithSegments("/swagger") || context.Request.Path.Value.ToLower().Contains("index.html"))

// 修改后
var requestPath = context.Request.Path.Value.ToLower();
if (requestPath.Contains("/swagger") || requestPath.Contains("index.html"))

3. 中间件顺序错误 #

确保Swagger Basic认证中间件优先于OIDC认证中间件执行，否则Swagger相关请求会先被OIDC拦截，Basic认证无法生效。

正确的中间件顺序示例： #

// 1. 启用Swagger Basic认证中间件
app.UseSwaggerAuthorized();
// 2. 启用OIDC认证
app.UseAuthentication();
app.UseAuthorization();
// 3. 启用Swagger相关中间件
app.UseSwagger();
app.UseSwaggerUI(c => { ... });

4. 凭证验证逻辑的优化建议 #

• 避免使用SingleOrDefault：如果存在多个凭证，SingleOrDefault会抛出异常，改用FirstOrDefault更安全；
• 生产环境禁止明文存储密码：改用哈希算法存储密码，验证时对比哈希值。

修改后的验证逻辑示例：

var current = credentials.Value.FirstOrDefault(x => 
    x.Username.Equals(username, StringComparison.OrdinalIgnoreCase));
// 生产环境替换为哈希对比逻辑
if (current != null && current.Password.Equals(password))
{
    await next(context);
    return;
}

内容的提问来源于stack exchange，提问作者Ivan-Mark Debono