SAML Authentication documentation for the dotCMS Content Management System

The SAML protocol provides a common authentication format which enables the use of single-sign-on, allowing dotCMS users to authenticate using third-party account providers such as Google and Amazon.

dotCMS provides built-in support for SAML authentication via the SAML App, available in the Apps Tool.

The SAML Identity Provider (IdP)

In SAML, the Identity Provider (IdP) is the account provider that authorizes login and authentication requests. When you enable SAML in dotCMS, dotCMS no longer directly authorizes users; instead, dotCMS queries your configured IdP, and provides or denies access to dotCMS content and objects based on the authorization information provided by the IdP.

Therefore, to enable SAML logins in dotCMS, in addition to configuring the dotCMS SAML App, you must also configure the user accounts in your Identity Provider to give those users the dotCMS Roles required for them to access the appropriate dotCMS content.

This document only describes how to configure and manage the SAML App within dotCMS. For information on how to configure your IdP, please see your Identity Provider's documentation.

SAML App Configuration

You may specify a different SAML configuration for each Site in your dotCMS instance.

You may also specify a single SAML configuration for all Sites in your dotCMS instance; if no SAML configuration exists for a specific Site, but a valid configuration exists for the System Host, then the Site will use the System Host configuration.

PropertyData TypeDefault ValueDescription
attribute.email.nameStringmailThe IdP attribute used to synchronize the email address of the user.
attribute.firstname.nameStringgivenNameThe IdP attribute used to synchronize the first name of the user.
attribute.lastname.nameStringsnThe IdP attribute used to synchronize the last name of the user.
attribute.roles.nameStringauthorizationsThe IdP attribute used to synchronize Roles.
authn.protocol.bindingHttp-Redirect or
Http-POST
Http-RedirectThe appropriate value to use depends on the IdP.
  • Most IdPs require and accept Http-Redirect.
  • Some IdPs (such as Azure) require Http-POST.
role.extraStringemptyA comma-separated list of dotCMS Role IDs (e.g. DOTCMS_BACKEND_USER).
verify.signature.credentialsBooleantrueIf set to false, the signature portion of the assertion returned from the IdP is not verified.

New SAML Users

The first time you login to dotCMS using SAML, dotCMS will check to see if the user account already exists as a native dotCMS account - either as a front-end user or back-end user.

  • If a native user account already exists for the user, it will be used.
    • The native account password will not be changed or removed.
    • The native account password will be ignored when SAML is used to login, but it will still be possible for a user to login with their previous password by accessing the dotCMS back-end in native mode.
  • If no account exists for the user, a new user account will be created.

dotCMS will then perform actions to synchronize the user account with the SAML identify provider.

Limiting Who Can Create an Account

With SAML authentication, all authentication is performed by the IdP, not by dotCMS. This means that, to limit which users can create an account in dotCMS, you must limit which users the IdP authenticates before passing the authenticated users to dotCMS.

For example, if you use Google as your IdP, you can configured the Google SSO to only allow certain Google users to authentiate using the configuration. When you connect the dotCMS SAML configuration to the Google SSO configuration, that ensures that only users which are accepted by the Google IdP configuration will be able to create accounts within dotCMS.

This means that it is very important that you configure your IdP to authenticate only the users you wish to be able to create accounts in dotCMS.

Note, however, that even if accounts are created for users you do not expect - because they are authorized by the IdP - those user accounts will not have any Roles in dotCMS unless one of the following is true:

  • The dotCMS SAML configuration automatically assigns Roles to all valid users which give those users rights to access dotCMS content or systems. For this to happen, both of the following must be true:
    • The build.roles property must be set to all, and
    • The role.extra property must include a Role with rights to access dotCMS content or systems.
  • The users are assigned dotCMS Roles in the IdP configuration.
    • Since this requires explicit configuration of the IdP for the user, this will only be true for users you explicitly choose to authorize.

Account Synchronization

Each time a user logs into dotCMS using SAML, dotCMS will synchronize the user account with the IdP. This includes both synchronizing Roles as defined in your configured Role synchronization strategy, and synchronizing account attributes defined in your SAML configuration, such as the user's first and last names.

Attribute Synchronization

If your SAML configuration defines user account attributes, the values of any user account attributes in dotCMS is always overwritten by the values of those attributes from the IdP. This synchronization happens with every SAML login.

You may prevent overwriting of the user account attributes by disabling account synchronization. For more incormation, please see Disabling Account Synchronization, below.

Role Synchronization

You can specify how dotCMS Roles are assigned to SAML users. By default, all SAML logins are assigned a default Role which identifies them as SAML users, and all Roles on users who login using SAML are automatically synchronized from the IdP.

The SAMLUser Role

By default, when a user logs into dotCMS using SAML, they will be assigned the SAMLUser System Role. This Role has no permissions to any dotCMS objects by default, but if you wish to provide all SAML users some default permissions, you can do so by assigning permissions to the SAMLUser Role.

