Add "SAML 2.0 Concepts" documentation and update SAML-related configuration and endpoint references.#1041
Open
Add "SAML 2.0 Concepts" documentation and update SAML-related configuration and endpoint references.#1041
Conversation
…ration and endpoint references.
khalidabuhakmeh
approved these changes
Mar 23, 2026
bhazen
reviewed
Mar 24, 2026
Contributor
bhazen
left a comment
bhazen
left a comment
There was a problem hiding this comment.
One general comment on a section and one FYI
|
|
||
| ## Assertions | ||
|
|
||
| An assertion is the central data structure in SAML. It is a digitally signed XML document that carries claims about a user from the Identity Provider to the Service Provider. Think of it as the SAML equivalent of a JWT in OpenID Connect — everything else in the protocol exists to produce, transport, and validate assertions. |
Contributor
There was a problem hiding this comment.
While it is best practice to sign either the assertion, the response, or both they are not always signed. The assertion is only part of the XML document. It's probably more accurate to say the Assertion carries attributes.
It's more accurate to say it is the equivalent of an ID token in OpenID Connect. JWT here to some may imply JWT Bearer/access token and assertions are not that - they're a form of an identity assertion.
| * **Attribute Statement**: carries user properties such as email address, roles, group memberships, and department. | ||
| * **Conditions**: constrain where and when the assertion is valid. `NotBefore` and `NotOnOrAfter` define a time window (typically minutes), and `AudienceRestriction` limits which recipients can accept it. | ||
|
|
||
| The Identity Provider signs the assertion with its private key. The Service Provider validates the signature before trusting any claims inside. IdentityServer builds assertions automatically when it processes a SAML sign-in request. You control what attributes appear in assertions via claim mappings — see [`SamlOptions.DefaultClaimMappings` and `SamlServiceProvider.ClaimMappings`](/identityserver/saml/configuration.md#default-claim-mappings). The signing behavior is configured via the [`SamlSigningBehavior` enum](/identityserver/saml/configuration.md#samlsigningbehavior). |
Contributor
There was a problem hiding this comment.
FYI: the claims mapping will potentially change as we're still doing some API review on this work.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
@bhazen would you mind a quick pass?