Egov.Integrations.MPass.Saml 8.0.56

MPass SAML Authentication

This package is intended for Service Provider integration built on ASP.NET Core 8.0+ with MPass using SAML v2.0 protocol for authentication.

Getting Started

Please go through the following instructions to integrate your project with MPass.

Prerequisites

Before being able to integrate with MPass, a Service Provider, including its certificate, must be registered accordingly in MPass. MPass accepts certificates issued by STISC.

Installing

Install the following package from NuGet

Install-Package Egov.Integrations.MPass.Saml

Note: This package is dependent on Egov.Extensions.Configuration.

Then follow the instructions from Configuration and Usage sections below.

Configuration

Add the following configuration section to your appsettings.json:

{
   ...
    "Certificate": {
      "Path": "Files\\Certificates\\yourcertificate.pfx",
      "Password": "yourcertificatepassword"
   }
   ...
   "MPassSaml": {
      "SamlRequestIssuer": "https://sampleservice.md",
      "IdentityProviderCertificatePath": "Files\\Certificates\\idp.cer",
      "SamlMessageTimeout": "00:10:00",
      "SamlLoginDestination": "https://mpass.staging.egov.md/login/saml",
      "SamlLogoutDestination": "https://mpass.staging.egov.md/logout/saml",
      "ServiceRootUrl": "https://localhost:44379"
   }
   ...
}

where ServiceRootUrl is the base path of your published service.

Please note that your Service must be published using https protocol.

Usage

Add the following code snippet to your Startup.ConfigureServices method:

builder.Services.AddSystemCertificate(builder.Configuration.GetSection("Certificate"));

services.AddAuthentication(sharedOptions =>
{
    sharedOptions.DefaultAuthenticateScheme = CookieAuthenticationDefaults.AuthenticationScheme;
    sharedOptions.DefaultSignInScheme = CookieAuthenticationDefaults.AuthenticationScheme;
    sharedOptions.DefaultChallengeScheme = MPassSamlDefaults.AuthenticationScheme;
})
.AddCookie()
.AddMPassSaml(builder.Configuration.GetSection("MPassSaml"));

In your Startup.Configure add the Authentication Middleware.

app.UseAuthentication();

This package allows you to enable default endpoints mapper, so you don't have to implement login, logout, and user-details endpoints manually.

app.MapMPassSaml();

MapMPassSaml - registers 3 endpoints in your application under the /account path:

• /account/login - Initiates SAML authentication with MPass. Accepts optional query parameters:
  • returnUrl - URL to redirect after successful authentication (defaults to /)
  • passive - Set to true for passive authentication (defaults to false)
  • lang - Language preference (ro, ru, or en)
• /account/logout - Handles logout from both local and remote sessions. Accepts optional query parameter:
  • returnUrl - URL to redirect after logout (defaults to /)
• /account/me - Returns the current user's claims as JSON. Returns 204 No Content if the user is not authenticated.

Authentication is started automatically if you are not already authenticated with code →

    // DefaultAuthenticateScheme causes User to be set
    var user = context.User;

    // Not authenticated
    if (user == null || !user.Identities.Any(identity => identity.IsAuthenticated))
    {
        // This is what [Authorize] calls
        await context.ChallengeAsync();

        return;
    }

LogOut is initiated then Sign Out and Sign Out Remote buttons are pressed.
For local logout is used next part of code.

    if (context.Request.Path.Equals("/signout"))
    {
        await context.SignOutAsync(CookieAuthenticationDefaults.AuthenticationScheme);
        await WriteHtmlAsync(context.Response, async res =>
        {
            await context.Response.WriteAsync($"<h1>Signed out {HtmlEncode(context.User.Identity.Name)}</h1>");
            await context.Response.WriteAsync("<a class=\"btn btn-link\" href=\"/\">Sign In</a>");
        });
        return;
    }

For remote logout is used next part of code.

    if (context.Request.Path.Equals("/signout-remote"))
    {
        if (context.User.Identity.IsAuthenticated)
        {
            // Redirects
            await context.SignOutAsync(CookieAuthenticationDefaults.AuthenticationScheme);
            await context.SignOutAsync(MPassSamlDefaults.AuthenticationScheme,
                new AuthenticationProperties()
                {
                    RedirectUri = "/signedout"
                });
            return;
        }
        else
        {
            await WriteHtmlAsync(context.Response, async res =>
            {
                await context.Response.WriteAsync($"<h1>Signed out {HtmlEncode(context.User.Identity.Name)}</h1>");
                await context.Response.WriteAsync("<a class=\"btn btn-link\" href=\"/\">Sign In</a>");
            });
            return;
        }

    }