Align with products commit 2249a0935853b79a8453f1baab979f21b4b7255e

Author: maartenba

astro/src/content/docs/identityserver/saml/concepts.md

@@ -1,7 +1,7 @@
 ---
 title: "SAML 2.0 Concepts"
 description: Core SAML 2.0 concepts you need to understand when integrating with IdentityServer's SAML 2.0 Identity Provider feature.
-date: 2026-03-23
+date: 2026-05-15
 sidebar:
   label: Concepts
   order: 5
@@ -58,7 +58,9 @@ sequenceDiagram
     SP->>User: Grant access (session created)
 ```
 
-In IdentityServer, you register each SP using a `SamlServiceProvider` configuration object. This tells IdentityServer the SP's entity identifier, where to deliver assertions (the Assertion Consumer Service URL), and how to communicate. See the [Service Provider Store](/identityserver/saml/service-providers.md) and the [SamlServiceProvider model](/identityserver/saml/configuration.md#samlserviceprovider-model) for details.
+In IdentityServer, you register each SP using a `SamlServiceProvider` configuration object. This tells IdentityServer the SP's entity identifier, where to deliver assertions (the Assertion Consumer Service URL) and how to communicate. See the [Service Provider Store](/identityserver/saml/service-providers.md) and the [SamlServiceProvider model](/identityserver/saml/configuration.md#samlserviceprovider-model) for details.
+
+Duende IdentityServer can also act as a SAML Service Provider itself, consuming assertions from an external SAML IdP. See [Identity Provider and Service Provider](/identityserver/saml/idp-and-sp.md) for an overview of both roles.
 
 ## Metadata
 
@@ -127,9 +129,15 @@ The most common use of RelayState is deep linking: the SP encodes the URL the us
 
 IdentityServer preserves RelayState automatically through the authentication flow. The maximum permitted length is controlled by `SamlOptions.MaxRelayStateLength` (default: `80` bytes). See [SamlOptions](/identityserver/saml/configuration.md#samloptions).
 
-## Single Logout
+## Single Logout (SLO)
+
+SAML Single Logout (SLO) is a protocol for coordinating session termination across an entire federation.
+
+When a user authenticates via SAML, they establish a session at the IdP and a separate local session at each SP they visit. Logging out of one application ends only that application's local session. Without SLO, the user still has active sessions at every other SP they visited, and anyone with access to the browser can continue using those applications. SLO solves this by letting a single logout action propagate to all SPs in the federation.
 
-SAML Single Logout (SLO) is a protocol for coordinating session termination across an entire federation. When a user logs out at one SP or at the IdP, the IdP sends `LogoutRequest` messages to every other SP where that user has an active session, then waits for each SP to confirm.
+### SP-Initiated SLO
+
+The most common flow starts at an SP. When the user clicks "Log out" in an application, the SP sends a `LogoutRequest` to the IdP. The IdP ends the user's session, then sends `LogoutRequest` messages to every other SP where the user has an active session. Each SP terminates its local session and responds with a `LogoutResponse`. Once all SPs have responded (or timed out), the IdP sends a final `LogoutResponse` back to the originating SP.
 
 ```mermaid
 sequenceDiagram
