SAML Authentication

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.

Please Note: Some additional documentation is provided to give examples for how to configure the SAML App with some specific services (see the subsections under this document). However, there are many different SAML Identity Providers (IdPs) and each is different. So, dotCMS does not provide documentation for how to configure all IdPs, and it is the responsibility of each user to configure the SAML app with your specific provider.

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.

Basic Configuration Properties

For any SAML integration to work, all of the following properties must be set properly.

Identity Provider (IdP) Synchronization Properties

Some SAML integrations will require the use of some of these properties to synchronize dotCMS with the IdP, or to specify how dotCMS should handle certain types of responses from the IdP (such as user accounts which do not have valid values for name or email address).

Advanced Configuration Properties

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, unless allow.user.synchronization is set to false.

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 SAML User Role

By default, when a user logs into dotCMS using SAML, they will be assigned the SAML User 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 SAML User Role.

The Role Assignment Strategy (build.roles App property)

In addition to the SAML User 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 a pre-defined Role 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:

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 CI/CD Authentication

REST, dotCLI, 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, dotCLI, or WebDAV requests by:

• REST: Submit the API Token in the header of the request.
• dotCLI: Submit the token using the --token or -tk option, especially (but not exclusively) via the login command.
• WebDAV: Authenticate using the dotCMS user name, with the API Token is submitted as the password.

Retrieving SAML App Metadata

To configure dotCMS as an SSO provider with the IdP, you will need to provide the SAML metadata from dotCMS to the IdP. You can retrieve the dotCMS SAML metadata using the following REST API method:

/api/v1/dotsaml/metadata/{siteId}

The {siteId} is the identifier of the dotCMS Site for which you with to retrieve the metadata.

• If you have different SAML configurations for different Sites on the same dotCMS instance, you will need to configure each dotCMS Site as a separate SSO provider with your IdP, and the metadata for each site will be different.
• If you are using the SYSTEM HOST SAML configuration to act as a default SAML configuration for multiple dotCMS Sites in the same dotCMS instance, you should retrieve the metadata by specifying the identifier of one of the Sites that does not have its own separate SAML configuration.

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.

Note:

• The steps in the “IdP or External Configuration” column will need to be performed by whoever manages your IdP administration account (for example, your IT depatrment).
• The steps in the “dotCMS Configuration” column will need to be performed by a dotCMS administrator.