Authentication

Introduction to authentication

Authentication in ConSol CM is done via the authentication applications delivered together with the main product. It is based on OpenID Connect. Authorization, i.e. determining the access permissions of the authenticated users, is done via roles.

There are two scopes of authentication:

User group	Clients	Authentication application	Credentials
Users	Web Client and Web Admin Suite	cm-auth-user.war or cm-auth-user-standalone.jar	Managed on the Users page of the Web Admin Suite
Contacts	CM/Track	cm-auth-portal-user.war or cm-auth-portal-user-standalone.jar	Managed on the pages of the respective contact in the Web Client

There are three locations from which the authentication application can retrieve the credentials of the users to confirm their identity: the ConSol CM database, an LDAP server or an external SSO service.

Name	Location of the credentials	Notes
Database	The username and the password are saved in the ConSol CM database.	You can set a password policy and configure the password reset functionality.
LDAP	The username is saved in the ConSol CM database. The password is saved on the LDAP server.	The users or contacts cannot change their passwords it in ConSol CM.
SSO	The username is saved in the ConSol CM database. The password is saved in the active directory and retrieved from a valid Windows session.	The users or contacts cannot change their passwords in ConSol CM. An external SSO provider such as Microsoft Active Directory Federation Services or Azure AD is needed.

The default OIDC configuration for authentication based on database and LDAP credentials is created automatically. For external SSO authentication, you need to adjust the properties with the values required by your SSO provider.

Basic tasks

Determining the credential provider for users

The credential provider for the Web Client and the Web Admin Suite is determined on the Authentication page. Possible values are: "Database", "LDAP", "LDAP, Database", "Database, LDAP".

Mixed mode

If both LDAP and database are configured, the authentication attempts are made in the following order:

• LDAP, Database: If an LDAP ID is saved in the user data, the first login attempt is made using the available LDAP servers. If the login fails, an attempt to log in using the database is made, provided that a username and password are saved in the user data.
• Database, LDAP: If a username and a password are saved in the user data, the first login attempt is made using the database. If the login fails, an attempt to log in using the available LDAP servers is made, provided that an LDAP ID is saved in the user data.

Depending on the configured credential provider, you need to fill different fields on the Users page of the Web Admin Suite:

• Database: Fields Login and Password
• LDAP: Field LDAP ID
• External SSO: Field Login

Authentication of the initial administrator

The credential of the administrator who was created during setup (see system property cmas-core-security, admin.login) are always saved to the database. If you use LDAP-only as an authentication method with internal OIDC, the initial administrator will stop working. Therefore, you first need to assign administrator permissions to a user managed in LDAP.

Determining the credential provider for contacts

The credential provider for CM/Track is determined on the Global portal settings page. Possible values are: "Database", "LDAP", "LDAP, Database", "Database, LDAP".

Mixed mode

If both LDAP and database are configured, the authentication attempts are made in the following order:

• LDAP, Database: If an LDAP ID is saved in the contact data, the first login attempt is made using the available LDAP servers. If the login fails, an attempt to log in using the database is made, provided that a username and password are saved in the contact data.
• Database, LDAP: If a username and a password are saved in the contact data, the first login attempt is made using the database. If the login fails, an attempt to log in using the available LDAP servers is made, provided that an LDAP ID is saved in the contact data.

Depending on the configured credential provider, you need to create fields for the credentials in the contact data on the Contact fields page of the Web Admin Suite. These fields need to be filled out in the Web Client for all contacts which need access to CM/Track or the REST API.

• Database: Username (field with the setting User name for CM/Track) and password (field with the setting Password for CM/Track)
• LDAP: LDAP ID (field with the setting User name for CM/Track and LDAP ID for CM/Track).
• External SSO: Username (field with the setting User name for CM/Track).

Case-sensitive usernames

If database is used, you need define whether CM/Track usernames should be case-sensitive in the system property cmas-core-security, policy.track.username.case.sensitive. Only set it to "true" if the database collation supports case-sensitive strings.

Configuring authentication

