Skip to content

SAML Middleware - Identity Provider

The SAML middleware provides support for web applications acting as the SAML identity provider (IdP), and participating in SAML single sign-on (SSO) and single logout (SLO).

Both IdP-initiated and SP-initiated SSO and SLO are supported.

Note

SAML API calls within the application should not be made as SSO and SLO are managed by the SAML middleware.

Initialization

The following code adds the SAML services and SAML middleware.

// Add SAML services.
builder.Services.AddSaml(builder.Configuration.GetSection("SAML"));

// Add SAML middleware services.
builder.Services.AddSamlMiddleware(options =>
{
    options.PartnerName = (httpContext) => builder.Configuration["PartnerName"];
});

The following code enables the SAML middleware.

// Use SAML middleware.
app.UseSaml();

Initiating SSO

To initiate SSO from the IdP, redirect to InitiateSingleSignOnPath.

public ActionResult SingleSignOn()
{
    return Redirect(SamlMiddlewareDefaults.InitiateSingleSignOnPath);
}

Initiating SLO

To initiate SLO from the IdP, redirect to InitiateSingleLogoutPath.

In this example, the returnUrl distinguishes between IdP-initiated (i.e. no returnUrl) and SP-initiated SLO (i.e. a returnUrl). 

public ActionResult SingleLogout()
{
    return Redirect(SamlMiddlewareDefaults.InitiateSingleLogoutPath);
}

Middleware Options

The SamlMiddlewareOptions class supplies options to the SAML middleware.

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 service providers in the SAML configuration.

For example, if a configured partner service provider is "https://ExampleServiceProvider", this name must be specified in order to initiate SSO to this service provider.

If multiple partner service providers are configured, the partner name must be specified.

RelayState

The optional delegate returns the relay state to include when initiating SSO to the partner service provider.

The relay state specifies the target URL the service provider should redirect to once SSO completes successfully.

Its purpose is to support deep web links.

If not specified, the service provider determines which page to display after SSO completes. Typically, this will be the home page.

InitiateSingleSignOnPath

The initiate single sign-on path is the endpoint within the SAML middleware that initiates SSO.

The application may redirect to this endpoint for IdP-initiated SSO.

The default is "/SAML/InitiateSingleSignOn".

InitiateSingleLogoutPath

The initiate single logout path is the endpoint within the SAML middleware that initiates SLO.

The application may redirect to this endpoint for IdP-initiated SLO.

The default is "/SAML/InitiateSingleLogout".

SingleSignOnServicePath

The single sign-on service path is the endpoint within the SAML middleware that receives SAML authn requests from partner service providers.

The default is "/SAML/SingleSignOnService".

SingleSignOnServiceCompletionPath

The single sign-on service completion path is the endpoint within the SAML middleware that completes SSO.

The application redirects to this endpoint once the used is authenticated.

The default is "/SAML/SingleSignOnServiceCompletion".

SingleLogoutServicePath

The single logout service path is the endpoint within the SAML middleware that receives SAML logout messages from partner service providers.

The default is "/SAML/SingleLogoutService".

SingleLogoutServiceCompletionPath

The single logout service completion path is the endpoint within the SAML middleware that completes SLO.

The application redirects to this endpoint once the used is logged off.

The default is "/SAML/SingleLogoutServiceCompletion".

ArtifactResolutionServicePath

The artifact resolution service path is the endpoint within the SAML authentication handler that receives SAML artifact resolutions messages from partner service providers.

The default is "/SAML/ArtifactResolutionService".

LoginUrl

The optional delegate returns the URL to redirect to for login if the user isn't authenticated.

The application should login the user.

The default is "/Identity/Account/Login".

LogoutUrl

The optional delegate returns the URL to redirect to for logout if the user is authenticated.

The application should logout the user.

The default is "/Identity/Account/Logout".

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".

ConfigurationNameParameter

The optional configuration name query string parameter specifies 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).

This is an alternative to the ConfigurationName delegate.

The default is "ConfigurationName".

PartnerNameParameter

The optional partner name query string parameter specifies the name of one of the partner service providers in the SAML configuration.

For example, if a configured partner service provider is "https://ExampleServiceProvider", this name must be specified in order to initiate SSO to this service provider.

If multiple partner service providers are configured, the partner name must be specified.

This is an alternative to the PartnerName delegate.

The default is "PartnerName".

RelayStateParameter

The optional relay state query string parameter specifies the relay state to include when initiating SSO to the partner service provider.

The relay state specifies the target URL the service provider should redirect to once SSO completes successfully.

Its purpose is to support deep web links.

If not specified, the service provider determines which page to display after SSO completes. Typically, this will be the home page.

This is an alternative to the RelayState delegate.

The default is "RelayState".

CorrelationIDParameter

The correlation ID query string parameter identifies the SAML request to respond to.

The default is "CorrelationID".

ReturnUrlParameter

The return URL query string parameter specifies the URL to return to once SSO or SLO completes.

The default is "ReturnUrl".

Events

The optional event delegates.

Middleware Events

In addition to the ISamlIdentityProviderEvents events, the SAML middleware supports the following events.

OnInitiateSso

OnInitiateSso is called prior to calling ISamlIdentityProvider.InitiateSsoAsync.

The InitiateSsoAsync parameters may be modified if required.

Func<HttpContext, string, string, IList<SamlAttribute>, string, string, (string, string, IList<SamlAttribute>, string, string)> OnInitiateSso { get; set; }

OnSendSso

OnSendSso is called prior to calling ISamlIdentityProvider.SendSsoAsync.

The SendSsoAsync parameters may be modified if required.

Func<HttpContext, string, IList<SamlAttribute>, string, (string, IList<SamlAttribute>, string, Status)> OnSendSso { get; set; }

OnInitiateSlo

OnInitiateSlo is called prior to calling ISamlIdentityProvider.InitiateSloAsync.

The InitiateSloAsync parameters may be modified if required.

Func<HttpContext, string, string, (string, string)> OnInitiateSlo { get; set; }

OnSendSlo

OnSendSlo is called prior to calling ISamlIdentityProvider.SendSloAsync.

The SendSloAsync parameters may be modified if required.

Func<HttpContext, string, string> OnSendSlo { get; set; }

OnError

OnError is called when an error occurs during SAML SSO or SLO.

Func<HttpContext, Exception, bool> OnError { get; set; }

Event Examples

The following example demonstrates setting the authentication context prior to the call to ISamlIdentityProvider.InitiateSsoAsync.

// Add SAML middleware services.
builder.Services.AddSamlMiddleware(options =>
{
    options.Events.OnInitiateSso = (httpContext, partnerName, userID, attributes, relayState, authnContext) =>
    {
        return (partnerName, userID, attributes, relayState, AuthnContextClasses.Password);
    };
});