@@ -149,8 +157,24 @@ sequenceDiagram
     IdP-->>SP_A: LogoutResponse
 ```
 
-SLO is powerful in theory but complex in practice. Reliable SLO requires the IdP to track every active session across all SPs. Partial failures are common: an SP may be unreachable, slow to respond, or the user may close the browser before all notifications complete. These partial failures create ambiguous states where some SPs consider the session terminated and others do not.
+### IdP-Initiated SLO
+
+The IdP can also initiate logout without waiting for an SP to start the flow. This happens when an administrator ends a session, a session timeout occurs, or the IdP detects a security event. The IdP sends `LogoutRequest` messages directly to all SPs with active sessions for that user. There is no originating SP to return a final `LogoutResponse` to.
+
+### Front-Channel Logout
+
+IdentityServer uses front-channel logout, which means logout notifications travel through the user's browser via redirects. The IdP redirects the browser to each SP's SLO endpoint in sequence, and each SP terminates its local session before the browser is redirected onward. This approach is simpler to implement than back-channel (server-to-server) logout, but it requires the user's browser to remain open and active throughout the logout sequence. Back-channel logout is not supported.
+
+### Partial Logout
+
+Not all SPs may respond successfully. An SP may be unreachable, slow to respond, or the user may close the browser before the sequence completes. IdentityServer tracks which SPs are expected to respond and can return a "partial logout" status when some SPs do not confirm. This is a normal outcome in real-world deployments, not an error condition.
+
+### Session Tracking
+
+For SLO to work, the IdP must know which SPs have active sessions for a given user. IdentityServer tracks this automatically as users authenticate at each SP. You can customize the storage backend by implementing [`ISamlLogoutSessionStore`](/identityserver/saml/extensibility.md#isamllogoutsessionstore).
+
+### Timeouts and Edge Cases
 
-For this reason, many deployments supplement SLO, or replace it entirely, with short session lifetimes and per-application logout as a simpler fallback.
+If an SP is unreachable or the user closes the browser mid-flow, the logout sequence may not complete for all SPs. Short session lifetimes and per-application logout are common supplements to SLO in deployments where reliability matters more than protocol completeness. You can tune logout timeout behavior via `SamlOptions` to balance user experience against thoroughness.
 
 In IdentityServer, you configure SLO per SP by setting `SamlServiceProvider.SingleLogoutServiceUrl`. IdentityServer then sends front-channel logout notifications to all SPs with a configured SLO endpoint when a user's session ends. See the [logout endpoint](/identityserver/saml/endpoints.md#logout-endpoint) and [`ISamlLogoutNotificationService`](/identityserver/saml/extensibility.md#isamllogoutnotificationservice) for customization options.

astro/src/content/docs/identityserver/saml/configuration.md

@@ -1,7 +1,7 @@
 ---
 title: "SAML Configuration"
-description: Configuration options and models for the SAML 2.0 Identity Provider feature, including SamlOptions, Saml2Options, and SamlServiceProvider settings.
-date: 2026-03-02
+description: Configuration options and models for the SAML 2.0 Identity Provider feature, including SamlOptions and SamlServiceProvider settings.
+date: 2026-05-15
 sidebar:
   label: Configuration
   order: 10
@@ -21,20 +21,20 @@ builder.Services.AddIdentityServer()
     .AddSaml();
 ```
 
