.NET/ASP.NET Core Integration Guide
Integrate Hawiyati SAML2 SP SDK with .NET 8 ASP.NET Core applications. Covers NuGet package, middleware wiring, minimum configuration, route protection, ACS handling, logout, and SP registration.
dotnet test before merging to production.
1. Prerequisites
| Requirement | Minimum version |
|---|---|
| .NET | 8.0 |
| ASP.NET Core | 8.0 |
| Hawiyati IdP | 2.0 |
| Network access | SP → IdP on port 443 |
The ASP.NET Core Data Protection API is required for the correlation cookie. Add builder.Services.AddDataProtection() before registering authentication.
2. Add the dependency
dotnet add package Hawiyati.Saml.Sp.AspNetCore --version 1.0.0
dotnet add package Hawiyati.Saml.Sp --version 1.0.0
3. Minimum configuration
Add the SAML section to appsettings.json. Do not store the IdP certificate inline. Reference it by file path only.
{
"Saml": {
"SpEntityId": "https://app.example.com/saml/metadata",
"AcsUrl": "https://app.example.com/saml/acs",
"IdpEntityId": "https://idp.hawiyati.org",
"IdpSsoUrl": "https://idp.hawiyati.org/saml2/sso/redirect",
"IdpSigningCertPath": "/etc/saml/idp-signing.pem"
}
}
Wire the SDK in Program.cs:
var cfg = builder.Configuration.GetSection("Saml");
var idpCert = new X509Certificate2(cfg["IdpSigningCertPath"]!);
var trustedIdp = TrustedIdp.Create()
.WithEntityId(cfg["IdpEntityId"]!)
.WithSsoUrl(cfg["IdpSsoUrl"]!)
.WithSigningKey(idpCert)
.Build();
var samlConfig = SamlSpConfig.Create()
.WithEntityId(cfg["SpEntityId"]!)
.WithAcsUrl(cfg["AcsUrl"]!)
.WithTrustedIdp(trustedIdp)
.WithPendingRequestStore(new InMemoryPendingRequestStore())
.WithReplayStore(new InMemoryReplayStore())
.Build();
builder.Services.AddDataProtection();
builder.Services
.AddAuthentication("saml")
.AddSamlAuthentication("saml", opts => { opts.Config = samlConfig; });
builder.Services.AddAuthorization();
4. Protect a route
Middleware order is mandatory:
app.UseHttpsRedirection();
app.UseSamlAcs("saml"); // Must come before UseAuthentication
app.UseAuthentication();
app.UseAuthorization();
app.MapGet("/protected", [Authorize] (HttpContext ctx) =>
{
var nameId = ctx.User.FindFirst(ClaimTypes.NameIdentifier)?.Value ?? "unknown";
return Results.Content($"<p>Authenticated as: {nameId}</p>", "text/html");
});
5. Handle the ACS callback
UseSamlAcs("saml") intercepts POST requests to the ACS path and handles them automatically. The middleware validates the SAML response, calls ILocalAccountResolver.ResolveAsync() if configured, calls HttpContext.SignInAsync("saml", principal), and redirects to the original target URL.
6. Display the current user
Standard claim types populated by the SDK:
| Claim type | Source |
|---|---|
ClaimTypes.NameIdentifier | SAML NameID |
SamlClaimTypes.NameIdFormat | SAML NameID Format attribute |
SamlClaimTypes.SessionIndex | SAML SessionIndex |
SamlClaimTypes.AuthnContextClassRef | SAML AuthnContextClassRef |
| SAML attribute names | Each <Attribute> in the assertion |
7. Local logout
Local logout clears the ASP.NET Core cookie session. SAML Single Logout (SLO) is not implemented in v1.0.0.
app.MapPost("/logout", async (HttpContext ctx) =>
{
await ctx.SignOutAsync("saml");
return Results.Redirect("/");
});
8. Local user mapping
Implement ILocalAccountResolver for JIT provisioning or role mapping:
public class AppLocalAccountResolver : ILocalAccountResolver
{
public async Task<ClaimsIdentity?> ResolveAsync(
SamlPrincipal samlPrincipal, CancellationToken ct)
{
var user = await _users.FindByNameIdAsync(samlPrincipal.NameId, ct)
?? await _users.CreateAsync(samlPrincipal.NameId, ct);
if (!user.IsActive)
throw new LocalAccountResolutionException("Account is disabled");
var identity = new ClaimsIdentity("saml");
identity.AddClaim(new Claim(ClaimTypes.NameIdentifier, samlPrincipal.NameId));
foreach (var role in user.Roles)
identity.AddClaim(new Claim(ClaimTypes.Role, role));
return identity;
}
}
9. SP registration in Hawiyati
Expose SP metadata at any URL:
app.MapGet("/saml/metadata", () =>
{
var xml = new MetadataGenerator().Generate(samlConfig);
return Results.Content(xml, "application/xml");
});
After registration, download the IdP signing certificate from Admin → IdP → Certificates → Download PEM and place it at Saml:IdpSigningCertPath.
10. Deferred extensions (not in v1.0.0)
| Feature | Status | Fallback behavior |
|---|---|---|
| SAML Single Logout (SLO) | Deferred | SignOutAsync clears local cookie only; IdP session remains active |
| IdP-initiated login | Deferred | SP-initiated only |
| Encrypted assertions | Deferred | Only signed (unencrypted) assertions accepted |
| AuthnContext class negotiation | Deferred | No RequestedAuthnContext in AuthnRequest |
| Multi-IdP federation per SP | Deferred | Exactly one TrustedIdp per SamlSpConfig |