H· Hawiyati Documentation

Guide d’intégration .NET/ASP.NET Core

Intégrez le SDK SAML2 SP Hawiyati avec vos applications .NET 8 ASP.NET Core. Couvre le package NuGet, le câblage du middleware, la configuration minimale, la protection des routes, la gestion ACS, la déconnexion et l’enregistrement SP.

Limitation connue : Le SDK .NET 8 n’était pas installé dans l’environnement de développement lors de la v1.0.0. Tout le code a été relu mais les tests unitaires n’ont pas été exécutés localement. Exécutez dotnet test avant tout passage en production.

1. Prérequis

PrérequisVersion minimale
.NET8.0
ASP.NET Core8.0
Hawiyati IdP2.0
Accès réseauSP → IdP sur le port 443

L’API Data Protection ASP.NET Core est requise pour le cookie de corrélation. Appelez builder.Services.AddDataProtection() avant d’enregistrer l’authentification.

2. Ajout de la dépendance

dotnet add package Hawiyati.Saml.Sp.AspNetCore --version 1.0.0
dotnet add package Hawiyati.Saml.Sp --version 1.0.0

3. Configuration minimale

Ajoutez la section SAML dans appsettings.json. Ne stockez pas le certificat IdP en clair dans ce fichier.

{
  "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"
  }
}

4. Protéger une route

L’ordre des middlewares est obligatoire :

app.UseHttpsRedirection();
app.UseSamlAcs("saml");   // Doit venir avant UseAuthentication
app.UseAuthentication();
app.UseAuthorization();

7. Déconnexion locale

SAML Single Logout (SLO) n’est pas implémenté en v1.0.0.

app.MapPost("/logout", async (HttpContext ctx) =>
{
    await ctx.SignOutAsync("saml");
    return Results.Redirect("/");
});

10. Extensions différées (hors périmètre v1.0.0)

FonctionnalitéStatutComportement de repli
SAML Single Logout (SLO)DifféréSignOutAsync supprime uniquement le cookie local
Connexion initiée par l’IdPDifféréUniquement SP-initié
Assertions chiffréesDifféréSeules les assertions signées acceptées
Négociation du contexte d’authentificationDifféréAucun élément RequestedAuthnContext
Fédération multi-IdP par SPDifféréUn seul TrustedIdp par instance