-`AddSaml()` registers all SAML services and six SAML endpoints, enabling five of them by default. The IdP-initiated SSO endpoint requires explicit opt-in (see [Enabling IdP-Initiated SSO](#enabling-idp-initiated-sso) below). It can be called with no arguments when all Service Provider configuration is managed via the admin API, or with an options callback to configure protocol-level settings via `Saml2Options`:
+`AddSaml()` registers all SAML services and endpoints, enabling most of them by default. The IdP-initiated SSO endpoint requires explicit opt-in (see [Enabling IdP-Initiated SSO](#enabling-idp-initiated-sso) below). It can be called with no arguments when all Service Provider configuration is managed via the admin API, or with an options callback to configure protocol-level settings:
 
 ```csharp
 builder.Services.AddIdentityServer()
-    .AddSaml(saml2 =>
+    .AddSaml(saml =>
     {
-        saml2.EntityId = "https://idp.example.com/saml";
-        saml2.Metadata.CacheDuration = TimeSpan.FromHours(1);
+        saml.EntityId = "https://idp.example.com/saml";
+        saml.Metadata.CacheDuration = TimeSpan.FromHours(1);
     });
 ```
 
 ## SamlOptions
 
-`SamlOptions` controls the global behavior and policy of the SAML 2.0 Identity Provider: how claims are mapped to SAML attributes, how assertions are signed, how NameIDs are resolved, and what tolerances apply to timestamps and request lifetimes. It is distinct from `Saml2Options`, which handles protocol plumbing (entity ID, endpoint paths, metadata generation).
+`SamlOptions` controls the global behavior and policy of the SAML 2.0 Identity Provider: how claims are mapped to SAML attributes, how assertions are signed, how NameIDs are resolved, and what tolerances apply to timestamps and request lifetimes.
 
 Access `SamlOptions` via `IdentityServerOptions.Saml` when calling `AddIdentityServer()`:
 
@@ -53,7 +53,7 @@ Use `SamlOptions` when you need to set defaults that apply across all Service Pr
 Available options:
 
 * **`MetadataValidityDuration`**
-  IdentityServer-layer setting that, if set, causes the metadata document to include a `validUntil` attribute. Defaults to 7 days. For most deployments, prefer configuring `Saml2Options.Metadata.ExpiryDuration` via the `AddSaml()` callback instead, which operates at the protocol layer and defaults to 5 days.
+  IdentityServer-layer setting that, if set, causes the metadata document to include a `validUntil` attribute. Defaults to 7 days.
 
 * **`WantAuthnRequestsSigned`**
   When `true`, the IdP requires all AuthnRequests to be signed. Defaults to `false`.
@@ -95,6 +95,21 @@ Available options:
 * **`UserInteraction`**
   Configures SAML endpoint paths. See [SamlUserInteractionOptions](#samluserinteractionoptions) below.
 
+### Error Inspector Callbacks
+
+These three optional callbacks let you observe and react to errors that occur while IdentityServer parses or validates incoming SAML messages. They are particularly useful when you are debugging interoperability issues with a specific SP, because they give you access to the raw XML and the error details before IdentityServer returns a failure response.
+
+None of these callbacks are required. When they are not set, IdentityServer handles errors using its default behavior.
+
+* **`AuthnRequestErrorInspector`**
+  A callback invoked when an error occurs while parsing or validating an incoming `AuthnRequest`. It receives the raw XML and the error details, so you can log the message, inspect the failure reason, or take corrective action on a per-SP basis. This is useful for diagnosing SP configuration problems such as malformed request signatures or unexpected XML structure.
+
+* **`LogoutRequestErrorInspector`**
+  A callback invoked when an error occurs while parsing or validating an incoming `LogoutRequest`. It works the same way as `AuthnRequestErrorInspector` but applies to SLO flows. Use it to investigate cases where an SP's logout request is rejected unexpectedly.
+
+* **`LogoutResponseErrorInspector`**
+  A callback invoked when an error occurs while processing an incoming `LogoutResponse` from an SP during Single Logout (SLO). It lets you handle cases where an SP returns a malformed or unexpected response, for example to log the raw XML for later analysis or to suppress the error for a known non-compliant SP.
+
 ### Default Claim Mappings
 
 The default `DefaultClaimMappings` dictionary maps common OIDC claim types to SAML 2.0 attribute
@@ -140,50 +155,6 @@ The full URL for each endpoint is formed by combining the base URL of the Identi
 the `Route` prefix and the individual path suffix. For example, the metadata endpoint is available
 at `https://your-idp.example.com/saml/metadata` by default.
 
-## Saml2Options
-
-`Saml2Options` is the protocol-level configuration class for the SAML 2.0 IdP. While `SamlOptions` controls behavior and policy (claim mappings, assertion lifetime, signing defaults), `Saml2Options` controls the SAML protocol plumbing: the IdP's entity identity, which endpoint paths and HTTP bindings are active, and how the metadata document is generated and cached.
-
-It lives in the `Duende.IdentityServer.Saml.Configuration` namespace and is configured via the `AddSaml()` options callback:
-
-```csharp
-builder.Services.AddIdentityServer()
-    .AddSaml(saml2 =>
-    {
-        saml2.EntityId = "https://idp.example.com/saml";
-        saml2.Endpoints.SingleSignOnServicePath = "/saml/sso";
-        saml2.Metadata.CacheDuration = TimeSpan.FromHours(1);
-    });
-```
-
-Use `Saml2Options` when you need to control the IdP's published identity (entity ID), the URL paths it listens on, or the shape of the metadata document it serves to Service Providers. Most deployments do not need to set `EntityId` explicitly; the default (`{host}/saml`) is suitable for standard configurations.
-
-Available options:
-
-* **`EntityId`** (`string?`)
-  The SAML entity ID of this IdP. If not set, IdentityServer derives it from the host URL combined with `EntityIdPath` (resulting in `{host}/saml` by default). Most deployments do not need to set this explicitly. Defaults to `null`.
-
-* **`EntityIdPath`** (`string`)
-  Path component appended to the OIDC issuer URL when `EntityId` is not explicitly set. Defaults to `/saml`.
-
-* **`Endpoints.SingleSignOnServicePath`** (`string`)
-  URL path for the SSO endpoint. Defaults to `/saml/signin`.
-
-* **`Endpoints.MetadataPath`** (`string`)
-  URL path for the metadata endpoint. Defaults to `/saml/metadata`.
-
-* **`Endpoints.SingleSignOnServiceBindings`** (`ICollection<string>`)
-  HTTP bindings accepted by the SSO endpoint. Defaults to both HTTP-Redirect and HTTP-POST.
-
-* **`Metadata.Enabled`** (`bool`)
-  Whether the metadata endpoint is active. Defaults to `true`.
-
-* **`Metadata.CacheDuration`** (`TimeSpan`)
-  How long clients should cache the metadata document. Defaults to 1 hour.
-
-* **`Metadata.ExpiryDuration`** (`TimeSpan`)
-  Protocol-layer setting that controls how far in the future the metadata `validUntil` attribute is set. Defaults to **5 days**. This is the preferred way to configure metadata expiry. Set it via the `AddSaml()` callback on `Saml2Options`. It is distinct from `SamlOptions.MetadataValidityDuration` (the IdentityServer-layer property accessed via `IdentityServerOptions.Saml`), which defaults to 7 days. When both are configured, `Saml2Options.Metadata.ExpiryDuration` takes effect at the protocol level.
-
 ## SamlServiceProvider Model
 
 `SamlServiceProvider` represents a registered SAML 2.0 Service Provider. Each SP has its own entity ID, ACS endpoints, signing certificates, and claim configuration. SPs can be registered statically in code or managed dynamically via a custom store.
@@ -229,11 +200,11 @@ Available options:
 * **`SingleLogoutServiceUrl`** (`SamlEndpointType?`)
   SP's Single Logout Service endpoint, expressed as a `SamlEndpointType` with a `Location` (Uri) and `Binding` (SamlBinding). Required for SLO support. Defaults to `null`. See [SamlEndpointType](#samlendpointtype) below.
 
-* **`RequireSignedAuthnRequests`** (`bool`)
-  When `true`, unsigned AuthnRequests from this SP are rejected. Defaults to `false`.
+* **`RequireSignedAuthnRequests`** (`bool?`)
+  When `true`, unsigned AuthnRequests from this SP are rejected. When `null`, falls back to the global `SamlOptions.WantAuthnRequestsSigned` default. Defaults to `null`.
 
-* **`SigningCertificates`** (`ICollection<X509Certificate2>?`)
-  Certificates used to verify SP-signed messages. Defaults to `null`.
+* **`Certificates`** (`ICollection<ServiceProviderCertificate>?`)
+  Certificates associated with this SP, with use annotations indicating whether each certificate is used for signature verification, encryption, or both. Replaces the old `SigningCertificates` property. See [ServiceProviderCertificate](#serviceprovidercertificate) below. Defaults to `null`.
 
 * **`AllowIdpInitiated`** (`bool`)
   When `true`, IdP-initiated SSO is allowed for this SP. Defaults to `false`.
@@ -347,6 +318,25 @@ AssertionConsumerServiceUrls = new List<IndexedEndpoint>
 }
 ```
 
+### ServiceProviderCertificate
+
+`ServiceProviderCertificate` pairs an X.509 certificate with a use annotation that tells IdentityServer how to apply it for a given SP. Use it to configure signature verification certificates, encryption certificates, or certificates that serve both purposes.
+
+Properties:
+
+* **`Certificate`** (`X509Certificate2`): The X.509 certificate. Required.
+* **`Use`** (`KeyUse`): How the certificate is used. Defaults to `KeyUse.Signing`. See [KeyUse](#keyuse) below.
+
+### KeyUse
+
+`KeyUse` is a flags enum that controls how a `ServiceProviderCertificate` is applied.
+
+| Value | Description |
+|---|---|
+| `Signing` | Used to verify signatures on messages from this SP. |
+| `Encryption` | Used to encrypt assertions sent to this SP. |
+| `Both` | Used for both signature verification and encryption. Equivalent to `Signing \| Encryption`. |
+
 ## Enabling IdP-Initiated SSO
 
 IdP-initiated SSO is disabled by default. To enable it, set the endpoint option and configure

astro/src/content/docs/identityserver/saml/endpoints.md

@@ -1,7 +1,7 @@
 ---
 title: "SAML Endpoints"
 description: Details of the SAML 2.0 protocol endpoints registered by IdentityServer, including metadata, sign-in, logout, and IdP-initiated SSO.
-date: 2026-03-02
+date: 2026-05-15
 sidebar:
   label: Endpoints
   order: 30
@@ -89,8 +89,12 @@ Enable it only for Service Providers that explicitly require it.
 
 Handles incoming SAML Single Logout (SLO) requests from Service Providers. The SP sends a SAML
 `LogoutRequest` message to this endpoint. IdentityServer processes the request, terminates the
-user's IdentityServer session, and sends front-channel logout notifications to other registered
-SPs.
+user's IdentityServer session, and coordinates logout across all other SPs.
+
+IdentityServer tracks which SPs have active sessions for the user. After receiving a `LogoutRequest`,
+it sends `LogoutRequest` messages to all other SPs with active sessions. It then collects their
+responses and, if some SPs do not respond or return an error, returns a partial logout status to the
+originating SP to indicate that not all sessions were successfully terminated.
 
 ## Logout Callback Endpoint
 
@@ -100,6 +104,10 @@ SPs.
 Processes SAML `LogoutResponse` messages returned by Service Providers after they have processed a
 logout notification from IdentityServer. This endpoint completes the SAML SLO round-trip.
 
+As each SP returns a `LogoutResponse`, IdentityServer records the result. If not all SPs with active
+sessions have responded by the time the logout flow completes, IdentityServer returns a partial
+logout status to the originating SP to indicate that some sessions may still be active.
+
 :::note
 SAML Single Logout is inherently complex: the process requires coordinated session termination across every SP that participated in the user's session. Partial failures are common. An SP may be unreachable, slow to respond, or the user may close the browser before all notifications complete, leaving some SPs with an active session while others consider the session terminated. Many deployments supplement SLO with short session lifetimes as a simpler fallback. See [Single Logout](/identityserver/saml/concepts.md#single-logout) for more background.
 :::