.NET 8 Web API集成Azure AD+Swagger认证异常问题排查

问题分析 #

迁移至.NET 8后出现两个核心问题：

1. Swagger认证弹窗client_id为空、scope显示异常
2. 手动输入client_id完成认证后，API调用返回Bearer error="invalid_token",error_description="The signature is invalid"

这些问题源于.NET 8对身份认证中间件的调整，以及Swashbuckle配置细节的变化。

解决方案 #

1. 修正Swagger OAuth2配置 #

问题根源：旧配置未显式指定ClientId，且使用了已不推荐的Implicit流，导致Swagger UI无法自动填充参数。

修改后的Swagger配置代码：

builder.Services.AddSwaggerGen(options =>
{
    options.CustomSchemaIds(type => type.FullName);
    options.DescribeAllParametersInCamelCase();

    var xmlFile = $"{Assembly.GetExecutingAssembly().GetName().Name}.xml";
    var xmlPath = Path.Combine(AppContext.BaseDirectory, xmlFile);
    options.IncludeXmlComments(xmlPath);
    options.OperationFilter<AppendAuthorizeToSummaryOperationFilter>();

    // 统一读取AzureAD配置
    var azureAdSection = builder.Configuration.GetSection("AzureAd");
    var clientId = azureAdSection["ClientId"];
    var scope = azureAdSection["Scopes"];
    var authorizationUrl = $"{azureAdSection["Instance"]}{azureAdSection["TenantId"]}/oauth2/v2.0/authorize";
    var tokenUrl = $"{azureAdSection["Instance"]}{azureAdSection["TenantId"]}/oauth2/v2.0/token";

    options.AddSecurityDefinition("oauth2", new OpenApiSecurityScheme
    {
        Type = SecuritySchemeType.OAuth2,
        Description = "通过Azure AD OAuth2认证访问API",
        Flows = new OpenApiOAuthFlows
        {
            // 替换为推荐的AuthorizationCode流
            AuthorizationCode = new OpenApiOAuthFlow
            {
                AuthorizationUrl = new Uri(authorizationUrl),
                TokenUrl = new Uri(tokenUrl),
                ClientId = clientId, // 显式指定ClientId，解决自动填充问题
                Scopes = new Dictionary<string, string>
                {
                    { scope, "默认API访问权限" }
                }
            }
        }
    });

    options.AddSecurityRequirement(new OpenApiSecurityRequirement
    {
        {
            new OpenApiSecurityScheme
            {
                Reference = new OpenApiReference
                {
                    Type = ReferenceType.SecurityScheme,
                    Id = "oauth2"
                }
            },
            new[] { scope } // 与配置中的scope保持一致，避免权限不匹配
        }
    });
});

2. 简化并修正AAD认证配置 #

问题根源：重复绑定配置、多余的OpenIdConnect配置干扰JwtBearer参数，且Authority未指定v2.0版本导致Issuer验证失败。

修改后的认证配置代码：

builder.Services.AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
    .AddMicrosoftIdentityWebApi(options =>
    {
        builder.Configuration.Bind("AzureAd", options);
        options.TokenValidationParameters.NameClaimType = "name";
        // 显式加载TokenValidation参数，确保与配置一致
        options.TokenValidationParameters.ValidIssuers = builder.Configuration
            .GetSection("AzureAd:TokenValidationParameters:ValidIssuers")
            .Get<string[]>();
        options.TokenValidationParameters.ValidAudiences = builder.Configuration
            .GetSection("AzureAd:TokenValidationParameters:ValidAudiences")
            .Get<string[]>();
        options.TokenValidationParameters.ClockSkew = TimeSpan.Zero;
    });

// 移除不必要的OpenIdConnect配置（Web API无需OpenIdConnect中间件）
// builder.Services.Configure<OpenIdConnectOptions>(...) 这部分代码可以删除

3. 更新appsettings.json的Authority配置 #

确保Authority包含v2.0后缀，与ValidIssuers保持一致：

"AzureAd": {
    "Authority": "https://login.microsoftonline.com/b4e49ba2-xxx/v2.0", // 添加/v2.0
    // 其他配置保持不变
}

关键说明 #

• 替换Implicit流为AuthorizationCode流：Implicit流在现代OAuth实践中已被弃用，AuthorizationCode流更安全，且Swagger UI支持更完善
• 显式指定ClientId：.NET 8对应的Swashbuckle版本不再自动读取配置中的ClientId，需手动设置
• 移除多余的OpenIdConnect配置：Web API仅需JwtBearer中间件处理token验证，OpenIdConnect配置属于MVC应用的登录流程，会干扰API的认证逻辑

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