Sustainsys.Saml2集成Azure IDP时Saml2/Acs路由返回404问题

安全阿岳

2026-7-31

解决Sustainsys.Saml2与自定义Acs路由冲突导致的404问题

问题根源

Sustainsys.Saml2库会自动注册/Saml2/Acs作为SAML回调端点，这个端点由库的中间件负责处理，而且仅接受符合SAML规范的POST请求（携带SAMLResponse参数）。你手动用GET访问或者Postman发非SAML格式的请求时，库的中间件不会处理，直接返回404；同时你自己写的同名控制器路由会被库的中间件覆盖，根本不会生效。

解决办法

方案1：改用库原生Acs端点，在登录成功后转发到Vue客户端

这是最省心的方案，不用自己处理复杂的SAML响应验证逻辑：

删掉自定义控制器中/Saml2/Acs的路由，保留登录发起的逻辑即可。
配置库的Saml2Events，在认证完成后将用户信息或令牌传递给Vue客户端：

services.AddSaml2(options =>
{
    // 保留你的Azure IDP配置、SP EntityId等原有配置
    options.SPOptions.AssertionConsumerServices.Add(
        new ServiceLocation("urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST", 
        new Uri("https://sp.example.com/Saml2/Acs")));
})
.AddSaml2Events(events =>
{
    events.OnAuthenticated = async context =>
    {
        // 从context中获取SAML响应或用户身份信息
        var userPrincipal = context.Principal;

        // 生成Vue客户端需要的令牌（比如JWT）或组装参数
        var clientToken = GenerateYourClientToken(userPrincipal);

        // 重定向到Vue的回调页面，携带参数
        context.Response.Redirect($"https://your-vue-domain.com/auth-callback?token={clientToken}");
        await Task.CompletedTask;
    };
});

测试时不要手动GET访问/Saml2/Acs，正常走登录流程：Vue跳转到SP的登录发起路由，SP重定向到Azure IDP，登录完成后Azure会自动POST到/Saml2/Acs，库处理后会跳转到你的Vue页面。

方案2：修改库的端点前缀，释放自定义路由

如果必须用自己的Acs控制器处理回调：

修改Sustainsys.Saml2的模块路径，让库的端点前缀和你的自定义路由不冲突：

services.AddSaml2(options =>
{
    // 将库的端点前缀改为/Saml2Library，这样库的Acs路径变为/Saml2Library/Acs
    options.SPOptions.ModulePath = "/Saml2Library";
    // 同步更新配置中的AssertionConsumerServiceUrl为新的库端点地址
    options.SPOptions.AssertionConsumerServices.Add(
        new ServiceLocation("urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST", 
        new Uri("https://sp.example.com/Saml2Library/Acs")));
})

保留你自定义的Saml2Controller中的/Saml2/Acs路由，此时这个路由不会被库占用，手动访问或Postman请求就能走到你的控制器逻辑。
注意：自定义Acs控制器需要自行实现SAML响应的验证（签名、断言解析等），这部分逻辑复杂，建议优先用方案1。

方案3：调整自定义控制器的路由

直接把自定义Acs的路由改成其他名称，比如/Saml2/CustomAcs，然后更新配置文件中的AssertionConsumerServiceUrl为https://sp.example.com/Saml2/CustomAcs，这样库不会占用这个新路由，你的控制器可以正常处理回调。同样需要自行处理SAML响应验证。

关键注意点

Sustainsys.Saml2的原生/Saml2/Acs只接受POST请求且必须携带合法的SAMLResponse参数，手动GET访问必然返回404，这是正常行为，不是BUG。
路由冲突的核心是库的中间件优先级高于MVC控制器，会先匹配并处理/Saml2/Acs路径的请求。

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