Kerberos login

Active Directory authentication via Kerberos

Kerberos is a distributed authentication service for open and non-secured computer networks. The domain controller offers a key distribution center (KDC) for key management in an Active Directory environment. The KDC accesses the active directory of the domain to load user information.

The KDC server and the associated domain name are required in CURSOR-CRM for the Kerberos authentication.

To use Kerberos authentication, the "Single Sign-on" module must be activated in a licensed manner.

Use of the Active Directory user password for the login to CURSOR-CRM

In the default login of CURSOR-CRM, the user name and password are compared with the employee data in the CURSOR-CRM database when logging in. The password will not be checked against employee information if Active Directory authentication is enabled. The user must now enter the user name and password of his Active Directory user when logging in. The user name in the domain and the employee token in CRM must match to ensure that the correct employee is found during the login process. Alternatively, the administrator can set a login name for the employee to create an explicit allocation between the domain user and the employee in CURSOR-CRM. If several domains are used for the login, please refer to the information in the Selecting the realm section.

The employee token and the login name of all employees must be unique in CURSOR-CRM, otherwise it is not possible to map a login name to exactly one employee when logging in. If this assignment is not clear, the login is not possible for any of the conflicting employees.

At login, the client (Rich Client, Web Client, app) transmits the login data to the application server via a secure, encrypted connection. A valid SSL certificate (X.509 certificate) must be set up on the JBoss application server to secure the connection.
The application server requests a ticket from the KDC using the login data and verifies their validity. The login data are kept encrypted for the session in memory and reused as needed (e.g. communication with WebServices or Groupware).

For special external interfaces not based on HTTPS, such as the JMX console, the password may be transmitted unencrypted. Therefore, caution is advised when using unencrypted interfaces.

Use of the Active Directory user password for the login to web services and Groupware

If web services are called by the user in CURSOR-CRM, the user's login information stored in encrypted form for the current session can be accessed, if necessary. The web service configuration must be set to enableLoginViaCurrentUser(true);. If Single Sign-on was used for login, no password is stored in the session and the user must enter the password once. Afterwards, this is then kept in memory encrypted for the session just as it is when logging in with a password.

The administrator can activate the Active Directory authentication explicitly in the system settings for the server-side Groupware connection (IMAP, SMTP, Domino, EWS). The domain password entered and the user name of the domain user are then used for logging in to the Groupware system. The user does not enter a password when Single Sign-on is used. The user will have to enter the password one time, as the server-side Groupware integration requires a password. The password is saved in the memory for the duration of the session. The password can also be saved in the employee dataset. It will be persisted in the database with symmetrical encryption. The employee field "Groupware user name" will then be read-only and will no longer be used. When a mail configuration is used and assigned to a user, then the saved user name and password for that mail client will be used.

Single Sign-on (Autologin) with Kerberos

Kerberos enables the automatic login of employees according to the Single Sign-on principle. When logging in to CURSOR-CRM, the Kerberos session existing on the Windows computer is used. The CURSOR-CRM client then issues a so-called service ticket and sends it to the application server. This checks the validity of the ticket and can thus securely authenticate the user.
Thereby the input of user passwords is not necessary when logging on to CURSOR-CRM.

Single Sign-on technology is supported by both the Rich Client and the Web Client. Technically, the rich client uses the Kerberos protocol directly, while the web client uses the SPNEGO (Simple and Protected GSSAPI Negotiation Mechanism) protocol to enable Kerberos login with the browser.

In order to use Single Sign-on, the corresponding settings in the domain, the application server and the rich client configuration must first be configured correctly. If you are using Single Sign-on for the Web Client, you may also need to configure the browsers used. The configuration of these areas is described in more detail in the relevant sections.

After setup, the automatic login can be activated individually for each employee. For this purpose, the "Autom. Login" check box must be activated in the employee dataset. When using Single Sign-on, the mapping of domain users to employees in CURSOR-CRM takes place in the same way as when logging in with the Active Directory user password. Therefore, the "Login Name" field must also be filled with the correct value here if necessary.

The Active Directory authentication is only supported on the app without Single Sign-on. So here the login must be done with the Active Directory username and password.
If the user utilizes the server-side Groupware interface or web services, then he will have to input his domain password one time, as these interfaces do not support Kerberos ticket logins.

