Skip to content

Update SAML documentation #1084

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
maartenba wants to merge 10 commits into
base: release/is-v8.0
Choose a base branch
from
Open

Update SAML documentation #1084

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
10 commits
Select commit Hold shift + click to select a range
48f8ef6
Created distinct `/reference/vX` folders and ported API changes from …
khalidabuhakmeh Apr 28, 2026
838144e
Add v8 changes from products repo and include IdentityServer4 to v8 u…
maartenba Apr 28, 2026
3c5bd7e
Additional reference docs updates after cross-checking against product
maartenba Apr 30, 2026
0e82c76
Align SAML with products commit 5777b1ece2af0aa7f2270e08050ffa3a24bbd6da
maartenba May 5, 2026
21c08bf
Address PR #1084 review feedback: remove InCommon example, trim backw…
maartenba May 5, 2026
78f029f
Apply wcabus suggestions: clarify AllowedScopes description, add note…
maartenba May 5, 2026
29264e9
Fix ISamlSigninStateStore rationale: cookies work fine in load-balanc…
maartenba May 5, 2026
c9d2d9b
Address bhazen review feedback: remove platform-only APIs (ISamlServi…
maartenba May 6, 2026
fd18777
Merge branch 'release/is-v8.0' into v8-saml
maartenba May 6, 2026
0564e8a
Align with products commit 2249a0935853b79a8453f1baab979f21b4b7255e
maartenba May 15, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
110 changes: 93 additions & 17 deletions astro/src/content/docs/identityserver/saml/concepts.md
View file
Open in desktop

Large diffs are not rendered by default.

215 changes: 161 additions & 54 deletions astro/src/content/docs/identityserver/saml/configuration.md
View file
Open in desktop

Large diffs are not rendered by default.

20 changes: 14 additions & 6 deletions astro/src/content/docs/identityserver/saml/endpoints.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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
Expand Down Expand Up @@ -61,7 +61,7 @@ Service Provider's Assertion Consumer Service (ACS) URL using the configured bin

**Path**: `/saml/idp-initiated`
**Methods**: GET, POST
**Enabled by default**: No — requires explicit opt-in
**Enabled by default**: No (requires explicit opt-in)

Supports IdP-initiated SSO flows, where the IdP starts the authentication without receiving an
`AuthnRequest` from the SP. The SP must have `AllowIdpInitiated = true` set in its
Expand Down Expand Up @@ -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
Copy link
Copy Markdown
Contributor

@bhazen bhazen May 15, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This also handles logout responses from Service Providers. After we send them a Logout Request they are to send a response and the response back to the initiating SP, at least in an SP-initiated logout, is based upon if all the SPs in the session returned a success response.

Copy link
Copy Markdown
Contributor

@bhazen bhazen May 15, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Oh, maybe the next paragraph covers this well enough? I'll leave that up to your judgement.

`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

Expand All @@ -100,8 +104,12 @@ SPs.
Processes SAML `LogoutResponse` messages returned by Service Providers after they have processed a
Copy link
Copy Markdown
Contributor

@bhazen bhazen May 15, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think it's a bit misleading to say this endpoint process the LogoutResponse since it doesn't receive them directly. The logout endpoint receives them and this endpoint is processing the result of all the responses.

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: it 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 it 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.
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.
:::

## Customizing Endpoint Paths
Expand All @@ -122,4 +130,4 @@ builder.Services.AddIdentityServer(options =>
});
```

See [SAML Configuration](/identityserver/saml/configuration/) for full path option documentation.
See [SamlUserInteractionOptions](/identityserver/saml/configuration.md#samluserinteractionoptions) for full path option documentation.
Loading