Single Logout | SAML2P Documentation

The Rock Solid Knowledge SAML Service Provider (SP) component supports two SAML Single Logout (SLO) flows:

SP-initiated SLO where the SP can initiate single logout for all parties in the current session (other SPs).
IdP-initiated SLO where the IdP sends a logout request to all the service providers in the current session

This page covers the SLO implementation details. For a high-level overview of SAML SLO, check out our article, The Challenge of Building SAML Single Logout.

SLO Configuration Options

You must set the following configuration options to support SLO in your Service Provider.

IdentityProviderOptions.SingleLogoutEndpoint: This is the identity provider's SLO endpoint where the SAML Logout requests and responses will be sent to
SignedOutCallbackPath: This is your SLO endpoint, where the IdP will send logout requests and responses to

Optional configuration includes:

SignOutScheme: The authentication scheme to use for SignOut. This should be the main cookie that you sign the user into. The user's unique identifier (NameID) is required for the SAML SLO protocol, which will be extracted from this cookie. Defaults to the specified SignInScheme config option since Rsk.Saml v5.3.0. Note that prior to Rsk.Saml v5.3.0, this config must be explicitly set
NameIdClaimType: This is the claim type of the logged-in user's NameID. This claim type is searched for in the SignOutScheme when generating logout requests and included in the request. It is also used for validating incoming logout requests. Defaults to http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier
IdPSessionIndexClaimType: This is the claim type of the IdP's session index. When null or empty, SessionIndex will be excluded from logout requests. When set to a value, this claim type is searched for in the SignOutScheme when generating logout requests. Defaults to null
RequireAuthenticatedUserForLogoutRequests: Indicates if an authenticated user is required for logout requests. When true, incoming logout request validation will fail if a user is not currently signed in. Defaults to false

Check out the SP configuration options for more details.

.AddSaml2p("saml2p", options =>
{
    // Other configuration code removed for brevity

    // IdP's SLO endpoint
    options.IdentityProviderOptions = new IdpOptions
    {
        SingleLogoutEndpoint = new SamlEndpoint("https://idp-slo", SamlBindingTypes.HttpRedirect)
    };

    // your SLO endpoint
    options.SignedOutCallbackPath = "/saml-signout";

    /* Optional */
    options.SignOutScheme = "idsrv";
    options.NameIdClaimType = "sub";

    /* Optional - SP-initiated only */
    options.IdPSessionIndexClaimType = "idPSessionIndex";

    /* Optional - IdP-initiated only */
    options.RequireAuthenticatedUserForLogoutRequests = true;
});

Trigger SP-Initiated SLO

To trigger logout, you simply need to call ASP.NET Core signout functionality on the authentication scheme. This should be the main cookie that you sign the user into.

public IActionResult Logout()
{
    return SignOut(new AuthenticationProperties { RedirectUri = "/" }, "idsrv", "saml2p");
}

Here, the "idsrv" is the local authentication scheme the user is signed into and "saml2p" is the external SAML authentication scheme.

When SignOut is called, ASP.NET Core will clear the local cookie and initiate the external SAML logout. The SAML authentication middleware will send a SAML logout request to the partner IdP. Once signout is completed, the user will be redirected to the path specified as the RedirectUri.

The SAML logout request must contain the Name ID of the user requesting logout. We get the current user from the cookie you specify as the SignoutScheme in your startup configuration. This means that the user must be signed in when SAML logout is initiated.

The ASP.NET Core SignOut method can take multiple schemes to process sequentially. ASP.NET Core will generate the logout requests for all the provided schemes before executing them. Using this approach avoids any execution order issues between local and external signouts.

Determine SignoutScheme

The SAML logout request needs to contain the Name ID of the currently signed-in user. This is extracted from the given SignOutScheme configuration option. SAML logout will fail with the exception "No authenticated user" if an incorrect SignOutScheme is provided or the user is not currently signed in.

The SignOutScheme must be the main cookie you are signing the user into. If you are using IdentityServer, the SignOutScheme must be the main authentication cookie ("idsrv") instead of the temporary external cookie ("idsrv.external").

If you are using ASP.NET Identity, it's important to note that ASP.NET Identity brings its own cookie handlers and sets the default scheme to "Identity.Application".

You can also check the browser cookie cache to figure out your main authentication scheme.

External Logout Within IdentityServer

We recommend reading the IdentityServer External Logout documentation for more details on how to determine the identity provider to sign out and state management after redirecting back from the identity provider.

Handle IdP-Initiated SLO

In this scenario, the IdP sends you a SAML logout request. Our SAML Service Provider component can handle incoming SAML logout requests out-of-the-box.

When we receive a valid SAML logout request, we end the user session by deleting the cookie specified as the SignoutScheme, and return a SAML logout response to the identity provider.

The incoming logout request contains the NameID format of the user requesting logout at the IdP. This NameID needs to be validated against the currently signed-in user in your application. If no user is currently authenticated in your application, the request validation will fail unless the RequireAuthenticatedUserForLogoutRequests configuration option is set to false.

Previous Next