Installation requirements

The JBoss application server must be run with Kerberos authentication enabled and in the user context of a valid domain user to allow KDC access. All employees in CURSOR-CRM must be assigned to a domain user. The same applies for the default user TECH_USER. A technical user must therefore be created in the domain.

Additional requirements for Single Sign-on

Single Sign-on requires the additional configuration of a so-called Service Principal Name (SPN) in the domain. The SPN should be structured as follows for maximum compatibility: HTTP/<fully qualified host name of the application server>.
The membership of the SPN in a domain results in the following fully qualified principal name: HTTP/<fully qualified host name of the application server>@<domain name>

For Single Sign-on to work in the Web Client, the SPN must be set to the exact host name that will later be used in the Web Client URL.

Special care must be taken when setting up the SPN in conjunction with alias names for the application server. Here it must be ensured that the alias name associated with the SPN is kept as an A record in the DNS.

When using CNAME records, different problems can occur depending on the browser or operating system used. Since the procedure for SPN construction in connection with CNAME records is not standardized, the behavior can even change depending on the version of the browser and/or operating system used. For this reason, you should never use CNAME records for these host names, but always A records.

The first step is setting up an SPN in the domain. This must be done by a domain administrator if you are using Microsoft Active Directory (AD). The SPN is assigned to the service user the application server is associated with. The format HTTP/<fully qualified host name of the application server> is used within AD. The domain suffix (e.g. @CURSOR.DE) is derived by AD automatically and must not be entered by the user.

In order to set the SPN in Active Directory, you will first have to activate "Advanced Features" in the menu "View" of the AD administration console (“Advanced Features”).
This will enable the tab "Attribute editor" in the features for AD users. This is where you can set the SPN.

By using the CURSOR-CRM service user for the Kerberos login, it is especially important that the service user password is long and secure. In particular, it should not be easily guessable, but should be as long and randomly generated as possible.

For this purpose, Active Directory offers the possibility to set up so-called "Managed Service Accounts" or "Group Managed Service Accounts". These use internally automatically managed, extremely long, secure and even automatically periodically changing passwords. If possible, this form of password management should be chosen for maximum security.

When operating the CURSOR CRM server on Linux, such managed accounts can unfortunately not be used without further configuration work. Here, instead, a very long and secure password must be assigned manually and also changed periodically.

Should the Single Sign-On not work after all components have been configured, then you can check the SPN configuration from any Windows PC in the domain. Use the Windows-supplied program setspn for the check.

The command setspn -L <username> will list all SPNs configured for the specified user.

The command setspn -Q <SPN> displays the user to whom the specified SPN is assigned.

To manually retrieve the service ticket for the CRM login as a test, you can use the klist program supplied with Windows.

The klist get <SPN> command uses the current Kerberos session to retrieve a service ticket for the specified SPN. If an error occurs, an error message is issued. If successful, a list of all saved tickets of the current session is displayed, including the newly requested ticket. This information may be useful for troubleshooting.

Application server configuration

The Kerberos authentication must be activated for the JBoss application server in the system settings under Password settings. The server configuration is used in Web Client, CURSOR App and server interfaces (e.g. web services). "Advanced password security" will be deactivated when Kerberos authentication is active. A mixed operation of database authentication and Kerberos authentication is not possible. The user password can no longer be changed via the application. A re-login will be required to apply changes.

The following setting options are available:

Option	Description
Enable ActiveDirectory for authentication	Activated The Kerberos authentication can be activated and deactivated here. Deactivated If the Kerberos configuration doesn't work correctly and therefore nobody can log on to the system, then you can deactivate the Kerberos authentication via the following SQL statement: SQL `update propertymapper set propertyvalue = 'false' where id = '/de/cursor/jevi/common/session/SessionVO$!!$use.LDAP';`
Realms (Domains)	A realm can be e.g. the DNS domain name ("CURSOR.DE"). As of version 17.1.8, additional realms can be added using comma separators ("CURSOR.DE,ACADEMY.CURSOR.DE"). This will allow users from all listed realms to log in. The configuration format was extended as of version 17.2, so that the NetBIOS domain name and the fully qualified domain name (FQDN) can be added for each domain. This is particularly important if the NetBIOS domain name and the FQDN differ. The format looks as follows: `<NetBIOS Domainname1>[<FQDN1>],<NetBIOS Domainname2>[<FQDN>]` (and so on) To ensure downward compatibility, the FQDN is optional for application servers based on Windows.
Domain Controller	Name of the KDC server ("KDC.CURSOR.DE") matching the relevant realm. Additional KDC servers must be listed with comma separators ("KDC.CURSOR.DE,KDC2.CURSOR.DE") if multiple administration areas were provided. Important: the order of KDC server entries must match the order of the domain entries.
Service Account Username (Linux)	Only required for application servers on Linux for Single Sign-on. For Windows servers, filling out this setting can be omitted because the user context of the service is used. The fully qualified user name of the domain user, who has access to the Kerberos Service Principle Name (SPN) of the server. ("cursor-crm-user@CURSOR.DE") To log in to the KDC server, a Kerberos Keytab file must be configured in the JBoss server.
Groupware Kerberos Login	Activated Used for the Kerberos authentication when logging in to server-side Groupware systems. Deactivated

Creation and configuration of a Kerberos Keytab file (Linux)

For Kerberos authentication under Linux, a domain user must be defined for logging in to the KDC server (domain controller). The user name can be stored in the system preferences for password security. The password is stored in a Kerberos Keytab file on the server and configured in the JBoss server. Here it must be ensured that only the own user has access to the file.

JBoss/bin/standalone.conf

CODE

...
# Pfad für Keytab Passwort Datei für Kerberos Login unter Linux. [Standard 'leer', z.B. $HOME/user.keytab]
export KEYTAB_PATH=$HOME/user.keytab
...

Under Linux a Keytab file can be created with the tool ktutil. Thereby the following steps have to be executed.

Caution

Especially on Linux operating systems, the domain name always has to be specified in capital letters (for example, EXAMPLE.COM), otherwise the various Kerberos utilities will not work properly.

In the following example, a keytab is created with different Encryption Types for maximum compatibility with both older and current versions of Active Directory and Windows. If existing security guidelines prohibit some of these types, the corresponding entry can be omitted during creation. For example, RC4 (arcfour-hmac) is now often disabled domain-wide.

In case of Single Sign-on problems in connection with Linux servers, it may be useful to check which encryption type is used for the Kerberos ticket by means of the Windows command klist on the client computers. This encryption type must then also be included in the keytab.

Shell on the Linux server

BASH

# Anmeldung als Dienstbenutzer
$ kinit <Benutzername@DOMAINNAME>
Password for <Benutzername@DOMAINNAME>: 


# Ermitteln der kvno, wird im nächsten Schritt benötigt
$ kvno <SPN>
<SPN>: kvno = 17


# Abmeldung des Dienstbenutzers
$ kdestroy


# Erstellen des Keytabs
$ ktutil
ktutil:  addent -password -p <Benutzername@DOMAINNAME> -k <kvno> -e arcfour-hmac
Password for <Benutzername@DOMAINNAME>:
ktutil:  addent -password -p <Benutzername@DOMAINNAME> -k <kvno> -e aes128-cts-hmac-sha1-96
Password for <Benutzername@DOMAINNAME>:
ktutil:  addent -password -p <Benutzername@DOMAINNAME> -k <kvno> -e aes256-cts-hmac-sha1-96
Password for <Benutzername@DOMAINNAME>:
ktutil:  wkt /home/<Linux JBoss Benutzer>/<Benutzername>.keytab
ktutil:  q


# Zum Prüfen der Anmeldung:
$ kinit -k -t /home/<Linux JBoss Benutzer>/<Benutzername>.keytab <Benutzername@DOMAINNAME>


# Abmeldung des Dienstbenutzers
$ kdestroy

Rich Client configuration

The Kerberos authentication for the Rich Client is configured in the file configuration.bat. Available are the variables KERBEROS_REALM and KERBEROS_KDC. These must be populated just like the system settings Administration area (Domain) and Key Distribution Center (KDC).

