Skip to content

SAML Logout Services

Single logout (SLO) involves several extensibility points. ILogoutRequestValidator validates a LogoutRequest that a service provider (SP) sends to IdentityServer. ISamlLogoutNotificationService decides which other SPs to notify, and calls ISaml2FrontChannelLogoutRequestBuilder to build one outbound LogoutRequest per SP. When all SPs have been handled, ISaml2SloResponseGenerator creates the LogoutResponse that goes back to the SP that started the logout. The state of the flow is kept in ISamlLogoutSessionStore.

Duende.IdentityServer.Saml.Validation.ILogoutRequestValidator

Section titled “Duende.IdentityServer.Saml.Validation.ILogoutRequestValidator”

Validates an incoming SAML LogoutRequest early in the SLO pipeline, before other service providers are notified.

public interface ILogoutRequestValidator
{
Task<LogoutRequestValidationResult> ValidateAsync(
ValidatedLogoutRequest request,
CancellationToken ct);
}
MethodDescription
ValidateAsyncValidate a LogoutRequest. request is the LogoutRequest validation context and ct is the cancellation token. Returns the validation result.

Result of LogoutRequest validation

MemberDescription
ValidatedRequestThe ValidatedLogoutRequest the result belongs to.
IsErrortrue when validation failed. Inherited from ValidationResult. Valid(...) sets it to false.
ErrorGets or sets the error. For this result, it’s the SAML status code of the failure (inherited).
ErrorDescriptionGets or sets the error description. It’s optional for this result (inherited).
SessionFoundIndicates whether a matching SAML session was found for the requesting SP. When false, the IdP should respond with Success without terminating the user’s IdP session (per SAML 2.0 Profiles §4.4).
Valid(validatedLogoutRequest)Creates a valid validation result
InValid(validatedLogoutRequest, saml2ErrorCode, errorDescription)Creates an invalid validation result. saml2ErrorCode is the error code (a Saml2 status code) and errorDescription is the error description.

Validated LogoutRequest context

MemberDescription
LogoutRequestThe parsed LogoutRequest
BindingIdentifier of binding used to receive the LogoutRequest
Saml2MessageThe raw inbound SAML message from the binding layer. Null when the request is reconstructed from stored state (e.g., in the callback endpoint).
RelayStateThe relay state to include in the response. When Saml2Message is present, this defaults to Saml2Message.RelayState.
Saml2SpThe resolved SAML Service Provider
SubjectThe current user
SessionIdThe current session ID
Saml2IdpEntityIdThe SAML entity ID of this IdP

LogoutRequest validator. The default implementation, LogoutRequestValidator, runs the following checks in order and stops at the first error. To customize a check, derive from the class and override its protected virtual method. Errors use SamlStatusCodes.Requester unless noted.

StepChecks
ValidateSpAsyncValidates the SP from the Issuer entity ID. The request has an issuer, the SP exists and is enabled, and it has at least one single logout URL.
ValidateSignatureTrustValidates that the LogoutRequest is signed (required per SAML spec). The request signature must be present and trusted.
ValidateVersionValidates that the LogoutRequest uses SAML version 2.0. Other versions fail with SamlStatusCodes.VersionMismatch.
ValidateDestinationValidates that the Destination matches the SLO endpoint URL. Signed requests must include a Destination per SAML Bindings 2.0. The comparison is case-insensitive.
ValidateNotOnOrAfterValidates that the NotOnOrAfter has not expired. It’s checked when present, allowing for the SP’s ClockSkew (or SamlOptions.DefaultClockSkew).
ValidateSessionAsyncValidates that the LogoutRequest’s NameID and SessionIndex match an active SAML session for the requesting SP. Per SAML 2.0 Core §3.7.1, the NameID identifies the principal and the SessionIndex identifies the specific session to terminate. This check applies when the user is signed in. The request needs a NameID that matches an active SAML session for the SP, and the SessionIndex (when present) must match.

If no user is signed in at IdentityServer, ValidateSessionAsync returns a valid result. If a user is signed in but no SAML session exists for the SP, or the SessionIndex doesn’t match, the result is valid with SessionFound set to false. In both cases IdentityServer responds with success and leaves the user’s session alone, without showing the logout page. The default validator has no replay protection for logout requests.

builder.Services.AddScoped<ILogoutRequestValidator, CustomLogoutRequestValidator>();

AddSaml() registers the default validator, so you only need to register your own to replace it.

Duende.IdentityServer.Saml.ISamlLogoutNotificationService

Section titled “Duende.IdentityServer.Saml.ISamlLogoutNotificationService”

Service for building SAML front-channel logout notifications. It builds the front-channel LogoutRequest messages IdentityServer sends to SAML service providers when a user logs out.

public interface ISamlLogoutNotificationService
{
Task<SamlLogoutNotificationResult> GetSamlFrontChannelLogoutsAsync(
LogoutNotificationContext context,
CancellationToken ct);
}
MethodDescription
GetSamlFrontChannelLogoutsAsyncBuilds the SAML messages needed for front-channel logout notification. context is the context for the logout notification and ct is the cancellation token. Returns the logout request messages that were generated and the number of service providers that were skipped.

Result of generating SAML front-channel logout notifications.

PropertyTypeDescription
MessagesIReadOnlyCollection<SamlLogoutRequestContext>The successfully generated logout request contexts. There is one entry per SP to notify.
SkippedCountintThe number of SPs that could not be notified.

Encapsulates the result of building a SAML LogoutRequest, including the binding-layer message and application-level metadata needed for response correlation. Namespace Duende.IdentityServer.Saml.Services.

