Home

Installation

To install the SAML2 library in your project, you may either download the source package and compile it, or install from NuGet package "SAML2". Releases will be added at a later date.

Configuration

The SAML2 library will require several Web.config changes. One new section must be added to the Web.config, and three handlers need to be mapped to use this library. The basic skeleton of these changes is below. More information on the contents of section can be found below.

<configuration xmlns:xdt="http://schemas.microsoft.com/XML-Document-Transform">
<configSections>
    <section name="saml2" type="SAML2.Config.Saml2Section, SAML2" />
</configSections>
...
<system.webServer>
    <handlers>
    <remove name="SAML2.Protocol.Saml20SignonHandler" />
    <remove name="SAML2.Protocol.Saml20LogoutHandler" />
    <remove name="SAML2.Protocol.Saml20MetadataHandler" />
    <add name="SAML2.Protocol.Saml20SignonHandler" verb="*" path="Login.ashx" type="SAML2.Protocol.Saml20SignonHandler, SAML2" />
    <add name="SAML2.Protocol.Saml20LogoutHandler" verb="*" path="Logout.ashx" type="SAML2.Protocol.Saml20LogoutHandler, SAML2" />
    <add name="SAML2.Protocol.Saml20MetadataHandler" verb="*" path="Metadata.ashx" type="SAML2.Protocol.Saml20MetadataHandler, SAML2" />
    </handlers>
</system.webServer>
...
<saml2>
    ...
</saml2>

The configuration section is split into several specific configuration areas

Element	Usage
<allowedAudienceUris>	Configures the SAML AudienceRestrictions values to use when generating assertions.
<serviceProvider>	Configures the service provider information such as endpoints, SAML AuthnContexts, and NameIdFormats.
<identityProviders>	Configures the identity providers to be used for federation. Can be as simple as defining the location of the IdP metadata, or provide access to overriding IdP metadata with custom values, etc.
<metadata>	(Optional) Configures various options used for metadata generation, such as contacts, organization information, requested attributes, etc.
<actions>	(Optional) Allows for setting the actions to execute on successful SignOn or Logout. Custom actions can be created, or the defaults can be used.
<commonDomainCookie>	(Optional) Configures Common Domain Cookie usage.
<assertionProfile>	(Optional) Configures the assertion profile to use for validating SAML assertions. Custom assertion profiles can be created to provide additional validation in special circumstances.
<logging>	(Optional) Configures the logging provider for the library. Multiple implementations are available, and additional ones can easily be created. By default, the built in NoLogging provider will be used.

Examples

See the Configuration Examples page for more examples of configuring SAML2.

Important Note for MVC / WebAPI

There is a caveat to keep in mind if using MVC / WebAPI. Both of these hand of routing of requests to their respective routing systems, which means the handler endpoints may result in a 404 when you try and access them. You may need to add a routeIgnore for *.ashx to get around this. You can do this by adding the following line to the route config for your application before your other routes:

routes.IgnoreRoute("{resource}.ashx/{*pathInfo}");

public static void RegisterRoutes(RouteCollection routes)
{
    routes.IgnoreRoute("{resource}.ashx/{*pathInfo}");

    routes.MapRoute(
        "Default",                                              // Route name
        "{controller}/{action}/{id}",                           // URL with parameters
        new { controller = "Home", action = "Index", id = "" }  // Parameter defaults
    );
}

Usage

Once SAML2 is configured, and your service provider is registered with the identity providers, actually using it revolves around the three registered handlers: Saml20SignonHandler, Saml20LogoutHandler, and Saml20MetadataHandler. By default, these are registered at /Login.ashx, /Logout.ashx, and /Metadata.ashx.

Handler	Default Location	Use
Saml20SignonHandler	/Login.ashx	Handles generating SAML authentication requests, and the response back from the identity provider.
Saml20LogoutHandler	/Logout.ashx	Handles generating SAML logout requests for service provider initiated logouts, and processing of identity provider initiated logout requests.
Saml20MetadataHandler	/Metadata.ashx	Handles generating service provider metadata files, which identity providers can import for quick setup.

SignOn and Logout

The Saml20SignonHandler will handle SSO (Singing SignOn), by generating SAML AuthnRequests and processing the responses from the identity provider when received.

The Saml20LogoutHandler will handle SLO (Single LogOut), by generating SAML LogoutRequests and processing the response from the identity provider when received (Service Provider Initiated SLO). It will also handle Identity Provider Initiated SLO.

Both handlers will execute configurable Actions after successful processing of a SAML request / response. By default, three actions will execute, but any custom actions can replace these, or be injected into process. This is the recommended way to handle custom authentication needs.

Default Authentication Process

Custom Authentication Process

Metadata

The Saml20MetadataHandler will generate a SAML2 metadata file for your service provider from the configuration. These are the normal method of passing configuration information back and forth between the identity providers and the service provider.

These files will contain public keys, and implementation details which some organizations may deem sensitive. In general, this is not the case, but if directed to secure this, the following can be used to deny access to everyone, and can then be manually removed if access is required again in the future, or the handler can just be removed from the configuration all together.

<configuration>
...
<location path="Metadata.ashx">
    <system.web>
    <authorization>
        <deny users="*" />
    </authorization>
    </system.web>
</location>
...
</configuration>