Skip to content

docs(sso): state that Entra ID form_post requires HTTPS - #496

Merged
marevol merged 1 commit into
masterfrom
docs/entraid-form-post-https
Aug 15, 2026
Merged

docs(sso): state that Entra ID form_post requires HTTPS#496
marevol merged 1 commit into
masterfrom
docs/entraid-form-post-https

Conversation

@marevol

@marevol marevol commented Aug 15, 2026

Copy link
Copy Markdown
Contributor

What

The 15.8 Entra ID pages tell you to set tomcat.sameSiteCookies = none when
entraid.response.mode is form_post, but never say that the workaround only
works over HTTPS. This adds that requirement and corrects how the failure is
described.

Touches config/sso-entraid.rst and install/upgrade.rst in all seven
languages (de, en, es, fr, ja, ko, zh-cn).

Why

Testing 15.8 against a live tenant turned up two inaccuracies.

The none workaround needs TLS. With tomcat.sameSiteCookies = none, the
session cookie goes out as:

Set-Cookie: JSESSIONID=...; Path=/; HttpOnly; SameSite=None

There is no Secure attribute, and browsers reject a SameSite=None cookie
that does not carry one. Over plain HTTP the cookie is therefore never stored
at all, which is worse than leaving the default lax in place: instead of
only 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_post and a working setup is the cookie
attribute.

The SAML pages already carry this warning, in every language:

Browsers only accept none on a cookie that also carries the Secure
attribute, so Fess must be served over HTTPS.

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 lax and under none, and separately
replayed 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 character
would silently fall back to plain text.

Notes

No behaviour change in Fess; documentation only. The default
entraid.response.mode=query is unaffected and needs no TLS-specific setup
beyond the usual production recommendation.

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.
@marevol
marevol merged commit bdccfc0 into master Aug 15, 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