componentspace saml for asp.net core …...componentspace saml for asp.net core identityserver4...
TRANSCRIPT
Copyright © ComponentSpace Pty Ltd 2017-2020. All rights reserved. www.componentspace.com
ComponentSpace
SAML for ASP.NET Core
IdentityServer4
Integration Guide
ComponentSpace SAML for ASP.NET Core IdentityServer4 Integration Guide
i
Contents Introduction ............................................................................................................................................ 1
IdentityServer4 as the Service Provider .................................................................................................. 1
Adding SAML Support ......................................................................................................................... 1
Service Provider Configuration ........................................................................................................... 2
Application Startup ............................................................................................................................. 2
Identity Provider Configuration .......................................................................................................... 3
SP-Initiated SSO................................................................................................................................... 3
IdP-Initiated SSO ................................................................................................................................. 8
SAML Logout ....................................................................................................................................... 8
IdentityServer4 as the Identity Provider ............................................................................................... 11
Adding SAML Support ....................................................................................................................... 11
Identity Provider Configuration ........................................................................................................ 12
Middleware vs API ............................................................................................................................ 13
SAML Middleware ............................................................................................................................. 13
Application Startup ....................................................................................................................... 13
SAML API ........................................................................................................................................... 14
Application Startup ....................................................................................................................... 14
SAML Controller ............................................................................................................................ 15
Service Provider Configuration ......................................................................................................... 17
SP-Initiated SSO................................................................................................................................. 17
IdP-Initiated SSO ............................................................................................................................... 20
SAML Logout ..................................................................................................................................... 20
ComponentSpace SAML for ASP.NET Core IdentityServer4 Integration Guide
1
Introduction IdentityServer4 doesn’t natively support SAML SSO but it is extensible.
This document describes how to add SAML support to IdentityServer4 acting as either an identity
provider or service provider.
The reader is assumed to have an existing IdentityServer4 project.
For information on building, configuring and running IdentityServer4, refer to the following
documentation.
https://identityserver4.readthedocs.io/en/release/index.html
IdentityServer4 as the Service Provider IdentityServer4 supports users signing in using external identity providers.
IdentityServer4 is the SAML service provider and the external providers are the SAML identity
providers. The application authenticating to IdentityServer4 may use any available protocol (e.g.
OpenID Connect).
The following sections described how to enable sign-on using external SAML identity providers.
Adding SAML Support Add the ComponentSpace.Saml2 NuGet package to the IdentityServer4 project.
Add the Certificates folder to the IdentityServer4 project. The following certificate files may be
copied from the ExampleServiceProvider project.
• sp.pfx
ComponentSpace SAML for ASP.NET Core IdentityServer4 Integration Guide
2
• idp.cer
Service Provider Configuration In IdentityServer4’s appsettings.json, include the SAML configuration.
"SAML": { "$schema": "https://www.componentspace.com/schemas/saml-config-schema-v1.0.json", "Configurations": [ { "LocalServiceProviderConfiguration": { "Name": "https://IdentityServer4", "Description": "IdentityServer4", "AssertionConsumerServiceUrl": "http://localhost:5000/SAML/AssertionConsumerService", "SingleLogoutServiceUrl": "http://localhost:5000/SAML/SingleLogoutService", "LocalCertificates": [ { "FileName": "certificates/sp.pfx", "Password": "password" } ] }, "PartnerIdentityProviderConfigurations": [ { "Name": "https://ExampleIdentityProvider", "Description": "Example Identity Provider", "SignAuthnRequest": true, "SingleSignOnServiceUrl": "https://localhost:44313/SAML/SingleSignOnService", "SingleLogoutServiceUrl": "https://localhost:44313/SAML/SingleLogoutService", "PartnerCertificates": [ { "FileName": "certificates/idp.cer" } ] } ] } ] }, "PartnerName": "https://ExampleIdentityProvider"
For information on SAML configuration, refer to the SAML for ASP.NET Core Configuration Guide.
Application Startup In the IdentityServer4’s Startup class, add the following.
private readonly IConfiguration _config; public Startup(IConfiguration config) { _config = config; }
ComponentSpace SAML for ASP.NET Core IdentityServer4 Integration Guide
3
In the ConfigureServices method in IdentityServer4’s Startup class, add the following.
// Add SAML SSO services. services.AddSaml(_config.GetSection("SAML"); // Add the SAML authentication handler. services.AddAuthentication() .AddSaml(options => { options.SignInScheme = IdentityServerConstants.ExternalCookieAuthenticationScheme; options.PartnerName = () => _config["PartnerName"]; });
These sections of code are available at:
https://gist.github.com/componentspace/49b98a772a2b292360d473576e568f10
For more information, refer to the SAML for ASP.NET Core Developer Guide.
Identity Provider Configuration The following partner service provider configuration is included in the example identity provider’s
SAML configuration.
{ "Name": "https://IdentityServer4", "Description": "IdentityServer4", "WantAuthnRequestSigned": true, "SignSamlResponse": true, "AssertionConsumerServiceUrl": "http://localhost:5000/SAML/AssertionConsumerService", "SingleLogoutServiceUrl": "http://localhost:5000/SAML/SingleLogoutService", "PartnerCertificates": [ { "FileName": "certificates/sp.cer" } ] }
SP-Initiated SSO The reader is assumed to have an application that authenticates to IdentityServer4 using OpenID
Connect or some other protocol.
For more information, refer to the IdentityServer4 documentation.
Browse to the application and initiate login.
ComponentSpace SAML for ASP.NET Core IdentityServer4 Integration Guide
4
At the IdentityServer4 login page, click the SAML external login button.
ComponentSpace SAML for ASP.NET Core IdentityServer4 Integration Guide
5
Login at the identity provider.
ComponentSpace SAML for ASP.NET Core IdentityServer4 Integration Guide
6
Allow the requested permissions.
ComponentSpace SAML for ASP.NET Core IdentityServer4 Integration Guide
7
The user is automatically logged in at the service provider.
ComponentSpace SAML for ASP.NET Core IdentityServer4 Integration Guide
8
IdP-Initiated SSO IdP-initiated SSO is not supported by IdentityServer4.
SAML Logout IdP-initiated SAML logout is not supported by IdentityServer4.
SP-initiated SAML logout is supported.
Initiate logout at the application.
ComponentSpace SAML for ASP.NET Core IdentityServer4 Integration Guide
9
You are logged out at IdentityServer4.
ComponentSpace SAML for ASP.NET Core IdentityServer4 Integration Guide
10
Click the link to return to the application.
ComponentSpace SAML for ASP.NET Core IdentityServer4 Integration Guide
11
IdentityServer4 as the Identity Provider IdentityServer4 supports adding authentication protocols.
The following sections described how to enable SAML SSO to IdentityServer4.
Authenticating applications act as SAML service providers and IdentityServer4 is the SAML identity
provider.
Adding SAML Support Add the ComponentSpace.Saml2 NuGet package to the IdentityServer4 project.
ComponentSpace SAML for ASP.NET Core IdentityServer4 Integration Guide
12
Add the Certificates folder to the IdentityServer4 project. The following certificate files may be
copied from the ExampleIdentityProvider project.
• idp.pfx
• sp.cer
Identity Provider Configuration In IdentityServer4’s appsettings.json, include the SAML configuration.
"SAML": { "$schema": "https://www.componentspace.com/schemas/saml-config-schema-v1.0.json", "Configurations": [ { "LocalIdentityProviderConfiguration": { "Name": "https://IdentityServer4", "Description": "IdentityServer4", "SingleSignOnServiceUrl": "http://localhost:5000/SAML/SingleSignOnService", "SingleLogoutServiceUrl": "http://localhost:5000/SAML/SingleLogoutService", "ArtifactResolutionServiceUrl": "http://localhost:5000/SAML/ArtifactResolutionService", "LocalCertificates": [ { "FileName": "certificates/idp.pfx", "Password": "password" } ] }, "PartnerServiceProviderConfigurations": [ { "Name": "https://ExampleServiceProvider", "Description": "Example Service Provider",
ComponentSpace SAML for ASP.NET Core IdentityServer4 Integration Guide
13
"WantAuthnRequestSigned": true, "SignSamlResponse": true, "AssertionConsumerServiceUrl": "https://localhost:44360/SAML/AssertionConsumerService", "SingleLogoutServiceUrl": "https://localhost:44360/SAML/SingleLogoutService", "ArtifactResolutionServiceUrl": "https://localhost:44360/SAML/ArtifactResolutionService", "PartnerCertificates": [ { "FileName": "certificates/sp.cer" } ] } ] } ] }
For information on SAML configuration, refer to the SAML for ASP.NET Core Configuration Guide.
Middleware vs API When adding SSO support to IdentityServer4, you have a choice between:
• Adding the SAML authentication handler or SAML middleware
• Making explicit SAML API calls within the application
Both approaches are described in the following sections.
SAML flows are the same for the two approaches.
For more information, refer to the SAML for ASP.NET Core Developer Guide.
SAML Middleware
Application Startup In the IdentityServer4’s Startup class, add the following.
private readonly IConfiguration _config; public Startup(IConfiguration config) { _config = config; }
In the ConfigureServices method in the application’s Startup class, add the following.
// Add SAML SSO services. services.AddSaml(_config.GetSection("SAML"); // Add SAML Middleware services.
services.AddSamlMiddleware();
In the Configure method in the application’s Startup class, add the following.
ComponentSpace SAML for ASP.NET Core IdentityServer4 Integration Guide
14
This should be placed after the UseIdentityServer call.
// Use SAML middleware. app.UseSaml(); // Specify the display name and return URL for logout. app.Use(async (context, next) => { if (context.Request.Path.Value.Equals("/Account/Logout", StringComparison.OrdinalIgnoreCase) && string.IsNullOrEmpty(context.Request.Query["logoutId"])) { var identityServerInteractionService = context.RequestServices.GetRequiredService<IIdentityServerInteractionService>(); var logoutMessageStore = context.RequestServices.GetRequiredService<IMessageStore<LogoutMessage>>(); var logoutMessage = new Message<LogoutMessage>(new LogoutMessage { ClientName = "SAML Service Provider", PostLogoutRedirectUri = "/SAML/SingleLogoutServiceCompletion" }, DateTime.UtcNow); var logoutId = await logoutMessageStore.WriteAsync(logoutMessage); context.Request.QueryString = context.Request.QueryString.Add("logoutId", logoutId); } await next(); });
These sections of code are available at:
https://gist.github.com/componentspace/995ff9eee9bbdd30a4e0e73dc1a236d7
For more information, refer to the SAML for ASP.NET Core Developer Guide.
SAML API
Application Startup In the IdentityServer4’s Startup class, add the following.
private readonly IConfiguration _config; public Startup(IConfiguration config) { _config = config; }
In the ConfigureServices method in the application’s Startup class, add the following.
// Add SAML SSO services. services.AddSaml(_config.GetSection("SAML");
ComponentSpace SAML for ASP.NET Core IdentityServer4 Integration Guide
15
These sections of code are available at:
https://gist.github.com/componentspace/995ff9eee9bbdd30a4e0e73dc1a236d7
For more information, refer to the SAML for ASP.NET Core Developer Guide.
SAML Controller Add a SAML controller to the IdentityServer4 project. This controller includes actions for handling
SAML single sign-on and logout.
public class SamlController : Controller { private readonly ISamlIdentityProvider _samlIdentityProvider; private readonly IIdentityServerInteractionService _identityServerInteractionService; private readonly IMessageStore<LogoutMessage> _logoutMessageStore; public SamlController( ISamlIdentityProvider samlIdentityProvider, IIdentityServerInteractionService identityServerInteractionService, IMessageStore<LogoutMessage> logoutMessageStore) { _samlIdentityProvider = samlIdentityProvider; _identityServerInteractionService = identityServerInteractionService; _logoutMessageStore = logoutMessageStore; } public async Task<ActionResult> SingleSignOnService() { // Receive the authn request from the service provider (SP-initiated SSO). await _samlIdentityProvider.ReceiveSsoAsync(); // If the user is logged in at the identity provider, complete SSO immediately. // Otherwise have the user login before completing SSO. if (User.Identity.IsAuthenticated) { await CompleteSsoAsync(); return new EmptyResult(); } else { return RedirectToAction("SingleSignOnServiceCompletion"); } } [Authorize] public async Task<ActionResult> SingleSignOnServiceCompletion() { await CompleteSsoAsync(); return new EmptyResult(); } public async Task<ActionResult> SingleLogoutService()
ComponentSpace SAML for ASP.NET Core IdentityServer4 Integration Guide
16
{ // Receive the single logout request or response. // If a request is received then single logout is being initiated by a partner service provider. // If a response is received then this is in response to single logout having been initiated // by the identity provider. var sloResult = await _samlIdentityProvider.ReceiveSloAsync(); if (sloResult.IsResponse) { if (sloResult.HasCompleted) { // IdP-initiated SLO has completed. return RedirectToPage("/Index"); } } else { // Specify the display name and return URL for logout. var logoutMessage = new Message<LogoutMessage>(new LogoutMessage { ClientName = "SAML Service Provider", PostLogoutRedirectUri = "/SAML/SingleLogoutServiceCompletion" }, DateTime.UtcNow); var logoutId = await _logoutMessageStore.WriteAsync(logoutMessage); // Logout locally. return RedirectToAction("Logout", "Account", new { logoutId = logoutId }); } return new EmptyResult(); } public async Task<ActionResult> SingleLogoutServiceCompletion() { // Respond to the SP-initiated SLO request indicating successful logout. await _samlIdentityProvider.SendSloAsync(); return new EmptyResult(); } private Task CompleteSsoAsync() { // Get the name of the logged in user. var userName = User.Identity.Name; // Include claims as SAML attributes. var attributes = new List<SamlAttribute>(); foreach (var claim in ((ClaimsIdentity)User.Identity).Claims) { attributes.Add(new SamlAttribute(claim.Type, claim.Value)); } // The user is logged in at the identity provider.
ComponentSpace SAML for ASP.NET Core IdentityServer4 Integration Guide
17
// Respond to the authn request by sending a SAML response containing a SAML assertion to the SP. return _samlIdentityProvider.SendSsoAsync(userName, attributes); } }
Service Provider Configuration The following partner identity provider configuration is included in the example service provider’s
SAML configuration.
{ "Name": "https://IdentityServer4", "Description": "IdentityServer4", "SignAuthnRequest": true, "SingleSignOnServiceUrl": "http://localhost:5000/SAML/SingleSignOnService", "SingleLogoutServiceUrl": "http://localhost:5000/SAML/SingleLogoutService", "ArtifactResolutionServiceUrl": "http://localhost:5000/SAML/ArtifactResolutionService", "PartnerCertificates": [ { "FileName": "certificates/idp.cer" } ] }
Ensure the PartnerName specifies the correct partner identity provider.
"PartnerName": "https://IdentityServer4"
SP-Initiated SSO Browse to the example service provider and click the button to SSO to the identity provider.
ComponentSpace SAML for ASP.NET Core IdentityServer4 Integration Guide
18
Log into IdentityServer4.
ComponentSpace SAML for ASP.NET Core IdentityServer4 Integration Guide
19
The user is automatically logged in at the service provider.
ComponentSpace SAML for ASP.NET Core IdentityServer4 Integration Guide
20
IdP-Initiated SSO IdP-initiated SSO is not supported by IdentityServer4.
SAML Logout IdP-initiated SAML logout is not supported by IdentityServer4.
SP-initiated SAML logout is supported.
Click the logout link at the example service provider.
ComponentSpace SAML for ASP.NET Core IdentityServer4 Integration Guide
21
You are prompted to logout at IdentityServer4.
ComponentSpace SAML for ASP.NET Core IdentityServer4 Integration Guide
22
Click the Yes button.
ComponentSpace SAML for ASP.NET Core IdentityServer4 Integration Guide
23
Click the link to return to the example service provider.
ComponentSpace SAML for ASP.NET Core IdentityServer4 Integration Guide
24