SAML Authentication

Last Updated: Oct 18, 2024
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.

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.

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.extraStringemptyExtra dotCMS Role IDs that will be assigned to all authenticated SAML users (e.g. DOTCMS_BACK_END_USER).
verify.signature.credentialsBooleantrueIf set to false, the signature portion of the assertion returned from the IdP is not verified.

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).

PropertyData TypeDefault Value
Description
attribute.email.allownullBooleantrueIf set to true, then if the IdP does not provide an email value, dotCMS will create a “dummy” email based on the NameID.
If set to false, then if no email is supplied by the IdP, dotCMS will generate a 401 error.
attribute.firstname.nullvalueStringnullIf the first name attribute from the IdP is null, this value will be used instead.
attribute.lastname.nullvalueStringnullIf the last name attribute from the IdP is null, this value will be used instead.
authn.requests.signedBooleantrueShould authorization requests be signed.
See also want.assertions.signed.
hash.useridBooleantrueWhen enabled (default), hashes the NameID received from the identity provider. Disabling stores the IDs without modification.
identity.provider.
destinationslo.url
StringURL taken 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)
identity.provider.
destinationsso.url
StringRetrieved from idp-metadata.xml fileURL for the login page on the IdP.
  • If an idp-metadata.xml file exists (see idp.metadata.path), dotCMS will always use the value from that file (even if this property is set).
  • If there is no idp-metadata.xml file, you can specify the URL with this property.
idp.metadata.pathStringemptyPath to the idp-metadata.xml file (if used). This value can reference the classpath or file system (using the prefix file://).
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).
include.roles.patternStringemptyComma separated value, used to validate roles against the patterns provided. Only matching roles will be considered.
protocol.bindingStringPlease see DescriptionNotifies the Idp how dotCMS is expecting the response. Valid values:
  • org.opensaml.saml.common.xml.SAMLConstants.SAML2_ARTIFACT_BINDING_URI (default): Waits for SAMLArt parameter with the Artifact Id to resolve the artifact via Artifact Resolver.
  • urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST: Expects a SAMLResponse as part of a post-back with the Assertion response.
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.
verify.assertion.signatureBooleantrueFor signature verification purpose.
verify.signature.profileBooleantrueFor signature verification purpose.
verify.signature.credentialsBooleantrueFor signature verification purpose.
want.assertions.signedBooleantrueShould assertions be signed.
See also authn.requests.signed.

Advanced Configuration Properties

PropertyData TypeDefault Value
Description
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.
assertion.customer.
endpoint.url
StringPlease see DescriptionURL used by the Idp to redirect to dotCMS when the login is made.
  • By default, an endpoint will be created using the service.provider.issuer and the keystore.entry.id.
  • We recommend that you override the default value and change this value to http://[domain]/dotsaml/login.
assertion.resolver.
handler.classname
Stringcom.dotcms.saml.service.handler.HttpPostAssertionResolverHandlerImpldotCMS provides a default implementation for handling the authentication callback from the IDP, it could be overridden if needed.
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.
build.rolesStringallOptional key to configure the roles strategy to sync them from IDP to DOTCMS.
Please see below for valid values.
clock.skewInteger10000Time out between the dotCMS call and the IDP.
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.
idp.metadata.parser.classnameStringDefaultMetaDescriptorServiceImplThis class parses the idp-metadata and creates the sp-metadata from the runtime information.
include.path.valuesString^/dotsaml3sp*$, ^/dotCMS/login.*$,
^/html/portal/login.*$, ^/c/public/login.*$,
^/c/portal_public/login.*$, ^/c/portal/logout.*$"
Comma separated values with the regex paths to be considered by the SAML plugin.
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
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.
message.life.timeInteger2000For message lifetime validation purpose.
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.
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.
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.
service.provider.
custom.metadata.path
String*/dotsaml/metadata.xml *The service provider path.
service.provider.issuerStringSite Name of the default SiteApp 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

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).

The required value for forcing the native sign-in method can be changed from true to another value you select. This can be useful as an additional layer of “security by obscurity.” To alter this property, contact a dotCMS customer service representative.

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.


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.

On this page

×

We Dig Feedback

Selected excerpt:

×