.NET Core中Google Workspace SAML令牌SSO认证实现求助

前置配置（Google Workspace 端） #

• 登录 Google Admin 控制台，进入「应用」→「Web 和移动应用」，创建自定义 SAML 应用
• 填写应用名称后，下载 Google 的 IdP 元数据 XML 文件（后续会用到）
• 配置服务提供商（SP）信息：
  • 实体 ID：你的应用唯一标识（比如 https://your-app-domain.com/saml/metadata）
  • ACS URL：应用接收 SAML 断言的回调地址（比如 https://your-app-domain.com/saml/acs）
  • 名称 ID 格式：选择 EMAIL，确保用用户邮箱作为唯一标识

.NET Core 项目实现步骤 #

1. 安装依赖包 #

使用 NuGet 安装 ITfoxtec.Identity.Saml2.MvcCore，这是.NET生态中成熟的SAML2实现库：

Install-Package ITfoxtec.Identity.Saml2.MvcCore

2. 配置 SAML 认证服务 #

在 Program.cs 中添加 SAML 认证配置：

using ITfoxtec.Identity.Saml2;
using ITfoxtec.Identity.Saml2.MvcCore.Configuration;
using ITfoxtec.Identity.Saml2.Schemas;
using Microsoft.AspNetCore.Authentication.Cookies;

var builder = WebApplication.CreateBuilder(args);

// 绑定SAML配置项
builder.Services.Configure<Saml2Configuration>(builder.Configuration.GetSection("Saml2"));
builder.Services.AddSaml2();

// 配置认证体系
builder.Services.AddAuthentication(options =>
{
    options.DefaultScheme = CookieAuthenticationDefaults.AuthenticationScheme;
    options.DefaultChallengeScheme = Saml2Defaults.Scheme;
})
.AddCookie()
.AddSaml2(options =>
{
    var saml2Config = builder.Configuration.GetSection("Saml2").Get<Saml2Configuration>();
    // 加载Google IdP元数据，可替换为本地文件路径或Google提供的元数据URL
    saml2Config.LoadIdPMetadata(new Uri("https://accounts.google.com/o/saml2/idp?idpid=xxxxxx"));
    options.SignInScheme = CookieAuthenticationDefaults.AuthenticationScheme;
    options.Saml2Configuration = saml2Config;
});

// 其他服务配置...

var app = builder.Build();

app.UseAuthentication();
app.UseAuthorization();

// 注册SAML端点
app.UseSaml2();

// 路由配置...
app.Run();

3. 配置文件（appsettings.json） #

添加SAML相关配置：

"Saml2": {
  "Issuer": "https://your-app-domain.com/saml/metadata", // 对应Google端配置的实体ID
  "SignatureAlgorithm": "http://www.w3.org/2001/04/xmldsig-more#rsa-sha256",
  "CertificateValidationMode": "ChainTrust",
  "RevocationMode": "NoCheck",
  "AllowedAudienceUris": [ "https://your-app-domain.com/saml/metadata" ],
  "NameIdFormat": "urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress"
}

4. 处理认证回调与用户信息 #

在控制器中添加登录触发和ACS回调处理：

using ITfoxtec.Identity.Saml2.MvcCore;
using System.Security.Claims;

public class AccountController : Controller
{
    public IActionResult Login()
    {
        // 触发SAML认证流程
        return Challenge(new AuthenticationProperties { RedirectUri = "/" }, Saml2Defaults.Scheme);
    }

    [HttpPost]
    [Route("saml/acs")]
    public async Task<IActionResult> AssertionConsumerService()
    {
        var binding = new Saml2PostBinding();
        var saml2AuthnResponse = new Saml2AuthnResponse(await HttpContext.GetSaml2ConfigurationAsync());

        try
        {
            binding.ReadSamlResponse(Request.ToGenericHttpRequest(), saml2AuthnResponse);
            if (saml2AuthnResponse.Status != Saml2StatusCodes.Success)
            {
                throw new Exception($"SAML认证失败，状态码：{saml2AuthnResponse.Status}");
            }

            // 创建用户会话，可自定义Claims处理
            await saml2AuthnResponse.CreateSessionAsync(HttpContext, claimsTransform: principal =>
            {
                var email = principal.Claims.First(c => c.Type == ClaimTypes.Email).Value;
                // 可添加自定义Claims到用户身份
                principal.Identities.First().AddClaim(new Claim("CustomClaim", "CustomValue"));
                return principal;
            });

            return Redirect("/");
        }
        catch (Exception ex)
        {
            // 处理认证失败逻辑
            return BadRequest($"认证出错：{ex.Message}");
        }
    }
}

常见问题排查 #

• 证书验证失败：确保Google提供的IdP证书已正确加载，可从元数据中提取公钥，手动添加到SAML配置的IdPSigningCertificates集合
• 断言签名不匹配：检查SignatureAlgorithm配置是否与Google端一致（Google默认使用SHA256）
• ACS URL不匹配：确保Google端配置的ACS URL与应用实际回调地址完全一致（包括HTTP/HTTPS、路径）
• Name ID格式错误：确认Google端选择的Name ID格式与应用配置的NameIdFormat一致

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