dotauth
SAML 2.0 Settings
These settings appear when you choose SAML 2.0 as the protocol.
dotAuth's SAML screen manages the same configuration as the classic SSO-SAML App. Existing SAML configurations keep working, and they appear in dotAuth automatically.
The Login behavior section (Redirect admin panel, Redirect site login, Hash user ID) is the same as for OIDC.
Service Provider#
"dotCMS metadata — share these values with your IdP team."
| Field | Default | Description |
|---|---|---|
| Entity ID | — | Required when SSO is enabled. Uniquely identifies this dotCMS instance as a SAML Service Provider. Give it to your IdP administrator. |
| ACS (Assertion Consumer) URL | Auto-derived | Read-only: https://<host>/dotsaml/login/<siteId>. |
| Sign requests | On | Signs AuthnRequests with the SP signing key. |
To give your IdP the SP metadata, use Download SP Metadata on the dotAuth overview screen (System card or site row). It downloads from /api/v1/dotauth/saml/metadata/<hostId>.
Identity Provider#
"Upload your IdP's SAML metadata, or fill endpoints manually."
| Field | Description |
|---|---|
| IdP metadata URL | Enter the URL and click Fetch to download the IdP's metadata XML into the Manual XML box. dotCMS saves the XML it fetched, not the URL, so fetch again if your IdP rotates certificates. |
| Manual XML input | Paste the IdP metadata XML directly. This is optional at first: you can save your SP configuration, share your SP metadata with the IdP, then come back and add theirs. |
| SSO URL / SLO URL (optional) | IdP sign-on and single-logout endpoints. |
Signing & Encryption#
| Field | Default | Description |
|---|---|---|
| Want assertions signed | On | Requires the IdP to sign the SAML assertion. Recommended. |
| Want response signed | Off | Requires the IdP to sign the entire SAML response envelope. |
At least one of the two must stay on. Turn on exactly the signatures your IdP sends. dotCMS rejects any SAML response unless every part you selected carries a valid IdP signature. If your IdP signs both the response and the assertion, turn both on.
dotCMS always validates SAML signatures, and validation can't be turned off. The legacy verify.signature.credentials and verify.signature.profile properties are ignored.
Upgrading to 26.10.05-01 or later. The signature validation type None has been removed. A configuration that still has it, or has no validation type, is treated as requiring both a signed response and a signed assertion. If your IdP doesn't sign both, SAML sign-in fails after the upgrade. To fix it, open the site in dotAuth, turn on the signatures your IdP actually sends, and save.
Key overrides. dotCMS generates an SP signing keypair automatically the first time you save with these fields blank. The keypair is 2048-bit RSA with a SHA-256 self-signed certificate, valid for 10 years. To use your own keypair, paste a PEM-encoded X.509 Certificate and Private Key. You must supply both or neither.
Regenerating the keypair. If you clear both fields on a configuration that already has a keypair, dotCMS asks Generate a new SP keypair? before saving. If you continue, upload the new certificate to your IdP, or SAML sign-in will fail. dotCMS never replaces a stored keypair without this confirmation.
Attribute Mapping#
"SAML attribute names → dotCMS user fields."
| Field | Default |
|---|---|
mail | |
| First name | givenName |
| Last name | sn |
| Groups attribute | authorisations |
Additional Properties#
Advanced SAML properties, passed directly to the SAML handler as key/value pairs. Click Add property to add one. Keys may contain letters, digits, ., _, and - (up to 64 characters). Rows with an empty key or value are dropped on save.
These are the same properties the classic SAML App accepts; the SAML App Configuration Reference lists them all. These are commonly needed:
| Property | Use |
|---|---|
authn.protocol.binding | Http-Redirect (default) or Http-POST. Some IdPs, such as Azure, require Http-POST. |
role.key.substitution | Rewrites IdP role names before matching them to dotCMS role keys. For example, /_sepsep_/ / turns CMS_sepsep_Administrator into CMS Administrator, for IdPs that can't send spaces. |
include.roles.pattern | Comma-separated patterns. Only IdP roles that match are considered. |
remove.roles.prefix | Strips a prefix the IdP adds to role names. |
isassertion.encrypted | Set to true if your IdP encrypts assertions. |
access.filter.values | Comma-separated URLs that are never redirected to SAML. |
additionalInfo | Extra assertion attributes to store on the dotCMS user, for example prop1,prop2|collection,prop3|json. |
Provisioning (SAML)#
SAML has the same provisioning controls as OIDC: Auto-provision new users, Default roles, and Role behavior. It also has Sync attributes on every login ("Refresh name, email, and group memberships on each sign-in"), which is on by default. Group security is not available for SAML.
Every SAML user also gets the built-in SAML User role, except under IdP groups only. The role has no permissions by default; grant it permissions to give all SAML users a common baseline.
SAML and role mapping. With SAML, the role names in the IdP's Groups attribute are matched directly against dotCMS role keys. A name with no matching role is skipped; dotCMS doesn't create a role for it. Name your IdP groups to match the dotCMS role keys you want to grant, or use role.key.substitution to translate them. See Limitations.