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 on the System properties page. 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 using the system property cmas-core-security, engineer.authentication.method. 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 using the system property cmas-core-security, contact.authentication.method. 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. This is done in the following system properties of the module cmas-core-security. Two placeholders are used in the property names:

• <scope>: Determines if the LDAP server is used for user authentication (value engineer) or contact authentication (value contact).
• <name>: Allows to define configurations for several different LDAP servers. It always needs to be provided, even if you only configure one LDAP server. 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.

Set the following properties on the System properties page of the Web Admin Suite:

• <scope>.authentication.method: LDAP
• ldap.<scope>.<name>.basedn: 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.
• ldap.<scope>.<name>.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.
• ldap.<scope>.<name>.providerurl: 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.
• ldap.<scope>.<name>.searchattr: Search attribute to look up a user / contact by LDAP ID, e.g. uid.
• ldap.<scope>.<name>.userdn: The LDAP user for connecting to the LDAP server to look up the users. Only needed if the lookup cannot be done anonymously.
• ldap.initialcontextfactory: 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 by modifying the following properties in the module cmas-core-security on the System properties page.

The placeholder <scope> is used in the property names for the client for which the OIDC configuration is relevant. This can be the Web Client (value web), Web Admin Suite (value was), CM/Track V3 (value track3) or CM/Track V2 (value track).

• oidc.<scope>.enabled.default: Indicates whether user authentication using SSO via OIDC is enabled. Should be "true".
• oidc.<scope>.authority.default: Indicates the URL of the authenticating authority, e.g. ADFS. Example: https://localhost/adfs
• oidc.<scope>.clientId.default: Indicates the client ID (application ID) of the application, as registered in ADFS or Azure AD.
• oidc.<scope>.clientSecret.default: Indicates the secret of the client, generated using ADFS or Azure AD.
• oidc.<scope>.globalLogout.default: 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. Not relevant for CM/Track V2.
• oidc.<scope>.providerType.default: Should be "external" to use a third-party application, such as Azure AD or ADFS. Not relevant for CM/Track V2.
• oidc.<scope>.redirectUri.default: 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/
• oidc.<scope>.usernameClaim.default: 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".
• oidc.<scope>.usernameRegexp.default: 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.

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 the following system properties:

• cmas-core-security, policy.password.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)

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

• cmas-core-security, policy.rotation.ratio: Number of previous passwords which may not be identical. Default: 5.

• cmas-core-security, policy.username.case.sensitive: 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, scope user) and the portal authentication application (CM/Track V3, scope portal.user).

• cmas.auth.<scope>.2fa.mode: Set to "email" to enable two-factor authentication.
• cmas.auth.<scope>.2fa.email.code.length: Define the length of the one-time code sent by email. Default: 6.
• cmas.auth.<scope>.2fa.email.code.validity.minutes: Define the validity of the one-time code in minutes. Default: 15.
• cmas.auth.<scope>.2fa.rememberBrowser.enabled: Set to "true" to show the Remember this device checkbox on the login screen, which allows the users to skip the second factor.
• cmas.auth.<scope>.2fa.rememberBrowser.period.days: Define the time period for remembering the browser.
• cmas.auth.<scope>.2fa.rememberBrowser.key: Define the key to identify tokens for remembering the browser.
• cmas.auth.<scope>.2fa.whitelist: Define which users can skip two-factor authentication by adding their logins as a comma-separated list.
• cmas.auth.user.2fa.scope: Set to "admin" if two-factor authentication should be required only for users with administrator permissions. Set to "all", 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 following templates on the Templates page of the Web Admin Suite:

• track-auth-2fa-mailcode-template: Template for CM/Track V3
• auth-2fa-mailcode-template: Template for the Web Client and Web Admin Suite

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 on the System properties page. The following properties in the module cmas-core-security are relevant.

The placeholder <scope> is used in the property names for the client for which the OIDC configuration is relevant. This can be the Web Client (value web), Web Admin Suite (value was) or CM/Track V3 (value track3).

• oidc.<scope>.enabled.default: Indicates whether user authentication using SSO via OIDC is enabled. Should be "true".
• oidc.<scope>.authority.default: 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.
• oidc.<scope>.clientId.default: Indicates the ID of the client. Does not need to be changed in the default setup.
• oidc.<scope>.clientSecret.default: Indicates the secret of the client. Does not need to be changed in the default setup.
• oidc.<scope>.globalLogout.default: Determines if the user is also logged out from the OIDC provider when logging out of the client. Should be set to "true".
• oidc.<scope>.providerType.default: Should be "internal" to use the ConSol CM authentication application as OIDC provider.
• oidc.<scope>.redirectUri.default: 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/
• oidc.<scope>.usernameClaim.default: 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".
• oidc.<scope>.usernameRegexp.default: Defines the regular expression used for mapping the username claim values to ConSol CM usernames. Should be (.*).

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.