如何在ASP.NET Core MVC中配置itfoxtec-identity-saml2的SAML2认证参数？

第一步：安装依赖包 #

先安装官方提供的SAML2 MVC Core包：

dotnet add package ITfoxtec.Identity.Saml2.MvcCore

第二步：在appsettings.json中配置核心参数 #

将SAML2相关配置添加到appsettings.json，替换为你的IDP实际参数：

"Saml2Settings": {
  "Issuer": "你的SP实体ID（例如https://your-app-domain.com）",
  "AssertionConsumerServiceUrl": "https://your-app-domain.com/Saml2/Acs", // ACS回调地址
  "SignatureAlgorithm": "http://www.w3.org/2001/04/xmldsig-more#rsa-sha256",
  "Idp": {
    "EntityId": "IDP提供的实体ID",
    "SingleSignOnServiceUrl": "IDP的单点登录Endpoint地址", // IDP SSO接口地址
    "SingleLogoutServiceUrl": "IDP的单点注销Endpoint地址（可选）",
    "SigningCertificate": "IDP证书的Base64字符串或本地证书文件路径"
  },
  "AuthenticationLevel": "urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport" // 认证等级标识
}

第三步：在Program.cs中配置认证服务（.NET 6+） #

如果是.NET 5及更早版本，对应在Startup.cs的ConfigureServices方法中配置：

var saml2Settings = configuration.GetSection("Saml2Settings").Get<Saml2Settings>();
// 加载本地证书文件（如果配置的是文件路径）
if (!string.IsNullOrEmpty(saml2Settings.Idp.SigningCertificate) && System.IO.File.Exists(saml2Settings.Idp.SigningCertificate))
{
    saml2Settings.Idp.SigningCertificate = System.IO.File.ReadAllText(saml2Settings.Idp.SigningCertificate);
}

builder.Services.AddAuthentication(options =>
{
    options.DefaultScheme = CookieAuthenticationDefaults.AuthenticationScheme;
    options.DefaultChallengeScheme = Saml2Defaults.Scheme;
})
.AddCookie()
.AddSaml2(options =>
{
    options.SignInScheme = CookieAuthenticationDefaults.AuthenticationScheme;
    options.Saml2Settings = saml2Settings;
    // 绑定认证等级到SAML请求
    options.Events = new Saml2Events
    {
        OnRedirectToIdentityProvider = async context =>
        {
            context.Saml2AuthnRequest.AuthnContextClassRef = new Uri(saml2Settings.AuthenticationLevel);
            await Task.CompletedTask;
        }
    };
});

注意：必须在app.UseAuthentication();之后添加app.UseAuthorization();启用授权中间件。

关键参数配置详解 #

1. Assertion Consumer URL（ACS URL） #

• 这是SP接收IDP认证响应的回调地址，必须和IDP后台配置的地址完全一致（包括HTTP/HTTPS协议）。
• 需要在MVC控制器中实现对应的Action处理响应：

public class Saml2Controller : Controller
{
    private readonly Saml2Configuration _saml2Config;

    public Saml2Controller(IOptions<Saml2Settings> saml2Settings)
    {
        _saml2Config = saml2Settings.Value.ToSaml2Configuration();
    }

    [HttpPost]
    public async Task<IActionResult> Acs()
    {
        var saml2AuthnResponse = new Saml2AuthnResponse(_saml2Config);
        await saml2AuthnResponse.ReadSamlResponseAsync(Request.Form["SAMLResponse"]);

        if (saml2AuthnResponse.Status != Saml2StatusCodes.Success)
        {
            throw new Exception($"SAML认证失败: {saml2AuthnResponse.StatusMessage}");
        }

        // 创建用户身份凭证
        var claimsIdentity = new ClaimsIdentity(saml2AuthnResponse.Claims, Saml2Defaults.Scheme);
        await HttpContext.SignInAsync(CookieAuthenticationDefaults.AuthenticationScheme, new ClaimsPrincipal(claimsIdentity));

        // 跳转到认证前的页面或主页
        return Redirect(saml2AuthnResponse.RelayState ?? "/");
    }
}

2. IDP Endpoint #

• 即IDP提供的单点登录请求接收地址，配置在Idp.SingleSignOnServiceUrl，用户触发登录时，SP会将SAML请求转发到该地址。
• 添加Login Action触发跳转：

public IActionResult Login(string returnUrl = "/")
{
    var saml2AuthnRequest = new Saml2AuthnRequest(_saml2Config);
    saml2AuthnRequest.RelayState = returnUrl;
    return Redirect(saml2AuthnRequest.CreateRedirectUrl());
}

3. Authentication Level（认证等级） #

• 对应SAML协议的AuthnContextClassRef字段，用于指定IDP需要使用的认证方式（如密码、双因素等）。
• 可在配置文件预设，也可在OnRedirectToIdentityProvider事件中动态调整。常用值：
  • urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport：密码+HTTPS认证
  • urn:oasis:names:tc:SAML:2.0:ac:classes:TimeSyncToken：双因素认证

4. IDP证书配置 #

• IDP提供的证书用于验证SAML响应的签名合法性，防止篡改。
• 两种配置方式：
  1. Base64字符串：将证书导出为Base64编码字符串，直接填入配置项。
  2. 本地文件：将证书文件（.cer/.crt）放在项目目录，填入文件路径，再通过代码读取内容（示例已包含）。

验证步骤 #

1. 确认IDP后台配置的ACS URL与SP的AssertionConsumerServiceUrl完全匹配。
2. 启动项目，访问/Saml2/Login，测试是否能正常跳转到IDP登录页，完成认证后是否能回调并生成用户会话。

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