Skip to content

docs(sso): document the session cookie setting SAML requires (7 languages) - #480

Open
marevol wants to merge 1 commit into
masterfrom
docs/saml-samesite-cookie
Open

docs(sso): document the session cookie setting SAML requires (7 languages)#480
marevol wants to merge 1 commit into
masterfrom
docs/saml-samesite-cookie

Conversation

@marevol

@marevol marevol commented Aug 10, 2026

Copy link
Copy Markdown
Contributor

Problem

The SAML configuration page never mentioned tomcat.sameSiteCookies, yet SAML SSO does not work on a default install without changing it.

The IdP returns the assertion to Fess as a cross-site POST (SAML's HTTP-POST binding). A SameSite=Lax cookie is not sent on such a request, and Fess ships tomcat.sameSiteCookies = lax in tomcat_config.properties. Because the attribute is set explicitly, Chrome's two-minute "Lax + POST" grace period does not apply either — that only covers cookies with no SameSite attribute at all. The session that holds the AuthnRequest ID is therefore unreachable when the assertion arrives, and the login cannot complete.

The comment on the setting in tomcat_config.properties already names SAML's HTTP-POST binding as a case that needs none. The SAML page did not, so there was no way to discover the requirement from the documentation.

Change

Adds a "Session Cookie Configuration" section after "Enabling SSO", covering:

  • the value to set, and why the shipped default does not work for SAML
  • where the file lives per package — lib/classes/ for the ZIP, /etc/fess/ for DEB/RPM (verified against src/main/assemblies/common-bin.xml and the jdeb/rpm mappings in pom.xml, not assumed)
  • a warning that none is only accepted on a Secure cookie, so Fess must be served over HTTPS — on plain HTTP the setting makes login impossible
  • a note that the lax default exists for redirect-based (GET) SSO callbacks, so this change is only needed for SAML, and that a restart is required

Applied to the 15.8 pages in all seven languages.

Companion to codelibs/fess#3239, which stops the same missing cookie turning into an infinite redirect loop. That change makes the failure visible and logged; this one tells operators how to avoid it.

Checks

tools/check_headings.py over the versions.json current versions (15.7, 15.8): exit 0
  - and no new findings vs master across the whole tree
tools/update_eol.py --check: every translation matches versions.json
python -m unittest discover -s tools: Ran 23 tests, OK

All seven changed pages were also parsed with docutils: no title underline or section title errors (the CJK underline widths were computed, not eyeballed).

…ages)

The SAML page never mentioned `tomcat.sameSiteCookies`, yet SAML SSO does not
work on a default install without changing it.

The IdP returns the assertion as a cross-site POST, and a `SameSite=Lax` cookie
is not sent on one. Fess ships `tomcat.sameSiteCookies = lax`, and because the
attribute is set explicitly the "Lax + POST" grace period does not apply either,
so the session that holds the AuthnRequest ID is unreachable when the assertion
arrives. The comment on the setting in `tomcat_config.properties` already names
SAML's HTTP-POST binding as a case that needs `none`; the SAML page did not.

Adds a "Session Cookie Configuration" section after "Enabling SSO" covering the
value, where the file lives in each package (`lib/classes/` for ZIP, `/etc/fess/`
for DEB/RPM), the HTTPS requirement that `none` brings with it, and that a
restart is needed.

Applied to the 15.8 pages in all seven languages.

Checks: `tools/check_headings.py` over the versions.json current versions exits
0 and reports no new findings; `tools/update_eol.py --check` and the tools unit
tests pass; all seven changed pages parse with no title underline or section
errors.
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