PropertyTypeDescription
MessageOutboundSaml2MessageThe binding-layer message ready to be sent to the SP.
RequestIdstringThe SAML request ID (from the ID attribute) for correlating responses via InResponseTo.
SpEntityIdstringThe entity ID of the SP this request is destined for.

Default implementation of ISamlLogoutNotificationService that uses the new ISaml2FrontChannelLogoutRequestBuilder to build outbound LogoutRequest messages. The default implementation, Saml2LogoutNotificationService, builds a request for each SP session using ISaml2FrontChannelLogoutRequestBuilder. It skips the initiating SP, SPs that are unknown or disabled, SPs without a single logout URL or without an HTTP-Redirect logout endpoint, and SPs for which building the request fails. SPs skipped for any reason other than being the initiating SP are counted in SkippedCount; the initiating SP is skipped but not counted. Outbound logout requests support only HTTP-Redirect.

AddSaml() replaces any registration made before it, so register your implementation after AddSaml():

builder.Services.AddIdentityServer()
.AddSaml();
builder.Services.AddScoped<ISamlLogoutNotificationService, CustomSamlLogoutNotificationService>();

Duende.IdentityServer.Saml.Services.ISaml2FrontChannelLogoutRequestBuilder

Section titled “Duende.IdentityServer.Saml.Services.ISaml2FrontChannelLogoutRequestBuilder”

Builds outbound SAML 2.0 LogoutRequest messages for front-channel logout notifications. It builds the outbound LogoutRequest for one service provider and is called once per SP by the logout notification service.

public interface ISaml2FrontChannelLogoutRequestBuilder
{
Task<SamlLogoutRequestContext> BuildLogoutRequestAsync(
SamlServiceProvider serviceProvider,
string nameId,
string? nameIdFormat,
string sessionIndex,
string issuer,
CancellationToken ct);
}
ParameterDescription
serviceProviderThe SP to notify.
nameIdThe NameID value for the subject being logged out.
nameIdFormatOptional NameID format URI.
sessionIndexThe session index to include in the request.
issuerThe IdP entity ID (issuer).
ctCancellation token.

BuildLogoutRequestAsync builds a front-channel logout request for the given service provider. It returns a SamlLogoutRequestContext containing the message and correlation metadata.

The default builder, Saml2FrontChannelLogoutRequestBuilder, signs requests with the certificate from ISamlSigningService and sends them using HTTP-Redirect. It throws InvalidOperationException if the SP has no single logout URL or no HTTP-Redirect logout endpoint.

builder.Services.AddScoped<ISaml2FrontChannelLogoutRequestBuilder, CustomLogoutRequestBuilder>();

Duende.IdentityServer.Saml.ResponseHandling.ISaml2SloResponseGenerator

Section titled “Duende.IdentityServer.Saml.ResponseHandling.ISaml2SloResponseGenerator”

Response generator for SAML 2.0 Single Logout. It creates the LogoutResponse returned to the service provider that initiated single logout.

public interface ISaml2SloResponseGenerator
{
Task<Saml2FrontChannelResult> CreateSuccessResponse(
ValidatedLogoutRequest request,
CancellationToken ct);
Task<Saml2FrontChannelResult> CreatePartialLogoutResponse(
ValidatedLogoutRequest request,
CancellationToken ct);
}
MethodDescription
CreateSuccessResponseCreate a success LogoutResponse for a validated LogoutRequest. request is the validated logout request context and ct is the cancellation token. Returns the Saml2 front channel result containing the LogoutResponse.
CreatePartialLogoutResponseCreate a partial logout LogoutResponse indicating not all SPs successfully logged out. It reports a partial logout (SamlStatusCodes.PartialLogout). request is the validated logout request context and ct is the cancellation token. Returns the Saml2 front channel result containing the LogoutResponse with partial logout status.

Saml2FrontChannelResult (namespace Duende.IdentityServer.Saml.Endpoints.Results) is the result from a Saml2 endpoint that wraps a Saml2 message and should be handled by a front channel binding.

PropertyDescription
MessageContained Saml2 Message. It’s the OutboundSaml2Message.
ErrorError message if this result is an error. When it’s set, IdentityServer redirects to the error page instead of sending Message.
SpEntityIdEntity Id of Sp as received in incoming message, may not be validated.
GeneratedNameIdThe NameID that was generated for the subject in this response. Null when the result is an error.

Both methods create a LogoutResponse, set InResponseTo to the request ID, use the IdP entity ID from ISaml2IssuerNameService as the issuer, and sign the response with the certificate from ISamlSigningService. The destination is the SP’s HTTP-Redirect single logout URL, falling back to the request’s issuer. If neither is available, they throw InvalidOperationException. CreateSuccessResponse uses the status SamlStatusCodes.Success. CreatePartialLogoutResponse uses SamlStatusCodes.Success with a nested SamlStatusCodes.PartialLogout status. The response’s RelayState and binding are copied from the request.

IdentityServer calls CreateSuccessResponse only when every notified SP responded with success and SkippedSpCount of the logout session is 0. In all other cases, including when the logout session can’t be found, it calls CreatePartialLogoutResponse. The logout session is removed afterward.

The interface controls response generation only. Logout state is stored by ISamlLogoutSessionStore.

builder.Services.AddScoped<ISaml2SloResponseGenerator, CustomSloResponseGenerator>();

AddIdentityServer() registers the default Saml2SloResponseGenerator, so you only need to register your own if you want to replace it. To customize both response methods at once, derive from the default class and override their shared CreateResponseAsync(ValidatedLogoutRequest, string statusCode, string? subStatusCode, string? statusMessage, CancellationToken) method, which builds a LogoutResponse and wraps it in a Saml2FrontChannelResult.