The Rock Solid Knowledge SAML Service Provider (SP) component allows your users to log into your ASP.NET Core application using an account handled by an external SAML Identity Provider.
Following this quickstart, you will learn how to add SAML authentication to your ASP.NET Core application using our Rock Solid Knowledge 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 Rsk.Saml Package
dotnet add package Rsk.Saml
Configure SAML Authentication Handler
Our library acts much in the same way as other ASP.NET Core authentication libraries for external providers (e.g., OpenID Connect), where you have a local authentication type (a cookie) and then an external authentication provider (SAML2P).
To enable SAML authentication in your ASP.NET Core application, add the following code to the ConfigureServices method in your Startup class.
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 authentication services to your DI container.
To enable cookie authentication, use the AddCookie method and set cookie to be the default means to authenticate the user.
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 option 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. Digitally signed SAML requests from an SP allow the IdP to verify that the requests are authentic and untampered. 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 can all be retrieved from the identity provider's metadata document.
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:
new X509Certificate2(Convert.FromBase64String(@"MIIDajCCAlKgAwIBAgI...);
Instead of manually specifying the identity provider information, you can use the automatic metadata lookup.
Define ACS Endpoint
The CallbackPath defaults to /signin-saml, 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.
Our 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 your are configuring multiple external identity providers, please read our Federating with Multiple External Providers documentation.
Define Sign-in Scheme
The SignInScheme is used to issue a cookie using the cookie handler once the SAML authentication is complete.
This is the cookie that the SAML identity will be saved to.
You don't need to specify a value for SignInScheme if it's the same as DefaultScheme.
Add Authentication Middleware
To ensure that the authentication services are executed on each request, add authentication to the Configure method in your Startup class:
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 you don't need to write any extra code.
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 Trigger Authentication
To invoke the SAML authentication handler, call ChallengeAsync and pass saml2p as the authentication scheme.
After the SAML middleware signs the user in, the user is also automatically signed into the cookie middleware, allowing the user to be authenticated on subsequent requests.
public async Task Login()
{
await HttpContext.ChallengeAsync("saml2p", new AuthenticationProperties {RedirectUri = "/"});
}
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, 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 ran 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-tunining your SAML authentication handler.
Other topics that you may find helpful: