SAML APP Configuration Reference

SAML APP Custom Properties Reference

This guide details the configuration of the properties for the SAML App on dotCMS.

General Context

When the Saml APP is configured for a particular site or system host for every user logged in dotCMS across the IDP authentication, the information retrieve back from the IDP will be capture and synchronized on dotCMS, this means if the user does not exists on dotCMS it will be created, the roles (if any in the XML response assertion) will be also added in addition to the SAML User role (there is also the possibility to add an extra role by using role.extra properties, detailed here).

The second time that the user gets logged in, since it was previously created on the first login it will be just recovered from dotCMS database and updated with the name, last name, email. It would depend on the role strategy but usually roles will be removed and readded all time the user gets login into the dotCMS however as mentioned this could be configurable and it is even possible to avoid this synchronization at all.

Note: the assertion NameID could be an identifier (uuid) or an email, it will depend on the IDP policy. If the NameID is an identifier, on the configuration portlet > basic config > security, the authentication type must be User Id. On the other hand if the NameID is the user email the Authentication Type must be Email Address, this is important because the user will be locale on the dotCMS based on the authentication type and the nameID.

Custom properties

On the app portlet the user is allowed to edit some default attributes such as the IDP metadata XML, keys, Assertion URL, Federated Id, etc. However there is a section to add optional parameters, in this guide we will detail each of them.

protocol.binding

This property is used on the authentication request, by default uses urn:oasis:names:tc:SAML:2.0:bindings:HTTP-Redirect But it can also be POST.

Bindingtype

This is the binding for the login and logout request from dotCMS, by default we use Redirect but it could change to POST.

isassertion.encrypted

The IDP might send the assertion encrypted, but default dotCMS is not expecting an assertion encrypted but in case it is, set this to true

force.authn

If dotCMS wants to force the authentication on every authentication request, set this to true by default false, it is related to the remember me on some IDPs, where you do not have to relogin if you were previously logged on the IDP.

use.encrypted.descriptor

If true, uses encryption for the Key descriptor on the dotCMS metadata by default is false.

identity.provider.destinationsso.url

Usually the destination url is being recovered from the IDP metadata xml (SingleSignOnService), however if there is not any sso url it can be set by using this property.

role.extra

There are scenarios where we want to add another role (rather than the SAML User role and the IDP roles, if any), in this case the role.extra may help us to add this particular role for all logged users from the IDP, a good example would be: role.extra=DOTCMS_BACK_END_USER

In this example, any user synchronized from the IDP will be also added as a backend user

policy.allowcreate

Allows to create users that do not exist on the IdP, when the authentication request is done, of course it will depend on the IdP policies too. We advise do not create new users on the IDP by SP demand, however you can change this behavior, turning on this property, by default is false.

nameidpolicy.format

SAML Name ID policy. By default we support TRANSIENT and PERSISTENT (default PERSISTENT value is : urn:oasis:names:tc:SAML:2.0:nameid-format:persistent) formats, org.opensaml.saml.saml2.core.NameIDType for more details about the valid values.

authn.comparisontype

Comparison rule used to evaluate the specified authentication methods when the authentication request is being made. By default we use a MINIMUM as an Authorization. Possible values are:

• MINIMUM The user could be authenticated by using a password or any stronger method, such as a 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.ref

Authentication context, which could be Kerberos, Internet protocol, password, etc. See org.opensaml.saml.saml2.core.AuthnContext for more details. By default we use: org.opensaml.saml.saml2.core.AuthnContext.PASSWORD_AUTHN_CTX (urn:oasis:names:tc:SAML:2.0:ac:classes:Password)

clock.skew and message.life.time

For message lifetime validation purpose. By default the clock skew is 10000 and lifetime 20000.

remove.roles.prefix

Depending 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, if set and not empty will remove the prefix (if the role has it) from the roles recovered from IDP assertion.

build.roles

Optional key to configure the roles strategy to sync them from IDP to DOTCMS Valid values (default “all”):

• “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.name

By default, mail is the field used to fetch the user email from the IDP response.

attribute.email.allownull

Boolean value that allows 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.name

By default givenName is the field used to fetch the user name from the IDP response, however if you are using another one you can overwrite it.

attribute.firstname.nullvalue

If the first name attribute is null, this value will be set instead

attribute.lastname.name

By default, “sn” is the field used to fetch the last name from the IDP response.

attribute.lastname.nullvalue

If the first name attribute is null, this value will be set instead

attribute.roles.name

By default, “authorizations” is the field used to fetch the roles/groups from the IDP response, however if you are using another one you can overwrite it. Please note that authorizations is expected as an array, not as a comma separated list.

idp.metadata.protocol

Attribute name used to find the IDP Information on the idp-metadata.xml (the file provided from the Shibboleth server). Default value: urn:oasis:names:tc:SAML:2.0:protocol

access.filter.values

By default, dotCMS does not filter any url, however if you want to avoid to check open saml authentication over any URL please add (comma separated) the list of urls on this property.

include.roles.pattern

Comma separated value, used to validate roles against the patterns provided. Only matching roles will be considered. For instance: “include.roles.pattern”:“^www,^xxx” The previous example will include only the roles from SAML that start with www or xxx.

include.path.values

Comma separated values with the regex paths to be considered by the SAML plugin. By default we include:

^/dotsmal/login$, ^/dotCMS/login.*$, ^/html/portal/login.*$, ^/c/public/login.*$,^/c/portal_public/login.*$,^/c/portal/logout.*$,^/dotCMS/logout.*$,^/application/login/login.*$,^/dotAdmin.*$,"

Use this property in case you need to filter additional paths. For instance: include.path.values:^/html/portal/login.*$,^/dotCMS/login.*$,^/c/,^/admin

logout.path.values

Comma separated values with the regex paths to be considered by the SAML plugin. By default we include:

/api/v1/logout,/c/portal/logout,/dotCMS/logout,/dotsaml/request/logout

Use this property in case you need to add additional logout paths. For instance:

"include.path.values":"^/html/portal/logout.*$,^/dotCMS/logout.*$,^/c/"

identity.provider.destinationslo.url

Usually the logout destination url is being recovered from the IDP metadata xml (SingleLogoutService), however if there is not any slo url it can be set by using this property.

verify.signature.profile

By default dotCMS will validate the signature profile, in case you want to avoid this validation you can set to false

verify.signature.credentials

By default dotCMS validates the assertion signature, in case you want to avoid this validation you can set to false

location.cleanqueryparams

By default when do a redirect request the query string parameters from the sso url are being removed, set to false if want to keep them.

company.email.domain

By default if the creation of the user fails because the email is duplicated, we will try to create a new email based on the name id or a UUID. If you want to set a domain for the new email you can set it here. For example: dotcms.com, by default will use “fakedomain.com”

login.email.update

By default after each login, and if the user already exists, we will try to update the name, lastname and email with the values from the assertion If you want to ignore the email synchronization you should set this value to false.

authn.protocol.binding

By default the authentication request uses the Http-Redirect but you can set to Http-POST if needed

renew.session

If you want to destroy/renew the session when the user is logged in, set this to true.

allow.user.synchronization

By default dotcms allows the user synchronization, this means if the user does not exist on their database the user will be added to their storage, attributes, roles, etc. In case you do not want any synchronization set this to false. Note: if it is set to false, you have to create the users on dotcms manually in order to match with the assertion name id (it will depend on the authentication configuration for dotCMS: by identifier or email on the configuration portlet)