Skip to content

docs(sso): keep the SAML page to what an operator can act on - #501

Merged
marevol merged 1 commit into
masterfrom
docs/trim-sso-implementation-detail
Aug 19, 2026
Merged

docs(sso): keep the SAML page to what an operator can act on#501
marevol merged 1 commit into
masterfrom
docs/trim-sso-implementation-detail

Conversation

@marevol

@marevol marevol commented Aug 16, 2026

Copy link
Copy Markdown
Contributor

The SAML page had grown several passages that describe how the implementation behaves rather
than what to configure. They do not change what a reader does, and this is open source, so the
source is the better place for them.

Net effect: -306 / +77 lines across the seven translations, with nothing actionable removed.

Replaces #500, which corrected one of these passages instead of cutting it.

What is cut, and what stays

Single Logout warning. It listed which checks the library performs, that the Issuer
element is optional in the schema, and which sessions a crafted LogoutRequest can and cannot
end. The action is one setting.

When Single Logout is configured (saml.idp.single_logout_service.url), always set
saml.security.want_messages_signed=true as well. While it is false, a LogoutRequest that
carries no signature is accepted, so a crafted URL can end an authenticated user's session.
The impact is a forced logout (denial of service), not account takeover.

This also drops a sentence that had become wrong. codelibs/fess#3262 and codelibs/fess#3300
make the NameID of a LogoutRequest be compared against the session user, so "the NameID in the
LogoutRequest is never compared against the logged-in user" no longer describes 15.8.

AuthnRequest expiration. Removed: what happens for a value that cannot be parsed as a
number, what happens for zero or less, and a note about a per-session cap on unanswered
AuthnRequests that no saml. setting can change. Kept: the property, what it means, and its
default.

Troubleshooting, cannot return after authentication. Removed: a paragraph explaining how to
tell two warning messages apart — the remedy is the same either way — and a note comparing the
behaviour with 15.7. Kept: the SameSite remedy and the advice to raise the session timeout
alongside saml.request.id.ttl, since both are things to change.

IdPs that repeat an attribute name. Removed: the explanation of where in validation the
refusal happens and that it is unaffected by saml.attribute.role.name. Kept: that Keycloak
does this by default, both remedies, and the property.

Destination validation behind a reverse proxy. Removed: how the request URL is
reconstructed, and the internal-host example. Kept, in one sentence, that the comparison uses
the URL as the request arrives and that saml.sp.base.url does not affect it — which is what
stops a reader from setting that property and expecting it to help — plus the Tomcat connector
settings, the Host header requirement and the restart.

Verification

  • python tools/check_headings.py over the versions versions.json calls current → passes
  • python -m unittest discover -s tools -p 'test_*.py' → OK
  • python tools/update_eol.py --check → passes
  • All seven files parse under docutils with no new system messages

The SAML page had grown several passages that describe how the implementation
behaves rather than what to configure. They do not change what a reader does,
and this is open source, so the source is the better place for them.

Five passages are cut back:

- The Single Logout warning listed which checks the library performs, that the
  Issuer element is optional, and which sessions a crafted LogoutRequest can and
  cannot end. The action is one setting; the warning now gives that setting, the
  risk of leaving it off, and the severity. This also drops a sentence that had
  become wrong: the NameID of a LogoutRequest is compared against the session
  user now, so a request naming somebody else no longer ends the session.
- AuthnRequest expiration described what happens for an unparseable value and
  for zero or less, and carried a note about a per-session cap that no saml.
  setting can change. The property, its meaning and its default remain.
- The troubleshooting entry for not returning after authentication explained how
  to tell two warning messages apart. The remedy is the same either way. A note
  comparing the behaviour with 15.7 goes too. The SameSite remedy and the
  session-timeout advice stay, because both are things to change.
- The repeated-attribute-name section explained at which point of validation the
  refusal happens. What Keycloak does by default and the two remedies stay.
- The reverse-proxy entry described how the request URL is reconstructed. It now
  says only that the comparison uses the URL as the request arrives, and that
  saml.sp.base.url does not affect it, which is what stops a reader from setting
  that property and expecting it to help.

All seven translations are updated the same way.
@marevol
marevol merged commit 86cee5e into master Aug 19, 2026
2 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant