Skip to content

docs(sso): document the SAML role-attribute risk and the SameSite requirement - #477

Open
marevol wants to merge 1 commit into
masterfrom
saml-doc-security-notes
Open

docs(sso): document the SAML role-attribute risk and the SameSite requirement#477
marevol wants to merge 1 commit into
masterfrom
saml-doc-security-notes

Conversation

@marevol

@marevol marevol commented Aug 9, 2026

Copy link
Copy Markdown
Contributor

Three additions to 15.8/config/sso-saml.rst, applied to all seven languages (ja, en, de, es, fr, ko, zh-cn).

1. The role attribute can hand out administrator rights

saml.attribute.role.name is documented as a plain attribute mapping, but SamlCredential#getDefaultRolesAsArray copies the IdP attribute values into the Fess roles verbatim, and authentication.admin.roles defaults to admin in fess_config.properties. Any user whose role attribute contains admin therefore becomes a Fess administrator.

This is how Fess SSO works generally — the Entra ID authenticator maps Graph directoryRole objects into roles the same way — so this is a warning on the page rather than a code change. But the page gave no hint of it, and the example it shows is saml.attribute.role.name=roles, which is exactly the configuration where it matters.

2. SameSite breaks the ACS callback

tomcat_config.properties ships tomcat.sameSiteCookies = lax, which FessBoot applies to every context's cookie processor, so JSESSIONID carries SameSite=Lax.

The SAML assertion reaches /sso/ as a cross-site POST from the IdP's auto-submitting form, and a cookie with an explicit SameSite=Lax is not sent with it. getLoginCredential() then sees no session, treats the request as a fresh visit and issues another AuthnRequest — the login loops between Fess and the IdP.

Added to the existing "cannot return to Fess after authentication" troubleshooting entry, with tomcat.sameSiteCookies = none as the fix and the note that SameSite=None requires HTTPS. The comment in tomcat_config.properties only mentioned OAuth/OIDC, whose callback is a top-level GET and is unaffected; codelibs/fess#3224 corrects that comment.

3. The insecure-settings warning

codelibs/fess#3224 makes Fess log Insecure SAML settings: ... when java-saml reports weak configuration. Mentioned in the security section so operators can connect the log line to the settings on this page.

Item 3 describes behaviour from codelibs/fess#3224. Items 1 and 2 describe the current release and are accurate today.

Verification

Each file was parsed with docutils (Sphinx-only directives and roles filtered out) — no structural, indentation or escape errors in any of the seven. The zh-cn text follows the existing \ ``literal``\ spacing convention used elsewhere on the page.

…uirement

Three additions to the 15.8 SAML page in all seven languages.

- Role attribute: saml.attribute.role.name makes the IdP attribute values
  Fess roles verbatim, and authentication.admin.roles defaults to admin, so
  an IdP that sends a role value of admin grants Fess administrator rights.
  The page previously described the property without noting that.
- Troubleshooting: the assertion reaches the ACS as a cross-site POST from
  the IdP, so with the shipped tomcat.sameSiteCookies = lax the browser does
  not send the session cookie and the login loops back to the IdP. Added to
  the "cannot return to Fess after authentication" entry with the fix.
- Security settings: mention the Insecure SAML settings warning that Fess
  writes when weak settings remain, so operators know what it refers to.
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