The Role Assignment Strategy (build.roles App property)

In addition to the SAMLUser Role, you can also configure dotCMS to assign other Roles, including different Roles to different SAML users, in one of more of the following ways:

  • Prevent Role synchronization from the SAML IdP, and manually manage Roles for the user(s) in dotCMS (in the same way they're managed for native dotCMS logins).
  • Inherit Roles from the SAML IdP.
  • Add pre-defined Roles from the dotCMS configuration (via the role.extra App property).

How Roles are applied is configured via the build.roles property in the SAML App configuration. This configuration property can accept the following values:

Property ValueExisting User RolesRoles from the
role.extra Property
(If it is set)
Roles from the
Identity Provider (IdP)
allRemovedAddedAdded
idpRemovedIgnoredAdded
staticonlyRemovedAddedIgnored
staticaddNot ChangedAddedIgnored
noneNot ChangedIgnoredIgnored

Important

You can not manage Roles from both dotCMS and the SAML identity provider.

You must choose whether dotCMS or the IdP is the source of the dotCMS Role assignments, and then assign an appropriate Role strategy (from the above table), depending on whether you would like to use the role.extra property.


Disabling Account Synchronization

You can prevent dotCMS from performing any changes to dotCMS user accounts or Roles by setting the allow.user.synchronization SAML property to false.

allow.user.synchronization=false

When this property is disabled, the following changes are made to how dotCMS handles SAML logins:

  • When a new user authenticates via SAML, dotCMS will not create a new user account.
    • Users will only be able to authenticate via SAML if a user account already exists for that user in dotCMS when they attempt to login.
  • User account attributes such as first name and last name will not be synchronized.
    • User account attributes can only be set and changed through the dotCMS admin console.
  • Only Roles explicitly added to user accounts via the dotCMS administration interface will exist on any dotCMS user accounts.
    • The SAMLUser Role will not be assigned to any users.
    • No Roles will be assigned to users from the IdP.
    • The build.roles property will be ignored.

Forcing Native Login

Once SAML is enabled, all attempts to access the dotCMS administrative console (/dotAdmin) will be automatically authenticated using SAML, rather than native dotCMS logins. The native dotCMS login screen will no longer display.

You can login using native dotCMS accounts by setting the ?native=true URL parameter:

/dotAdmin?native=true

When you use this URL, the native dotCMS login screen displays. This allows you to login to a native dotCMS account. However you can only login using the native interface with a user account for which a native password has been set; user accounts which have been created via SAML do not have native dotCMS passwords, and can not be accessed using the native login screen. This means that the native login option only exists for user accounts which:

  • Existed as native dotCMS user accounts before SAML integration was enabled, or
  • Have had the native password manually set (via the administration interface).

Roles Applied to Native Logins

When you login using the native login screen, it does change how Roles are assigned to user accounts. This means that, if SAML integration is configured to overwrite user Roles:

  • Any Roles which were set during a prior SAML login will remain.
    • Any Roles a user had prior to SAML integration will be removed from that user the first time the user logs in via SAML.
  • Any changes you make to a user's Roles in the Users screen will not persist.
    • Although you can temporarily assign user Roles via the Users screen, the next time the user logs in via SAML, any changes you have made will be overwritten based on your SAML Role assignment configuration.

REST and WebDAV Authentication

REST and WebDAV operations can not be authenticated using SAML. Therefore, to enable user accounts to perform these operations, the operations must be authenticated using API Tokens. To enable the use of API Tokens with a user account:

  1. Ensure that the user account already exists in dotCMS.
    • This can be accomplished either by manually creating the user account in the dotCMS admin console, or by having the user requiring authentication login first via SAML.
    • You can not assign an API Token until after the user account has been created in dotCMS.
  2. In the dotCMS admin console, create an API Token for the user.

Once the API token has been created, the user account can perform REST or WebDAV requests by:

  • REST: Submit the API Token in the header of the request.
  • WebDAV: Authenticate using the dotCMS user name, with the API Token is submitted as the password.

Converting from Native Login to SAML

The following is a guideline for how to convert your dotCMS instance from using native dotCMS logins to using SAML.

  1. Prepare for Migration
    • Decide which SAML users will be allowed to login to each of your dotCMS Sites.
    • Decide which Roles to assign for users on each dotCMS Site.
  2. Create your SAML configuration on the IdP (authentication provider) you will connect to (e.g. Google SSO).
    • Add appropriate Role Keys for each IdP user, to match the Roles those users should be assigned in dotCMS.
  3. Configure your SAML connection in dotCMS.
    • If you wish to allow different users for each dotCMS Site, or assign different permissions to SAML users on different Sites, you will need to create a different SAML configuration for each Site.
    • Otherwise (if you want all SAML users to have the same permissions on all Sites), you can create a single SAML configuration for the System Host.
  4. Create API Tokens for any user accounts which need access to REST API calls and/or WebDAV.