WBL.Saml2Handler 1.0.2

WBL.Saml2Handler

This packages makes sure of the 'ITfoxtech.Identity.Saml2' package to perform SAML2 based authentication using the .NET 8 authentication middleware approach. The package is designed to make easier use of the ITfoxtech library in modern .NET

Quick start guide:

In your program/startup add the following

 builder.Services
    .AddAuthentication("saml2AuthScheme")
    .AddSaml2("saml2AuthScheme", "saml2cookie","Saml2 demo", options => {
        // Configuraiton of saml2 integration goes here
    });

    builder.Services.AddAuthorization();

Ensure the authScheme for saml2 and default are the same for ease of use.

Next configure the desired saml2 authentication options. If all desired properties are set and matching from an appsettings.json the following approach can be used.

 builder.Services
    .AddAuthentication("saml2AuthScheme")
    .AddSaml2("saml2AuthScheme", "saml2cookie","Saml2 demo", options => {
        builder.Configuration.Bind("Saml2:Security", options);
    });

    builder.Services.AddAuthorization();

Manual example of configuration

        builder.Services
            .AddAuthentication("saml2AuthScheme")
            .AddSaml2("saml2AuthScheme", "saml2cookie","Saml2 demo", async options =>
        {
            builder.Configuration.Bind("Saml2:Security", options);
            var saml2Options = builder.Configuration.GetSection(Saml2Options.Position).Get<Saml2Options>();
            
            options.SignInScheme = "saml2cookie";
            options.LoginPath = saml2Options.Paths.LoginPath;
            options.LocalLogoutPath = saml2Options.Paths.LocalLogoutPath;
            options.InitiateSingleLogoutPath = saml2Options.Paths.InitiateSingleLogoutPath;
            options.SingleLogoutPath = saml2Options.Paths.SingleLogoutPath;
            options.SingleLogoutCallbackPath = saml2Options.Paths.SingleLogoutCallbackPath;
            options.CallbackPath = saml2Options.Paths.AssertionConsumerServicePath;
            options.MetadataPath = saml2Options.Paths.Metadata;
            options.EnableChallenge = saml2Options.EnableChallenge;

            // Setup the ITFoxtech Saml2Configuration
            options.Saml2Configuration.Issuer = saml2Options.Issuer;
            options.Saml2Configuration.AllowedAudienceUris.Add(saml2Options.Issuer);
            options.Saml2Configuration.SignAuthnRequest = true;
            options.Saml2Configuration.RevocationMode = saml2Options.CertificateRevocationMode ?? X509RevocationMode.Online;
            options.Saml2Configuration.CertificateValidationMode = saml2Options.CertificateValidationMode ?? X509CertificateValidationMode.ChainTrust;
            if (!string.IsNullOrEmpty(saml2Options.SignatureAlgorithm))
            {
                options.Saml2Configuration.SignatureAlgorithm = saml2Options.SignatureAlgorithm;
            }

            // Fetch metadata from IdP
            var entityDescriptor = new EntityDescriptor();
            entityDescriptor.ReadIdPSsoDescriptorFromUrl(saml2Options.IdPMetadataAddress);
            if (entityDescriptor.IdPSsoDescriptor != null)
            {
                options.Saml2Configuration.SingleSignOnDestination = entityDescriptor.IdPSsoDescriptor
                    .SingleSignOnServices
                    .FirstOrDefault()?.Location;
                options.Saml2Configuration.SingleLogoutDestination = entityDescriptor.IdPSsoDescriptor
                    .SingleLogoutServices
                    .FirstOrDefault()?.Location;
                options.Saml2Configuration.SignatureValidationCertificates.AddRange(entityDescriptor
                    .IdPSsoDescriptor
                    .SigningCertificates);

                // load up certificates
                var cert = CertificateStore.Find(saml2Options.CertificateStore, saml2Options.CertificateLocation,
                    X509FindType.FindByThumbprint, saml2Options.CertificateThumbprint);
                // Use the same cert for signing and encryption
                options.Saml2Configuration.SigningCertificate = cert;
                options.Saml2Configuration.EncryptionCertificate = cert;
                options.Saml2Configuration.DecryptionCertificates = [cert];
            }
            else
            {
                // unable to load SSO metadata. This will result in an error when ITFoxtec tries to validate the response.
            }
        });

        builder.Services.AddAuthorization();

Example of configured values from appsettings.json

  "Security": {
    "Saml2": {
      "Paths": {
        "AssertionConsumerServicePath": "/Auth/AssertionConsumerService",
        "LoginPath": "/Auth/Login",
        "LocalLogoutPath": "/Auth/LocalLogout",
        "InitiateSingleLogoutPath": "/Auth/Logout",
        "SingleLogoutPath": "/Auth/SingleLogout",
        "SingleLogoutCallbackPath": "/Auth/LoggedOut",
        "Metadata": "/Auth/Metadata"
      },
      "Metadata": {
        "WantAssertionsSigned": true
      },
      "AuthScheme": "Saml2Weibel",
      "CookieScheme": "Saml2Cookie",
      "EnableChallenge": true,
      "UseCertStore": true,
      "IdPMetadataAddress": "https://adfs.weibel.dev/FederationMetadata/2007-06/FederationMetadata.xml",
      "Issuer": "http://saml2demo.weibel.dev/schema/adfs.weibel.dev",
      "CertificateThumbprint": "439ec47d709b9257a7b6aa27a3573ebdcd7db2f5",
      "CertificateLocation": "CurrentUser",
      "CertificateStore": "MY",
      "CertificateRevocationMode": "NoCheck",
      "CertificateValidationMode": "None"
    }
  }