Acting as a SAML ServiceProvider

The Rock Solid Knowledge SAML component turns your ASP.NET Core web application into a SAML 2.0 Service Provider (SP) allowing users to login using an account held by an external SAML Identity Provider.

The ServiceProvider part of the component is standalone and can be used without a dependencies on an OIDC Framework

Following this quickstart, you will learn how to add SAML authentication to your ASP.NET Core web application using the SAML component.

If you prefer a video tutorial instead, check out How to Setup SAML Service Provider.

Getting Started

License

Our SAML component requires a valid license. For a demo license, please sign up on our products page, or reach out to support@identityserver.com.

Install the Rsk.Saml Package

To act as a ServiceProvider only the base Rsk.Saml package is required, you can install this package using your preferred method.

For example, to install the package using the dotnet CLI

dotnet add package Rsk.Saml

Configure the SAML Authentication Handler

The SAML component is designed to mimic the default ASP.NET Core authentication handlers for external providers (e.g OpenID Connect), where you have a local authentication type (a cookie) and then an external authentication provider (SAML).

To enable SAML authentication in your ASP.NET Core application, add the following code to the ConfigureServices method in your Startup.cs class or Program.cs if you're using top-level statements.

public void ConfigureServices(IServiceCollection services)
{
    services.AddAuthentication(options =>
        {
            options.DefaultScheme = "cookie";
            options.DefaultChallengeScheme = "saml2p";
        })
        .AddCookie("cookie")
        .AddSaml2p("saml2p", options => {
            options.Licensee = "";
            options.LicenseKey = "";

            // details about the identity provider you want to integrate with
            options.IdentityProviderOptions = new IdpOptions {
                EntityId = "https://localhost:5000",
                SingleSignOnEndpoint = new SamlEndpoint("https://localhost:5000/saml/sso", SamlBindingTypes.HttpRedirect),
                SigningCertificates = { new X509Certificate2("idpPublicSigningKey.cer") }
            };

            // Details about yourself
            options.ServiceProviderOptions = new SpOptions {
                // the entity ID is the unique identifier for your app
                EntityId = "https://localhost:5001/saml",

                // this will be your SP metadata endpoint
                MetadataPath = "/samlsp-metadata",

                // optional
                SignAuthenticationRequests = false
            };

            // this will be your ACS endpoint
            options.CallbackPath = "/signin-saml";

            // this is the cookie that the SAML identity will be saved to. You only need to set this if it's different from DefaultScheme
            // options.SignInScheme = "cookie";
        });
}

The AddAuthentication method adds the .NET authentication services to your DI container. To save the ClaimsPrincipal generated by the SAML2P authentication handler you need to add a cookie authentication handler.

To add a cookie authentication handler, use the AddCookie method, name this scheme cookie and set the DefaultScheme to be cookie. This will tell .NET to look at the ClaimsPrincipal in this cookie by default to determine if the user is authenticated.

Set the default challenge scheme to the "saml2p" scheme, this will tell the application to default to this scheme during challenge requests if no scheme argument is provided.

Next, you need to configure the SAML authentication handler using the AddSaml2p method.

Configuration Options

License

You need to provide the licencee and license key that you obtained earlier in the Getting Started section.

Information about yourself

You need to define information about yourself, the service provider, using the ServiceProviderOptions. This data is configured for your application.

If the partner Identity Provider requires you to sign SAML requests, you must include a signing certificate in the ServiceProviderOptions and set SignAuthenticationRequests to true. This is your private signing key that will be used to sign the messages you send to the identity provider.

We recommend signing SAML requests whenever possible, as digitally signed SAML requests allow the SAML Identity Provider to verify that requests are authentic and have not been tampered with.

No other viable mechanisms are available to cryptographically bind requests to a specific SP.

Information about the partner IdP

You also need to define information about the Identity Provider that you want to authenticate against using the option IdentityProviderOptions.

The Identity Provider information is described in the Identity Provider's metadata document, this should be provided by your integration partner.

