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.

Basic Configuration Properties

PropertyData TypeDefault Value
Description
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 single extra 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.

Advanced Configuration Properties

PropertyData TypeDefault Value
Description
idp.metadata.pathStringemptyIn case you have a idp-metadata.xml you can get it from the classpath or file system. For the classpath, overwrite the property with the right path in your classpath. If you want to get the XML from the file system use the prefix file://.
protocol.bindingStringorg.opensaml.saml.common.xml.SAMLConstants.
SAML2_ARTIFACT_BINDING_URI
The binding tells to the Idp how the SP is expecting the response. The default one just wait for SAMLArt parameter with the Artifact Id to resolve the artifact via Artifact Resolver. We also have support for urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST, this one expects a SAMLResponse as part of a post-back with the Assertion response.
identity.provider.destinationsso.urlStringurl from the idp-metadataURL for the login page on the Shibboleth Server. By default, it gets the url from the idp-metadata (the file provided from the Shibboleth server); in case there is not any idp-metadata you can edit this property and include the SSO url. (Note, if you set this property as well as the idp-metadata, the idp-metadata will be get by default).
service.provider.issuerStringdefault dotCMS site nameApp Id for the dotCMS Service Provider. In case it is not provided, the default dotCMS site name will be set, using the https protocol. We encourage to use your url.com address, for instance: http://www.dotcms.com
assertion.customer.endpoint.urlStringdefault endpoint will be created using the service.provider.issuer and the keystore.entry.idURL used by the Idp (the Shibboleth server) to redirect to dotCMS when the login is made. We suggest to go to http://[domain]/dotsaml/login.
logout.service.endpoint.urlStringdefault endpoint will be created using the service.provider.issuer/dotsaml/logoutURL used by the Idp (the Shibboleth server) to redirect to dotCMS when the logout is made.
policy.allowcreateBooleanfalseAllows to create users that do not exist on the IdP.We advise to not create new users on the Idp, however you can change this behavior, turning on this property.
nameidpolicy.formatStringBy default we support TRANSIENT and PERSISTANCE formatsSAML Name ID policy. By default we support TRANSIENT and PERSISTANCE formats, however if you want to overwrite it just add the values (comma separated). See org.opensaml.saml.saml2.core.NameIDType for more details about the valid values.
authn.comparisontypeStringMINIMUMComparison rule used to evaluate the specified authentication methods. Possible values are:MINIMUM:The user could be authenticated by using password or any stronger method, such as smart card for instance.BETTER:The user must be authenticated with a stronger method than password.EXACT:The user will be authenticated with a specific method assigned for it, for instance: if it is password, the user will be authenticated only by password.MAXIMUM:The user will use the strongest possible method.
authn.context.class.refStringorg.opensaml.saml.saml2.core.AuthnContext.PASSWORD_AUTHN_CTXAuthentication context, which could be Kerberos, Internet protocol, password, etc. See org.opensaml.saml.saml2.core.AuthnContext for more details.
clock.skewInteger10000Time out between the dotCMS call and the IDP.
message.life.timeInteger2000For message lifetime validation purpose.
remove.roles.prefixStringemptyDepending on your Identity Providers on the IdP, the roles may be returned on the assertion with a prefix, you can change this behavior by turning on remove.roles.prefix.
build.rolesStringallOptional key to configure the roles strategy to sync them from IDP to DOTCMS Valid values: “all”: Removes all user roles from DOTCMS; adds the roles to DOTCMS from IdP and role.extra (if set) “idp”: Removes all user roles and adds the roles to DOTCMS from IdP “staticonly”: Removes all user roles, adds roles from role.extra (if set) to DOTCMS. Ignore roles from IdP. “staticadd”: Do not alter existing user roles, adds the roles from role.extra (if set) to DOTCMS. Ignore roles from IdP. “none”: Do not alter any user roles on DOTCMS
attribute.email.allownullBooleantrueValue to allow to build a dummy email based on the NameID from the Idp when the email attribute from the IDP is not present. True will apply the email generation, false will throw 401 error.
attribute.firstname.nullvalueStringnullIf the first name attribute is null, this value will be set instead
attribute.lastname.nullvalueStringnullIf the first name attribute is null, this value will be set instead
idp.metadata.protocolStringurn:oasis:names:tc:SAML:2.0:protocolAttribute name used to find the Idp Information on the idp-metadata.xml (the file provided from the Shibboleth server).
idp.metadata.parser.classnameStringDefaultMetaDescriptorServiceImplThis class parses the idp-metadata and creates the sp-metadata from the runtime information.
access.filter.valuesStringemptyIf you want to avoid to check open saml authentication over any URL please add (comma separated) the list of urls on this property.
service.provider.custom.
credential.provider.classname
StringemptyUsed to set custom credentials for the Service Provider. This property expects a fully qualified class name. Please see com.dotcms.plugin.saml.v3.CredentialProvider.
id.provider.custom.
credential.provider.classname
StringemptyUsed to set custom credentials for the ID Provider. This property expects a fully qualified class name. Please see com.dotcms.plugin.saml.v3.CredentialProvider.
want.assertions.signedBooleantrueThis value is if you want assertions signed or not.
authn.requests.signedBooleantrueThis value is if you want authorization requests signed or not.
service.provider.custom.metadata.pathString*/dotsaml/metadata.xml *This is the service provider path.
assertion.resolver.handler.classnameStringcom.dotcms.saml.service.handler.HttpPostAssertionResolverHandlerImpldotCMS provides a default implementation for handling the authentication callback from the IDP, it could be overridden if needed.
include.roles.patternStringemptyComma separated value, used to validate roles against the patterns provided. Only matching roles will be considered.
include.path.valuesString^/dotsaml3sp*$, ^/dotCMS/login.*$, ^/html/portal/login.*$, ^/c/public/login.*$,<BR>^/c/portal_public/login.*$,^/c/portal/logout.*$"Comma separated values with the regex paths to be considered by the SAML plugin. Use this property in case you need to filter additional paths.
logout.path.valuesString^/dotsaml3sp*$, ^/dotCMS/login.*$, ^/html/portal/login.*$, ^/c/public/login.*$,<BR>^/c/portal_public/login.*$,^/c/portal/logout.*$",Comma separated values with the regex paths to be considered by the SAML plugin. Use this property in case you need to add additional logout paths
identity.provider.destinationslo.urlStringit gets url from the idp-metadataThis is url for the logout page on the SAML Server. If it is not any idp-metadata you can edit this property and include the SLO url. (Note, if you set this property and set the idp-metadata, the idp-metada will be get by default)
verify.assertion.signatureBooleantrueFor signature verification purpose.
verify.signature.profileBooleantrueFor signature verification purpose.
verify.signature.credentialsBooleantrueFor signature verification purpose.

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:

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.

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.


StepIdP or External ConfigurationdotCMS Configuration
1Prepare 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.
2Copy the metadata from your SAML Identify Provider (IdP)
  • This information will be used to configure SAML in dotCMS.
 
3Generate a public/private key pair
  • This pair will be used to encrypt the connection between your IdP and dotCMS.
    Instructions on how to do this are here.
 
4Configure the user accounts on the IdP
  • Add Role Keys for appropriate dotCMS Roles to each user.
 
5Configure the SAML App within dotCMS
  • This requires the metadata from your IdP.
  • 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.
6Retrieve the SAML metadata from dotCMS
7Add dotCMS to the IdP as an SSO provider
  • This requires the dotCMS SAML metadata.
 
8Create API Tokens
9Test
  • Ensure your IdP users can login to dotCMS.