The following section describes how to configure authentication with the various credential providers.

Database

No additional configuration required.

LDAP

You need to define the connection to at least one LDAP server.

• For users: Create one or several LDAP configurations on the Authentication page.
• For contacts: Create one or several LDAP configurations on the Global portal settings page.

As a name, you should use a simple string, which does not include any keywords as internal or external and does not contain special characters.

Authentication attempts against the LDAP servers are made until the first success, starting with the first server in an ascending alphabetical order.

The following settings are available:

• Base DN: The root path in the LDAP tree used to look up the user / contact by the LDAP ID, e.g. ou=accounts,dc=mycompany,dc=de.
• Password: The password used for connecting to the LDAP server to look up the users / contacts. Only needed if the lookup cannot be done anonymously.
• Provider URL: The complete address of the LDAP server in the format ldap[s]://host:port. Usually, the standard port is 636 and the port for the global catalog is 3269.
• Search attribute: Search attribute to look up a user / contact by LDAP ID, e.g. uid.
• User DN: The LDAP user for connecting to the LDAP server to look up the users. Only needed if the lookup cannot be done anonymously.
• Context factory: This is a predefined global property. The value should be com.sun.jndi.ldap.LdapCtxFactory.

See below for configuring LDAPS.

External SSO

You need to adjust the default OIDC configuration to use the external SSO provider instead of the ConSol CM authentication applications. This can be done for each client separately.

• Web Client: Adjust the OIDC configuration in the OIDC in the Web Client section of the Authentication page.
• Web Admin Suite: Adjust the OIDC configuration in the OIDC in the Web Admin Suite section of the Authentication page.
• CM/Track V3: Adjust the OIDC configuration in the OIDC in CM/Track V3 section of the Global portal settings page.

The following settings are available:

• OIDC enabled: Indicates whether user authentication using SSO via OIDC is enabled. Should be "true".
• Provider type: Should be "External" to use a third-party application, such as Azure AD or ADFS.
• Global logout: Determines if the user is also logged out from the OIDC provider when logging out of the client. For an external provider, the value is usually "False", so that sessions in other applications, which are provided by the same provider, are not closed.
• Redirect URI: Indicates the redirect URI where authentication responses can be received. This is either the OIDC endpoint on the ConSol CM server running the client or on the load balancer. Example: http://localhost/track/oidc/ or https://localhost/cm-client/oidc/
• URL of the authentication authority: Indicates the URL of the authenticating authority, e.g. ADFS. Example: https://localhost/adfs
• Client ID: Indicates the client ID (application ID) of the application, as registered in ADFS or Azure AD.
• Client secret: Indicates the secret of the client, generated using ADFS or Azure AD.
• Name of claim: Indicates the name of the claim in the ID token which is used to map the user to a user or contact in ConSol CM. The value depends on the ADFS settings; the default values are "upn" and "unique_name".
• RegEx for mapping user names: Defines the regular expression used for mapping the username claim values to ConSol CM usernames.
  • upn as claim: (.*)@.* will transform the claim value user1@sso.yourdomain.com to user1 and look up user1 in the ConSol CM database.
  • unique_name as claim: .*\\(.*) will transform the claim value SSO\user1 to user1 and look up user1 in the ConSol CM database.
• Remember me enabled: Indicates whether the checkbox Remember me is available. The user can select this checkbox to be logged in automatically after a session timeout. Only available for the Web Client.
• Remember me key*: Defines the key to identify tokens created for authentication with the Remember me feature. Only available for the Web Client.
• Remember me period: Allows specifying how long (in hours) a token is valid for the Remember me feature. Only available for the Web Client.

Advanced tasks

Making advanced settings

The following section describes how to make advanced settings for the various credential providers.

Database

Configuring the password policy

You can adjust the password policy in Password policy section of the Authentication page.

• RegEx pattern: RegEx pattern for the password. Default: ^(?=.*[0-9])(?=.*[A-Z])(?=.*[a-z]).{7,}$ (at least 7 characters, at least one upper case letter, one lower case letter and one number)