The Identity Provider's signing certificate is the public key that will be used to verify SAML responses sent from that provider.

You can either load it in from a file, or by converting the base64 encoded value found in the Identity Provider’s metadata document:

new X509Certificate2(Convert.FromBase64String(@"MIIDajCCAlKgAwIBAgI..."));

Instead of manually specifying the Identity Provider information, you can use the automatic metadata lookup feature. This is a more robust method of configuration, as the component will automatically update if any changes are made by the Identity Provider, such as during Key Rotation.

Define ACS Endpoint

The CallbackPath defaults to /saml/acs, and this value will be used as your Assertion Consumer Service (ACS Endpoint). This is the path where the Identity Provider will send SAML assertions to.

The SAML component handles the CallbackPath endpoint, and there's no need to write any other code to listen on this endpoint.

The value of CallbackPath must be unique per authentication handler. If you are configuring multiple external Identity Providers, please read our Federating with Multiple External Providers documentation.

Define Sign-in Scheme

The SignInScheme is where the authentication handler will store the ClaimPrincipal generated by the authentication. This is typically a cookie scheme (using a cookie authentication handler), and could your default authentication scheme if you want the SAML identity signed in without any processing, or a separate external cookie if you need to do any account linking or provisioning

If no SignInScheme if specified, the default authentication scheme will be used.

Add Authentication Middleware

To ensure that the authentication services are executed on each request, add a call to the IApplicationBuilder UseAuthentication extension method in your app config.

public void Configure(IApplicationBuilder app)
{
    app.UseDeveloperExceptionPage();
    app.UseStaticFiles();
    app.UseRouting();

    app.UseAuthentication();
    app.UseAuthorization();

    app.UseEndpoints(endpoints => endpoints.MapDefaultControllerRoute());
}

SAML2P Service Provider Metadata

You can now get the Service Provider metadata by visiting the path configured in your ServiceProviderOptions.MetadataPath.

If you have not set this path, then the default value is /saml. Again, just like the CallbackPath, this endpoint is also handled by our SAML component, and if you have multiple ServiceProviders configured each should have a unique path.

This metadata document is what you need to make available to any Identity Providers looking to integrate with your SAML Service Provider.

This document contains information such as your entityID, assertion consumer endpoints and public signing key.

Trigger Authentication

You can start integrating with the external Identity Provider once you have configured your SAML authentication handler and the Identity Provider has also configured their system to be aware of your configuration.

Manually Triggering Authentication

You can call a SAML authentication handler in the same way as another .Net authentication handler.

• Calling ChallengeAsync on the HttpContext
• Return a ChallengeResult from a Controller method.

To invoke the SAML authentication handler, create a challenge in your preferred way and and pass the Saml scheme, in this case saml2p, as the authentication scheme.

After the SAML middleware signs the user in, the user is also automatically signed into the cookie scheme by the middleware, allowing the user to be authenticated on subsequent requests.

public async Task Login()
{
    await HttpContext.ChallengeAsync("saml2p", new AuthenticationProperties {RedirectUri = "/"});
}

Here the RedirectUri is set to "/" which will send the user to the root page after authentication, but if you want to do any auto provisioning or account linking this should be dedicated callback method.

Automatically Trigger Authentication

As we set the DefaultScheme and DefaultChallengeScheme in this example, we can trigger authentication using the Authorize attribute. You don't need to call Challenge explicitly.

[Authorize]
public IActionResult ProtectedPage() => View();

Source Code

Completed source code for the above steps including test keys can be found on GitHub.

Next Steps

This quickstart demonstrated how to add SAML authentication to your ASP.NET Core application.

If you run into any unexpected errors, check out our Frequently Asked Questions.

Otherwise, please get in touch with us at support@identityserver.com.

Check out the other SAML SP Configuration Options for fine-tuning your SAML authentication handler.

If you using IdentityServer as a ServiceProvider, you will need to do some additional steps, for more information see - IdentityServer As A Service Provider

Other topics that you may find helpful:

• Federating with Multiple External Providers