Additionally, the variable KERBEROS_SPN is provided for Single Sign-on. The Service Principal Name (SPN) configured for the application server must be entered here.
At this point the format HTTP/<fully qualified host name of the application server>@<domain name> must be used, e.g. "HTTP/CURSORCRM-HOST.CURSOR.DE@CURSOR.DE".

Check the file configuration.bat after the update to ensure it contains the correct values, as otherwise a login will not be possible.
Depending on the configuration of their Windows domain, employees may be locked after a certain number of unsuccessful attempts across the domain.

Configuration of browsers

In order to use Single Sign-on in the Web Client, the browsers used must also be configured. The Microsoft Internet Explorer, Microsoft Edge and Google Chrome use the Internet options of Windows. Firefox, by contrast, uses its own setting. The correct configuration for each browser is described below.

If the browser is configured incorrectly, a password request similar to the following screenshot may occur when opening the Web Client:

Temporarily the problem can be avoided by selecting "Cancel" in this dialog. Then a manual login process with user name and password can be carried out via the CURSOR CRM login mask.

If this occurs, the configuration of the browser used on the affected computer should be checked again.

Internet options (Internet Explorer, Edge and Chrome)

The browsers Microsoft Internet Explorer, Microsoft Edge and Google Chrome all access the Internet options of Windows internally. These can be reached easiest in the settings of Internet Explorer via the menu item "Internet options".
The following settings must be made there:

Manual settings

Internet Options → "Advanced" tab → "Security" section → "Activate Integrated Windows Authentication": Activated
Internet Options → "Security" tab → Zone "Local Intranet” → "Custom Level” → Section "User Authentication” → Section "Login": "Auto login with current user name and password" or "Auto login only in the intranet zone"
Internet Options → "Security" tab → "Local Intranet" zone → "Sites” → "Advanced": Either add the entire domain (for example *.example.com) or the FQDN of the CRM server (for example cursor-crm.example.com) using wildcards

Setting via group policy

In order not to have to make these settings manually on each computer, they can be distributed in the domain via group policy. The group policies used for this purpose are as follows:

User Configuration\Settings\System Control Settings\Internet Settings → Create new → "Internet Explorer 10": As with the manual setting, "Activate Integrated Windows Authentication"
Computer Configuration\Administrative Templates\Windows Components\Internet Explorer\Internet System Control\Security Page\Intranet Zone → "Login Options": "Auto login with current user name and password" or "Auto login only in the intranet zone"
Computer Configuration\Administrative Templates\Windows Components\Internet Explorer\Internet System Control\Security Page → "Site List for Zone Assignment": Store the FQDN of the CRM server or placeholders for the entire domain

Firefox

Under about:config → network.negotiate-auth.trusted-uris the SPNEGO authentication must be allowed for the CRM host. The value of this setting is a comma-separated list of URL prefixes or domains.
If, for example, the CRM can be accessed at https://crm.example.com, https://crm.example.com or crm.example.com can be entered here.

If, for example, the SPNEGO authentication is to be enabled for all subdomains in a company, a kind of wildcard can be defined. The value .example.com allows the SPNEGO authentication on all subdomains of example.com.

More information about this configuration can be found in the Mozilla documentation. For the auto distribution of this setting, consult the Mozilla documentation.

Selecting the realm

The user name can be used to select the administration area against which authentication is performed. Only those realms configured in the system settings are available. The new format "user@ADMINISTRATIONAREA" and the older format "ADMINISTRATIONAREA\user" can be used. The login mask is initialized with the realm, via which the user is logged in to the operating system. In Windows, the system will first try to derive the realm from the environment variable "USERDOMAIN". If none is set (e.g. because a local account is used), then the default realm (the first in the list) will be used. In Unix, the default realm will in this case be used directly. The same applies if no realm is entered and only the user name instead.

Examples:

Administration areas: "CURSOR.DE,ACADEMY.CURSOR.DE"

Logged in to Windows with bne@cursor.de: bne => bne@CURSOR.DE
Logged in to Windows with bne@akademie.cursor.de: bne => bne@AKADEMIE.CURSOR.DE
Logged in under Windows with local account: bne => bne@CURSOR.DE
No matter how logged in: bne@CURSOR.DE stays bne@CURSOR.DE