• Maximum validity: Maximum validity period, in days. Example: 183 (6 months). Default: 5500 (15 years, i.e. no password change enforced).

• Password rotation: Number of previous passwords which may not be identical. Default: 5.

• Case sensitivity of usernames: Defines whether the password is case-sensitive. Default: true.

  MySQL

  This setting is affected by the MySQL collation setting and needs the correct collation to work properly with MySQL.

Configuring password reset

Users or contacts who have forgotten their passwords can click the Forgot your password? link on the login page. If their data contains an email address, they receive an email with instruction on how to reset their passwords.

The following templates are used for the email. They can be adjusted on the Templates page of the Web Admin Suite.

• Users: auth-password-reset-template
• Contacts: track-auth-password-reset-template

The following variables are used in the templates and must be set to the correct values:

• expirationDate: By default, the link expires 24 after the password reset request was made. To change this value, create the system property cmas-core-security, resetCode.expirationPeriod with the desired expiration date.
• urlTrackAuth: URL to the CM/Track instance kept in the system property cmas-core-server, url.track.auth.
• urlWebclientAuth: URL to the Web Client kept in the system property cmas-core-server, url.webclient.auth.

Required permissions for contacts

Contacts need write permissions to their own customer group to reset their passwords.

LDAP

Configuring LDAPS

Per default, when an LDAP client accesses an LDAP server, the information is transferred in clear text. In case you want the username and password to be transferred to the LDAP server in encrypted form, you have to set up the LDAP authentication using LDAPS.

You have to configure the ConSol CM server machine in a way that can use certificates. One way to do this for a Linux environment is described in the following section.

1. Retrieve the certificate:

   openssl s_client -connect dc2.mydomain.com:ldaps

2. The answer will contain a section which starts with "---BEGIN CERTIFICATE " and ends with "END CERTIFICATE ---". Copy this section to a file, e.g. /tmp/certificate2_dc2_mydomain_com.txt

3. Import the certificate to the truststore of your machine, e.g. /home/mydirectory/mytruststore:

   $JAVA_HOME/bin/keytool -import -alias <arbitrary> -trustcacerts -keystore /home/mydirectory/mytruststore -file/tmp/certificate2_dc2_mydomain_com.txt

   You have to enter (set) a password.

4. Enter the truststore in the ConSol CM config file in JAVA_OPTS:

   -Djavax.net.ssl.trustStore=/home/mydirectory/mytruststore -Djavax.net.ssl.trustStorePassword=<see above>

External SSO

No additional configuration possible.

Using two-factor authentication

You can enable two-factor authentication as an additional security measure. The second factor is a one-time code which is sent by email.

The login flow with two-factor authentication looks as follows:

1. The user opens the login page and enters his credentials (username and password).
2. If the credentials are correct, an email with a one-time code is sent.
3. The user enters the one-time code to log in. If configured, he can decide to remember this browser, so that he is not prompted for a one-time code again in the configured time period.

The configuration is done separately for the authentication application (Web Client and Web Admin Suite, Two-factor authentication section on the Authentication page) and the portal authentication application (CM/Track V3, Two-factor authentication section on the Global portal settings page).

• Two-factor authentication enabled: Set to "Email" to enable two-factor authentication.
• Length of the email code: Define the length of the one-time code sent by email. Default: 6.
• Validity of the email code: Define the validity of the one-time code in minutes. Default: 15.
• Users who can skip two-factor authentication: Define which users can skip two-factor authentication by adding their logins as a comma-separated list.
• Remember browser enabled: Set to "true" to show the Remember this device checkbox on the login screen, which allows the users to skip the second factor.
• Remember browser key: Define the key to identify tokens for remembering the browser.
• Remember browser period: Define the time period for remembering the browser.
• Scope: Set to "Only administrators" if two-factor authentication should be required only for users with administrator permissions. Set to "All users", if all users should have two-factor authentication enabled. Only for the Web Client and Web Admin Suite.

You can adjust the email which is sent with the one-time code in the Template for two-factor authentication. It can be found in the following places:

