docs(sso): state that Entra ID form_post requires HTTPS - #496
Merged
Conversation
Verified against a live tenant while testing 15.8: with entraid.response.mode=form_post, the session cookie is emitted as SameSite=None without the Secure attribute, so browsers refuse to store it over plain HTTP and the callback fails before the state can be validated. The Entra ID pages described the tomcat.sameSiteCookies=none workaround without mentioning that requirement, which the SAML pages already spell out. Reuse the same wording so the two SSO methods read consistently. Also correct the troubleshooting entry. The callback fails once and returns to the login page with an error rather than looping, and naming both the message shown to the user and the warning written to the log makes the case recognisable, the same way the SAML page documents its equivalent failure. Applies to config/sso-entraid.rst and install/upgrade.rst in all seven languages. The server-side form_post handling itself is correct; only the cookie attribute prevents it from working without TLS.
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.
What
The 15.8 Entra ID pages tell you to set
tomcat.sameSiteCookies = nonewhenentraid.response.modeisform_post, but never say that the workaround onlyworks over HTTPS. This adds that requirement and corrects how the failure is
described.
Touches
config/sso-entraid.rstandinstall/upgrade.rstin all sevenlanguages (de, en, es, fr, ja, ko, zh-cn).
Why
Testing 15.8 against a live tenant turned up two inaccuracies.
The
noneworkaround needs TLS. Withtomcat.sameSiteCookies = none, thesession cookie goes out as:
There is no
Secureattribute, and browsers reject aSameSite=Nonecookiethat does not carry one. Over plain HTTP the cookie is therefore never stored
at all, which is worse than leaving the default
laxin place: instead ofonly the cross-site callback losing the cookie, every request does. Either way
the login fails with
could not validate state.Worth noting that the server side is fine — replaying the same callback as a
POST with the session cookie attached completes the login normally, so the
only thing standing between
form_postand a working setup is the cookieattribute.
The SAML pages already carry this warning, in every language:
This reuses that wording so the two SSO methods read the same way.
The failure does not loop. The troubleshooting entry said the sign-in
screen "keeps reappearing". It fails once, on the spot, and the browser lands
on the login page with an error. The revised entry names both the message the
user sees and the warning written to the log, matching how the SAML page
documents its equivalent failure.
Verification
Built 15.8 from master and connected it to a real Entra ID tenant, then ran
the callback through a browser under
laxand undernone, and separatelyreplayed the callback POST with the session cookie attached to isolate the
server-side path from the cookie policy.
The changed reStructuredText was parsed with docutils to confirm the new
bullet continuations and inline literals render — including the CJK
languages, where a closing
``followed directly by a CJK characterwould silently fall back to plain text.
Notes
No behaviour change in Fess; documentation only. The default
entraid.response.mode=queryis unaffected and needs no TLS-specific setupbeyond the usual production recommendation.