如何实现Swashbuckle UI的Azure AD自动认证以保护完整页面？

核心修改步骤 #

1. 配置Swagger UI自动选择Scope并触发认证 #

在UseSwaggerUI配置中添加默认Scope，并注入自定义JavaScript实现页面加载时自动登录：

app.UseSwaggerUI(c =>
{
    c.OAuthClientId(_appSettings.ThunderClientId);
    c.OAuthUsePkce();
    c.OAuthScopeSeparator(" ");
    // 设置默认要选定的Scope
    c.OAuthDefaultScopes(new[] { "XXXX" }); // 替换为你的实际Scope
    
    // 注入自定义JS，页面加载时自动触发授权流程
    c.InjectJavascript("/swagger-ui/custom-auth.js");
});

在项目的wwwroot/swagger-ui目录下创建custom-auth.js文件，内容如下：

window.onload = function() {
    // 检查本地是否已有有效令牌
    const tokenKey = "swagger-oauth2-token";
    const storedToken = localStorage.getItem(tokenKey);
    
    if (!storedToken) {
        // 自动点击授权按钮
        const authorizeBtn = document.querySelector(".authorize-wrapper button");
        if (authorizeBtn) {
            authorizeBtn.click();
            
            // 延迟确认授权弹窗（适配UI渲染时机）
            setTimeout(() => {
                const confirmBtn = document.querySelector(".modal-actions .btn.authorize");
                if (confirmBtn) {
                    confirmBtn.click();
                }
            }, 500);
        }
    }
};

2. 保护Swagger端点，未认证用户无法访问 #

在UseSwagger和UseSwaggerUI之前添加认证中间件，并为Swagger相关端点添加授权要求：

// 确保认证、授权中间件在Swagger之前执行
app.UseAuthentication();
app.UseAuthorization();

app.UseSwagger();
app.UseSwaggerUI(...); // 你的现有Swagger UI配置

// 为Swagger端点添加授权校验
app.UseEndpoints(endpoints =>
{
    endpoints.MapSwagger()
             .RequireAuthorization(); // 访问Swagger JSON文件需认证
    
    endpoints.MapSwaggerUI()
             .RequireAuthorization(); // 访问Swagger UI页面需认证
});

3. 优化SwaggerGen安全配置（可选） #

将Implicit流替换为更安全的AuthorizationCode流，并确保全局安全要求生效：

AddSwaggerGen(c =>
{
    c.ExampleFilters();

    Dictionary<string, string> scopes = new Dictionary<string, string>
    {
        { "XXXX", "XXXX" } // 你的Scope配置
    };
    
    c.AddSecurityDefinition("oauth2", new OpenApiSecurityScheme
    {
        Type = SecuritySchemeType.OAuth2,
        Flows = new OpenApiOAuthFlows
        {
            AuthorizationCode = new OpenApiOAuthFlow
            {
                AuthorizationUrl = new Uri($"https://login.microsoftonline.com/{_appSettings.AzureActiveDirectoryTenant}/oauth2/v2.0/authorize"),
                TokenUrl = new Uri($"https://login.microsoftonline.com/{_appSettings.AzureActiveDirectoryTenant}/oauth2/v2.0/token"),
                Scopes = scopes
            }
        },
        In = ParameterLocation.Header,
        Name = "Authorization",
        BearerFormat = "JWT",
        Scheme = "bearer",
    });
    
    // 全局安全要求，所有API操作强制认证
    c.AddSecurityRequirement(new OpenApiSecurityRequirement
    {
        {
            new OpenApiSecurityScheme
            {
                Reference = new OpenApiReference { Type = ReferenceType.SecurityScheme, Id = "oauth2" }
            },
            scopes.Keys.ToList()
        }
    });
    
    c.OperationFilter<SecurityRequirementsOperationFilter>();
});

关键说明 #

• 自动登录逻辑：通过自定义JS在页面加载时检查令牌状态，无令牌则自动触发授权流程，实现页面加载即认证。
• 端点保护：通过RequireAuthorization()限制未认证用户访问Swagger UI和JSON文件，彻底阻断未授权用户查看API定义的路径。
• 流优化：AuthorizationCode流配合PKCE更符合OAuth 2.0安全规范，建议替代原Implicit流。

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