OpenId Connect集成Swagger UI异常：授权框空白问题排查

我已为API添加如下认证代码，可通过Postman正常访问资源，但在Swagger UI中配置OpenId Connect认证后仅显示空白授权框，请问是否遗漏配置或操作有误？

现有代码配置 #

认证服务配置 #

services.AddAuthentication(options => {
                options.DefaultScheme = CookieAuthenticationDefaults.AuthenticationScheme;
                options.DefaultChallengeScheme = OpenIdConnectDefaults.AuthenticationScheme;
            }).AddCookie(CookieAuthenticationDefaults.AuthenticationScheme, options => {
                options.Cookie.Name = "CookiE2";
            })
            .AddOpenIdConnect(OpenIdConnectDefaults.AuthenticationScheme,options => {
                options.SignInScheme = CookieAuthenticationDefaults.AuthenticationScheme;
                options.Authority = "https://localhost:5002/";
                options.ClientId = "tapioauth";
                options.ClientSecret = "secret2";
                options.ResponseType = "code";
                options.Scope.Add("roles");
                options.Scope.Add("galleryapi.fullaccess");
                options.SaveTokens = true;
                options.ClaimActions.MapJsonKey("role","role");
            });

SwaggerGen配置 #

services.AddSwaggerGen(c =>
            {
                c.SwaggerDoc("v1", new OpenApiInfo { Title = "API", Version = "v1" });

                c.AddSecurityDefinition("Auth", new OpenApiSecurityScheme{
                    Type = SecuritySchemeType.OpenIdConnect,
                    Scheme = "openIdConnect",
                    Name = "OpenID Connect",
                    Description = "OpenID Connect Authentication",
                    OpenIdConnectUrl = new Uri("https://localhost:5002/.well-known/openid-configuration"), 
    
                });

                c.AddSecurityRequirement(new OpenApiSecurityRequirement
                {
                    {
                        new OpenApiSecurityScheme
                        {
                            Reference = new OpenApiReference
                            {
                                Type = ReferenceType.SecurityScheme,
                                Id = "Auth"
                            }
                        },
                        new List<string>()
                    }
                });
            });

SwaggerUI配置 #

app.UseSwaggerUI(c => 
                {
                    c.SwaggerEndpoint("/swagger/v1/swagger.json", "API v1");
                    //c.SwaggerEndpoint("/swagger/v2/swagger.json", "API v2");
                    c.RoutePrefix = string.Empty;
                });

问题原因及修复方案 #

1. SwaggerUI缺少OIDC客户端参数配置 #

当前SwaggerUI未配置OIDC客户端的关键参数，导致无法正确发起认证请求。更新UseSwaggerUI配置：

app.UseSwaggerUI(c => 
{
    c.SwaggerEndpoint("/swagger/v1/swagger.json", "API v1");
    c.RoutePrefix = string.Empty;
    // 添加OIDC认证所需的客户端配置
    c.OAuthClientId("tapioauth");
    c.OAuthClientSecret("secret2");
    c.OAuthAppName("API Swagger UI");
    c.OAuthUsePkce(); // 配合code流程启用PKCE，提升安全性
});

2. SecurityDefinition缺少授权流程配置 #

现有的AddSecurityDefinition未明确指定授权流程细节，Swagger无法识别认证方式。补充Flows配置：

c.AddSecurityDefinition("Auth", new OpenApiSecurityScheme{
    Type = SecuritySchemeType.OpenIdConnect,
    Scheme = "openIdConnect",
    Name = "OpenID Connect",
    Description = "OpenID Connect Authentication",
    OpenIdConnectUrl = new Uri("https://localhost:5002/.well-known/openid-configuration"),
    // 补充授权码流程的具体配置
    Flows = new OpenApiOAuthFlows
    {
        AuthorizationCode = new OpenApiOAuthFlow
        {
            AuthorizationUrl = new Uri("https://localhost:5002/connect/authorize"),
            TokenUrl = new Uri("https://localhost:5002/connect/token"),
            Scopes = new Dictionary<string, string>
            {
                { "roles", "角色权限" },
                { "galleryapi.fullaccess", "API完全访问权限" }
            }
        }
    }
});

3. 验证OIDC元数据端点可用性 #

确保https://localhost:5002/.well-known/openid-configuration可以正常访问并返回合法的OIDC元数据。如果该端点不可达，SwaggerUI无法加载认证配置，会导致授权框空白。

4. 检查中间件顺序 #

确保认证中间件在授权中间件之前执行，正确的中间件顺序如下：

app.UseHttpsRedirection();
app.UseAuthentication(); // 认证先于授权
app.UseAuthorization();
app.UseSwagger();
app.UseSwaggerUI(...);

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