docs(sso): keep the SAML page to what an operator can act on - #501
Merged
Conversation
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.
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
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.
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
Issuerelement is optional in the schema, and which sessions a crafted LogoutRequest can and cannot
end. The action is one setting.
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 itsdefault.
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 Keycloakdoes 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.urldoes not affect it — which is whatstops a reader from setting that property and expecting it to help — plus the Tomcat connector
settings, the
Hostheader requirement and the restart.Verification
python tools/check_headings.pyover the versionsversions.jsoncalls current → passespython -m unittest discover -s tools -p 'test_*.py'→ OKpython tools/update_eol.py --check→ passes