.NET 4.8项目集成Swagger并配置Entra ID(Azure AD)认证异常

基于.NET 4.8搭建的默认ASP.NET MVC API项目，已集成Entra ID（Azure AD）认证，当前可通过Postman正常发送授权请求调用API。安装Swashbuckle及Swashbuckle.Core 5.6.0包后，配置Swagger的OAuth2认证时，"Authorize"按钮始终不显示——即使调整Flow和TokenUrl后Swagger文档结构与正常.NET Core项目一致，按钮仍未出现。

现有配置详情：

Entra ID认证配置（Startup.cs） #

public void ConfigureAuth(IAppBuilder app)
{
    OwinTokenAcquirerFactory factory = TokenAcquirerFactory.GetDefaultInstance<OwinTokenAcquirerFactory>();
    app.AddMicrosoftIdentityWebApi(factory);
    factory.Build();
}

appsettings.json配置 #

{
  "AzureAd": {
    "Instance": "https://login.microsoftonline.com/",
    "ClientId": "id of application",
    "Audience": "api://.....",
    "TenantId": "id of tenant"
  }
}

当前SwaggerConfig配置 #

c.OAuth2("oauth2")
    .Description("OAuth2 Implicit Grant")
    .Flow("implicit")
    .AuthorizationUrl("http://myazureurl/api/oauth/dialog")
    //.TokenUrl("https://tempuri.org/token")
    .Scopes(scopes =>
    {
        scopes.Add("read", "Read access to protected resources");
        scopes.Add("write", "Write access to protected resources");
    });

c.EnableOAuth2Support(
    clientId: "myclientid",
    clientSecret: null,
    realm: "myrealm",
    appName: "Swagger UI"
);

1. 修正OAuth2端点参数 #

Swashbuckle 5.6得用Entra ID官方的OAuth2端点，不能用自定义URL：

• AuthorizationUrl：https://login.microsoftonline.com/{你的TenantId}/oauth2/v2.0/authorize
• TokenUrl：https://login.microsoftonline.com/{你的TenantId}/oauth2/v2.0/token

推荐用授权码流程（Authorization Code Flow）+ PKCE，比隐式流更安全，适配Entra ID的最佳实践。

2. 完整调整SwaggerConfig配置 #

替换原有OAuth2配置代码为以下内容，记得把占位符换成你的Entra ID实际信息：

// 定义OAuth2安全方案
c.AddSecurityDefinition("oauth2", new OAuth2Scheme
{
    Type = "oauth2",
    Flow = "authorizationCode",
    AuthorizationUrl = "https://login.microsoftonline.com/{你的TenantId}/oauth2/v2.0/authorize",
    TokenUrl = "https://login.microsoftonline.com/{你的TenantId}/oauth2/v2.0/token",
    Scopes = new Dictionary<string, string>
    {
        { "api://{你的API ClientId}/access_as_user", "以用户身份访问API" } // 替换为你的API实际作用域
    }
});

// 为所有API操作添加安全要求——这是Authorize按钮显示的关键！
c.AddSecurityRequirement(new Dictionary<string, IEnumerable<string>>
{
    { "oauth2", new[] { "api://{你的API ClientId}/access_as_user" } }
});

// 启用Swagger UI的OAuth2支持，配置客户端信息
c.EnableOAuth2Support(
    clientId: "{你的Swagger应用注册ClientId}", // 得在Entra ID单独注册Swagger应用
    clientSecret: null, // PKCE流程不需要客户端密钥
    realm: "",
    appName: "Swagger UI",
    additionalQueryStringParams: new Dictionary<string, string>
    {
        { "response_type", "code" },
        { "code_challenge_method", "S256" } // 开启PKCE
    }
);

3. 不可忽略的Entra ID配置细节 #

• 注册Swagger专用应用：在Entra ID里新建一个应用注册，用于Swagger UI的身份验证，然后在该应用的「API权限」中添加你的API权限，并设置为「已授予管理员同意」。
• 配置重定向URI：在Swagger应用的「身份验证」中添加重定向地址：https://localhost:{你的项目端口}/swagger/ui/o2c-html（本地调试用，生产环境换成对应域名）。
• 作用域完全匹配：Swagger配置里的作用域必须和你API在Entra ID中定义的作用域完全一致，比如api://xxx/access_as_user，不能随便写。

4. 验证效果 #

启动项目后打开Swagger页面，右上角应该能看到"Authorize"按钮。点击按钮选择对应作用域，会跳转到Entra ID登录页，登录成功后就能携带令牌调用需要授权的API接口了。

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