如何在ASP.NET应用中使用微软官方包实现Okta SSO SAML2集成

你提到的Microsoft.IdentityModel.Tokens.Saml是微软官方SAML2能力的核心依赖包，实际ASP.NET应用开发时可配套使用官方的认证中间件（底层直接依赖该包）完成完整SSO流程，以下是可直接复用的实现示例：

1. 前置操作 #

• 首先安装所需NuGet包：

  Install-Package Microsoft.AspNetCore.Authentication.Saml2
  Install-Package Microsoft.IdentityModel.Tokens.Saml
  

• 提前从Okta后台获取以下配置信息：
  • Okta SAML 实体ID（Issuer）
  • Okta 单点登录服务URL
  • Okta 签名证书公钥（CER或PEM格式）
  • 自行确认应用的断言消费服务URL（ACS URL，即Okta登录后回调的地址，默认格式为https://你的应用域名/Saml2/Acs，需和Okta后台配置完全一致）

2. 服务配置（.NET 6+ Program.cs示例） #

替换以下代码中的占位符为你的实际配置即可：

var builder = WebApplication.CreateBuilder(args);

builder.Services.AddControllersWithViews();

// 配置身份认证服务
builder.Services.AddAuthentication(options =>
{
    options.DefaultScheme = "Cookies";
    options.DefaultChallengeScheme = "Saml2";
})
.AddCookie("Cookies", options =>
{
    options.LoginPath = "/Account/Login";
    options.AccessDeniedPath = "/Account/AccessDenied";
})
.AddSaml2("Saml2", options =>
{
    // 服务提供商（你的应用）实体ID，需和Okta后台配置一致
    options.EntityId = "https://你的应用域名/自定义SP实体ID";
    
    // Okta身份提供商配置
    options.IdentityProviderEntityId = "Okta后台提供的Issuer地址";
    options.SingleSignOnServiceUrl = new Uri("Okta后台提供的SSO服务地址");
    // 如需单点登出可补充配置
    // options.SingleLogoutServiceUrl = new Uri("Okta后台提供的SLO服务地址");
    
    // 配置Okta签名证书，用于验证SAML断言合法性
    var oktaSigningCert = new X509Certificate2("你的Okta公钥证书存储路径.cer");
    options.TokenValidationParameters = new TokenValidationParameters
    {
        ValidateIssuer = true,
        ValidIssuer = "Okta后台提供的Issuer地址",
        ValidateAudience = true,
        ValidAudience = "https://你的应用域名/自定义SP实体ID",
        ValidateLifetime = true,
        IssuerSigningKey = new X509SecurityKey(oktaSigningCert)
    };
    
    // SAML断言验证通过后的回调，可自定义声明映射逻辑
    options.Events.OnTokenValidated = context =>
    {
        var userClaims = context.Principal.Claims;
        // 示例：获取用户邮箱、姓名等属性
        var userEmail = userClaims.FirstOrDefault(c => c.Type == ClaimTypes.Email)?.Value;
        var userName = userClaims.FirstOrDefault(c => c.Type == ClaimTypes.Name)?.Value;
        // 可在此处补充本地用户查询、自定义声明添加等业务逻辑
        return Task.CompletedTask;
    };
});

var app = builder.Build();

if (!app.Environment.IsDevelopment())
{
    app.UseExceptionHandler("/Home/Error");
    app.UseHsts();
}

app.UseHttpsRedirection();
app.UseStaticFiles();
app.UseRouting();

// 中间件顺序不可调换：先认证再授权
app.UseAuthentication();
app.UseAuthorization();

app.MapControllerRoute(
    name: "default",
    pattern: "{controller=Home}/{action=Index}/{id?}");

app.Run();

3. 登录触发逻辑示例 #

在Account控制器中添加对应动作即可触发SAML认证流程：

public class AccountController : Controller
{
    public IActionResult Login()
    {
        if (!User.Identity.IsAuthenticated)
        {
            // 触发SAML挑战，自动跳转到Okta登录页
            return Challenge("Saml2");
        }
        return RedirectToAction("Index", "Home");
    }

    public IActionResult Logout()
    {
        // 同时清除本地Cookie和Okta会话
        return SignOut("Cookies", "Saml2");
    }

    public IActionResult AccessDenied()
    {
        return View();
    }
}

4. 注意事项 #

• 所有涉及的地址（SP实体ID、ACS URL、Okta issuer地址等）必须和Okta后台配置完全一致，大小写也要匹配，否则会出现验签失败的问题
• 生产环境不要将证书明文存放在程序目录，建议使用操作系统证书存储或云密钥管理服务存放
• 如果你使用的是.NET Framework版本的ASP.NET应用，对应官方包为Microsoft.Owin.Security.Saml，配置逻辑类似，放在Startup.Auth.cs文件中即可

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