H· Hawiyati Documentation

.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.

Known limitation: The .NET 8 SDK was not installed in the development environment during v1.0.0. All code has been reviewed but unit tests were not executed locally. Run dotnet test before merging to production.

1. Prerequisites

RequirementMinimum version
.NET8.0
ASP.NET Core8.0
Hawiyati IdP2.0
Network accessSP → 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 typeSource
ClaimTypes.NameIdentifierSAML NameID
SamlClaimTypes.NameIdFormatSAML NameID Format attribute
SamlClaimTypes.SessionIndexSAML SessionIndex
SamlClaimTypes.AuthnContextClassRefSAML AuthnContextClassRef
SAML attribute namesEach <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)

FeatureStatusFallback behavior
SAML Single Logout (SLO)DeferredSignOutAsync clears local cookie only; IdP session remains active
IdP-initiated loginDeferredSP-initiated only
Encrypted assertionsDeferredOnly signed (unencrypted) assertions accepted
AuthnContext class negotiationDeferredNo RequestedAuthnContext in AuthnRequest
Multi-IdP federation per SPDeferredExactly one TrustedIdp per SamlSpConfig