SAML Middleware - Service Provider
The SAML authentication handler provides support for web applications acting as the SAML service provider (SP), and participating in SAML single sign-on (SSO) and single logout (SLO).
Both IdP-initiated and SP-initiated SSO and SLO are supported.
The SAML authentication handler will handle:
- Challenge requests from the application as part of login
- Sign out requests from the application as part of logout.
Upon a challenge request, a SAML authn request is sent to the identity provider as part of SP-initiated SSO. The SAML response returned by the identity provider is automatically received and processed to login the user.
Upon a sign out request, a SAML logout request is sent to the identity provider as part of SP-initiated SLO. The SAML logout response returned by the identity provider is automatically received and processed to logout the user.
Note
SAML API calls within the application should not be made as SSO and SLO are managed by the SAML authentication handler.
Initialization
The following code adds the SAML services and SAML authentication handler.
// Add SAML services.
builder.Services.AddSaml(builder.Configuration.GetSection("SAML"));
// Add SAML authentication services.
builder.Services.AddAuthentication().AddSaml(options =>
{
options.PartnerName = (httpContext) => builder.Configuration["PartnerName"];
});
Authentication Options
SamlAuthenticationOptions provides configuration options to the SAML authentication handler.
ConfigurationName
The optional delegate returns the configuration name identifying which SAML configuration to use when processing SSO and SLO requests for the current user.
It's only required if multiple SAML configurations exist (e.g. in a multi-tenanted environment).
PartnerName
The optional delegate returns the name of one of the partner identity providers in the SAML configuration.
For example, if a configured partner identity provider is "https://ExampleIdentityProvider", this name must be specified to initiate SSO to this identity provider.
If multiple partner identity providers are configured, the partner name must be specified.
AssertionConsumerServicePath
The assertion consumer service path is the endpoint within the SAML authentication handler that receives SAML responses from partner identity providers.
The default is "/SAML/AssertionConsumerService".
SingleLogoutServicePath
The single logout service path is the endpoint within the SAML authentication handler that receives SAML logout messages from partner identity providers.
The default is "/SAML/SingleLogoutService".
ArtifactResolutionServicePath
The artifact resolution service path is the endpoint within the SAML authentication handler that receives SAML artifact resolutions messages from partner identity providers.
The default is "/SAML/ArtifactResolutionService".
LoginCompletionUrl
The optional delegate returns the URL to redirect to once SSO completes and if this URL hasn't been specified using a ReturnUrl query string.
The default is "/Identity/Account/ExternalLogin?handler=Callback".
LogoutCompletionUrl
The optional delegate returns the URL to redirect to once SLO completes and if this URL hasn't been specified using a ReturnUrl query string.
The default is "/".
ErrorUrl
The optional delegate returns the URL to redirect if SSO or SLO fails.
The default is "/Error".
SignInScheme
The sign-in scheme is responsible for persisting user's identity after successful authentication.
The default is "Identity.External".
SignOutScheme
The signout scheme is responsible for signout.
The default is "Identity.Application".
Events
The optional SamlAuthenticationEvents event delegates.
Authentication Properties
The SAML authentication handler recognizes the following AuthenticationProperties items during login and logout.
ConfigurationName
The optional configuration name identifies which SAML configuration to use when processing SSO and SLO requests for the current user.
It's only required if multiple SAML configurations exist (e.g. in a multi-tenanted environment).
If not specified, the ConfigurationName delegate is called.
PartnerName
The optional partner name specifies the name of one of the partner identity providers in the SAML configuration.
For example, if a configured partner identity provider is "https://ExampleIdentityProvider", this name must be specified in order to initiate SSO to this identity provider.
If multiple partner identity providers are configured, the partner name must be specified.
If not specified, the PartnerName delegate is called.
AuthnContext
The optional authentication context returned by the identity provider.
NameIDFormat
The optional name identifier format returned by the identity provider.
RelayState
The optional relay state returned by the identity provider.
Authentication Events
In addition to the ISamlServiceProviderEvents events, the SAML authentication handler supports the following events.
OnInitiateSso
OnInitiateSso is called prior to calling ISamlServiceProvider.InitiateSsoAsync.
The InitiateSsoAsync parameters may be modified if required.
Func<HttpContext, string, string, ISsoOptions, (string, string, ISsoOptions)> OnInitiateSso { get; set; }
OnInitiateSlo
OnInitiateSlo is called prior to calling ISamlServiceProvider.InitiateSloAsync.
The InitiateSloAsync parameters may be modified if required.
OnSendSlo
OnSendSlo is called prior to calling ISamlServiceProvider.SendSloAsync.
The SendSloAsync parameters may be modified if required.
OnError
OnError is called when an error occurs during SAML SSO or SLO.
Event Examples
The following example demonstrates setting SSO options prior to the call to ISamlServiceProvider.InitiateSsoAsync.
// Add SAML authentication services.
builder.Services.AddAuthentication().AddSaml(options =>
{
options.Events = new SamlAuthenticationEvents
{
OnInitiateSso = (httpContext, partnerName, relayState, ssoOptions) =>
{
ssoOptions = new SsoOptions
{
RequestedUserName = "[email protected]"
};
return (partnerName, relayState, ssoOptions);
}
};
});