• Web Client and Web Admin Suite: Email templates section of the Authentication page and auth-2fa-mailcode-template template on the Templates page
• CM/Track V3: Credentials tab of the Global portal settings page and track-auth-2fa-mailcode-template template on the Templates page

info

The Remember browser feature is only available via HTTPS or on localhost because secure cookies are used.

Reviewing the internal OIDC configuration

You can review the OIDC configuration in the following places:

• Web Client: OIDC in the Web Client section of the Authentication page
• Web Admin Suite: OIDC in the Web Admin Suite section of the Authentication page
• CM/Track V3: OIDC in CM/Track V3 section of the Global portal settings page

The following settings are available:

• OIDC enabled: Indicates whether user authentication using SSO via OIDC is enabled. Should be "true".
• Provider type: Should be "Internal" to use the ConSol CM authentication application as OIDC provider.
• Global logout: Determines if the user is also logged out from the OIDC provider when logging out of the client. Should be set to "True".
• Redirect URI: Indicates the redirect URI where authentication responses can be received. This is either the OIDC endpoint on the ConSol CM server running the client or on the load balancer. Example: https://localhost/track/oidc/ or https://localhost/cm-client/oidc/
• URL of the authentication authority: Indicates the URL of the authenticating authority. Should be "cmas-auth-user" for the Web Client and Web Admin Suite and "cmas-auth-portal-user" for CM/Track. Example: https://localhost/cmas-auth-user.
• Client ID: Indicates the ID of the client. Does not need to be changed in the default setup.
• Client secret: Indicates the secret of the client. Does not need to be changed in the default setup.
• Name of claim: Indicates the name of the claim in the ID token which is used to map the user to a user or contact in ConSol CM. Should be "sub".
• RegEx for mapping user names: Defines the regular expression used for mapping the username claim values to ConSol CM usernames. Should be (.*).
• Remember me enabled: Indicates whether the checkbox Remember me is available. The user can select this checkbox to be logged in automatically after a session timeout. Only available for the Web Client.
• Remember me key*: Defines the key to identify tokens created for authentication with the Remember me feature. Only available for the Web Client.
• Remember me period: Allows specifying how long (in hours) a token is valid for the Remember me feature. Only available for the Web Client.

Using several URLs for CM/Track

If CM/Track is accessed via more than one URL, you need to create additional OIDC configurations. This is the case for example in the following situations:

• There are two different instances of CM/Track for different groups of end users.
• One instance of CM/Track is accessed via two different URLs, e.g. an internal one and an external one.

For each URL used to access CM/Track, one OIDC configuration is needed. It must be created manually on the System properties page. The following changes are needed:

1. Add all the URLs which should use the portal configuration as a comma-separated list to the system property cmas-restapi-core, domain.map.for.client.config.\{portal_config\}, e.g. domain.map.for.client.config.MYPORTAL=http://cm.consol.pl:8999/cm-track, http://cm.consol.pl/cm-track.
2. Create an OIDC configuration for each URL. It needs to contain at least the following properties:
   • Create cmas-core-security, domain.map.for.oidc.config.\{oidc_config\} and set the URL through which CM/Track is reached as a value, e.g. domain.map.for.oidc.config.MYTRACK1=http://cm.consol.pl:8999/cm-track.
   • Create cmas-core-security, oidc.track3.redirectUri.\{oidc_config\} and set the /oidc endpoint of the CM/Track instance as a value, e.g. oidc.track3.redirectUri.MYTRACK1=http://cm.consol.pl:8999/cm-track/oidc/.
   • Create cmas-core-security, oidc.track3.authority.\{oidc_config\} and set the /cmas-auth-portal-user endpoint of the authentication application as a value, e.g. oidc.track3.authority.MYTRACK1=http://cm.consol.pl:8999/cmas-auth-portal-user.
3. Review the default OIDC configuration, see Reviewing the internal OIDC configuration. If different values are needed, create configuration-specific properties to overwrite the defaults, e.g. oidc.track3.authority.MYTRACK1.