Single Sign-On in a Windows Domain Using Kerberos

Short Introduction to Kerberos

Kerberos is a network protocol which is used to authenticate a user or a system to verify if a user or system has the identity it claims to have. The authentication mechanism is based on so called tickets. When a user or system has been authenticated by a Kerberos system, other systems, e.g., a ConSol CM server, can rely on this authentication and grant access for the user or system to their own resources. One of the advantages of using Kerberos is that no passwords are sent over the network. Only information which has been encrypted using the password is sent. Once authenticated, a client has access to all resources within the Kerberos domain/realm without any further login (single sign-on, SSO).

The following components are important in a Kerberos infrastructure.

The Key Distribution Center, which contains two active components:

• Authentication service
  Performs the authentication (e.g., using Microsoft Active Directory) and creates a ticket granting ticket (TGT) if the user or system has been authenticated successfully.
• Ticket granting service
  Creates tickets which will grant access to other systems. The user or system who/which wants to receive a service ticket has to present a TGT in order to get this service ticket.

Short Introduction into ConSol CM with Kerberos in a Windows Domain

The single sign-on feature allows users to authenticate against ConSol CM automatically with their Windows credentials.

This authentication mechanism ...

• works completely transparent, no user interaction is required (i.e., filling in credentials on a login screen)
• does not interfere with existing authentication mechanisms. If the Kerberos authentication fails, the configured authentication mechanism (LDAP or database authentication, see cmas-core-security, authentication.method) is used.

The single sign-on feature is based on the Kerberos V5 protocol, which is integrated in the Windows Active Directory.

The ConSol CM server works as a non-Windows Kerberos service and can be installed on any operating system / application server. The domain controller is the Key Distribution Center and also runs the Active Directory which stores the user authentication information.

The following graphic provides a simplified overview of the steps which are required in order to provide a valid client/server session for a ConSol CM client and the respective ConSol CM server. The explanations in these sections will guide you through the entire configuration process for running ConSol CM with Kerberos authentication.

Figure 434: Kerberos Authentication in a Windows domain for ConSol CM access

Steps in the Authentication Process

Step 1: Send Account Name, Request a Ticket Granting Ticket (TGT) and Session Key

The user logs in to the computer with a user name and password. The computer sends a message to the authorization server requesting a ticket granting ticket (TGT).

If pre-authentication is enabled, a timestamp is encrypted using the user’s password hash as an encryption key. The authentication server decrypts the timestamp with the user’s password (stored in the Active Directory). If it reads a valid time, it knows that the request is not a renewal of a previous request.

In the example, the pre-authentication is disabled.

Step 2: Verify Rights for Account, Provide Password for Account

The authorization server verifies the user’s access rights in the Active Directory and the Active Directory provides the user’s password for step 3.

Step 3: Deliver a Ticket Granting Ticket (TGT) and Session Key (Message Encrypted Using the Client’s Password)

The authentication service creates a ticket granting ticket (TGT) and a session key. These are sent in a message to the client and encrypted with a key derived from the user’s password.

The computer prompts the user for a password and uses the password to decrypt the incoming message. If the decryption succeeds, the user is able to use the TGT to request a service ticket.

Step 3a: The TGT is saved for the user for the TGT's lifetime and can be used for all service ticket requests during this period of time.

Step 4: Request a Service Ticket for CM

When the user wants access to a service, i.e., when an engineer wants lo log in to ConSol CM, the workstation client application (Web Client) sends a request to the ticket granting service containing the SPN (Service Principal Name) of the requested service, the client name, the realm/domain name, and a timestamp (name and timestamp encrypted with the session key). The user proves his identity by sending an authenticator (TGT) received in step 3.

Step 5: Deliver a Service Ticket for CM (= Ticket and Session Key)

The ticket granting service decrypts the ticket and authenticator, verifies the request, and creates a service ticket for the requested service (SPN = ConSol CM). The service ticket contains the user name. It also contains the realm/domain name and service ticket lifespan. The service ticket is encrypted using the service’s (CM's) secret. The ticket granting service sends the service ticket to the user.

Step 5a: The service ticket is saved for the user for the service ticket’s lifetime and can be used for all requests to the SPN during this period of time.

Step 6: Present the Service Ticket for CM (= Ticket and Session Key)

The client application (Web Client) now sends a service request to the CM server containing the ticket received in step 5 and an authenticator. The service (CM server) authenticates the request by decrypting the session key. The CM server verifies that the service ticket and authenticator match, and then grants access to the service (ConSol CM application).

Step 7: Open Client/Server Session

The client/server session is in operation.

Encryption in the Process

Usually, Kerberos is run with symmetric encryption (i.e., one key is used to encrypt and decrypt the message). The encryption is based on the user’s password. Optionally, public-key cryptography might be used in a Kerberos environment.

Microsoft Windows uses Kerberos as a default authentication method, using RC4 for encryption, together with HMAC (Hash-based Message Authentication Code).

Kerberos Terminology

Kerberos Principal

A Kerberos principal is a unique identity to which Kerberos can assign tickets. This might be a person’s user account or a system user account. Kerberos principals are composed of a number of components. Each component is separated by a component separator, usually "/". The last component is the realm/domain, separated from the rest of the principal by the realm/domain separator, usually "@". If there is no realm/domain component in the Kerberos principal, then it will be assumed that the principal is in the default realm/domain for the current environment.

Usually, a Kerberos principal is composed of three parts: the primary, the instance, and the realm/domain. The format of a typical Kerberos V5 principal is primary/instance@REALM.

• The primary is the first part of the principal, this is the user name (in case of a person's account) or the name/account of a system user or a host name.
• The instance is an optional string that qualifies the primary. The instance is separated from the primary by a slash (/). In the case of a user, the instance is usually null, but a user might also have an additional principal, with an instance called admin, which he uses to administrate a database. The principal cmlxuser@CONSOL.DE is completely different from the principal cmlxuser/administrator@CONSOL.DE, with a separate password and separate permissions. In the case of a host, the instance is the fully qualified hostname, e.g., cmserver.consol.de.
• The realm is the Kerberos realm, usually the domain name, in upper-case letters. For example, the machine cmserver@consol.de would be in the realm CONSOL.DE.

Keytab File

A keytab is a file containing pairs of Kerberos principals and the respective encrypted keys (which are derived from the Kerberos password). When a password is changed, you need to rebuild the keytab file. In the ConSol CM context this happens when the password of the system user (in our example cmwinuser for Windows and cmlxuser for Linux/Unix) has changed, not when a CM engineer has changed his password.

Setting Up Kerberos Single Sign-On for ConSol CM

Requirements

For Kerberos-based single sign-on you need:

• Domain controller for the Windows domain
• ConSol CM server
• Windows clients

Since in a Kerberos environment, timestamps are used to calculate and check the time period of validity of the tickets, it is absolutely indispensable that all components work with the same system time! A time server/service based on NTP can be used for example. (Some Windows domain controllers tolerate a maximum time difference of five minutes.)

The Windows domain used in the example is SSO.CONSOL.DE and the domain controller is called winadsrv.

Basic Principle and Required Steps

The user/account names and passwords of the CM engineers are managed in the Active Directory and the domain controller acts as Kerberos Key Distribution Center (KDC).

In the following chapters we distinguish between a CM server running on a Windows or running on a Linux/Unix system.

On Windows:

The computer running the CM server has to be a member of the Windows domain.

• Register the CM server as Windows domain member. Since it is not the system user (cmwinuser) who will work with CM but the CM engineers, the option Trust this computer for delegation to any service has to be set in the KDC. In this way, the system user can “impersonate” other users (the CM engineers).

  See Registering the ConSol CM Server and User.

• Build a keytab file for the system user cmwinuser for the CM machine. This registers CM as Kerberos service, so that Kerberos tickets can be processed on the ConSol CM server side.

  See Generating the keytab File.

On Linux/Unix:

• Register the CM server as Service Principal Name (SPN) on the Windows domain server.

• Create the domain account cmlxuser to which the SPN is assigned. Since it is not the domain user (cmlxuser) who will work with CM but the CM engineers, the option Trust this computer for delegation to any service has to be set in the KDC. In this way, the domain account can “impersonate” other users (the CM engineers).

  See Registering the ConSol CM Server and User.

• Build a keytab file for the SPN of the CM machine. This registers CM as Kerberos service, so that Kerberos tickets can be processed on the ConSol CM server side.

  See Generating the keytab File.

On Windows and Linux/Unix:

On the CM machine, it is required to configure the application server in a way that Kerberos can be used. CM needs to know where to find the keytab file to use Kerberos encryption and communication.

• Define the respective module in the application server.
• Store the keytab file on the CM server.
• Edit the cm6-kerberos.properties file.

See Configuring Kerberos.

For users who want to use SSO with Kerberos and CM, a CM engineer name must be assigned to a Kerberos principal name:

• Define Kerberos principal names for the CM engineers in the Engineers section of the Admin Tool.

See Configuring the CM Engineers for Kerberos.

Operations to Be Performed on the Domain Controller

The first step is to configure the domain controller so that it knows the ConSol CM server, i.e., to integrate the CM server into the Windows domain.

In our example the domain controller is called winadsrv, the domain is SSO.CONSOL.DE.

Registering the ConSol CM Server and User

On Windows:

The ConSol CM server machine needs to be registered in the Active Directory of the domain controller. This is done in the Computers administration of the Active Directory.

The radio button Trust this computer for delegation to any service (Kerberos only) must be enabled.

The user under which the ConSol CM server process will run is created and registered in the Active Directory (which acts as Key Distribution Center), in our example the user is called cmwinuser. This is done in the Users administration of the Active Directory.

The following account options must be enabled:

• Account is trusted for delegation
• No Kerberos pre-authentication needed

Make sure that the CM application server process runs under the indicated user on the CM machine.

On Linux:

First it is necessary to create a Windows domain account. ConSol CM is assigned to this account in the next step. We use the name cmlxuser for this account.

The radio button Trust this user for delegation to any service (Kerberos only) must be enabled in the Delegation tab.

Use the following command to assign the ConSol CM server to the created account.

You can show the assignment with the following command:

Generating the keytab File

On the domain controller, a Kerberos keytab file has to be generated. This file will be required later on the ConSol CM server machine. The keytab file contains the shared secret key of the service (SPN, Service Principal Name).

Use the following ktpass command:

C:\Users\Administrator> ktpass /princ HTTP/cmserver.consol.de@SSO.CONSOL.DE /pass consol123 /mapuser cmlxuser /pType KRB5_NT_PRINCIPAL /out c:\cmserver.http.keytab /crypto rc4-hmac-nt

If ktpass is not available, the Windows Server 2003 Support Tools must be installed, available here.

Explanation of the ktpass command

/out cmserver.http.keytab

=> Uses cmserver.http.keytab as output file

/ptype KRB5_NT_PRINCIPAL

=> Specifies the principal type.

• KRB5_NT_PRINCIPAL is the general principal type (recommended).
• KRB5_NT_SRV_INST is the user service instance.
• KRB5_NT_SRV_HST is the host service instance.

/princ HTTP/cmserver.consol.de@SSO.CONSOL.DE

=> Specifies the Kerberos principal name in the form http/computer.<domain>@<realm>.

/pass consol.123

=> Sets the password for the princ user indicated with /princ.

/mapuser cmlxuser

=> Maps the name of the Kerberos principal (/princ parameter) to the specified domain account.

/crypto rc4-hmac-nt

=> Specifies the keys that are generated in the keytab file (optional):

• DES-CBC-CRC is used for compatibility.
• DES-CBC-MD5 adheres more closely to the MIT implementation and is used for compatibility.
• RC4-HMAC-NT employs 128-bit encryption.
• AES256-SHA1 employs AES256-CTS-HMAC-SHA1-96 encryption.
• AES128-SHA1 employs AES128-CTS-HMAC-SHA1-96 encryption.
• All states that all supported cryptographic types can be used.

Operations to Be Performed on the ConSol CM Server

Run the application server under the system user which is registered in the Windows domain (in our example cmwinuser for Windows and cmlxuser for Linux/Unix).

Install ConSol CM as usual, then enable and configure Kerberos as described in the next steps.

Enabling Kerberos in ConSol CM

If you do an initial setup, you can choose whether Kerberos should be enabled. Please note that this is only a hint and additional configuration is needed (see next steps).

If your ConSol CM is already configured without Kerberos enabled, you can enable it in the Admin Tool by setting the system property cmas-core-security, kerberos.v5.enabled to true. A server restart is required to activate the new setting.

Configuring Kerberos

A ConSol CM server reads configuration parameters from the file cm6-kerberos.properties from the classpath. (Each cluster node may need separate configurations, so each node will read the cm6-kerberos.properties file from the classpath.)

Example configuration for JBoss 7:

1. Create a directory for the Kerberbos configuration at the following path:

   mkdir -p ${jboss}/modules/system/layers/base/com/consol/cmas/main/

2. In this directory, create the file module.xml with the following content:

   <module xmlns="urn:jboss:module:1.1" name="com.consol.cmas">

   <resources>

   <resource-root path="."/>

   </resources>

   </module>

3. Save the cm6-kerberos.properties file in this directory.
4. Edit the configuration file, e.g., ${jboss}/standalone/configuration/cm6.xml

   <subsystem xmlns="urn:jboss:domain:ee:1.1">

   ...

   <global-modules>

   <module name="com.consol.cmas" slot="main" />

   </global-modules>

   </subsystem>

   Code example 86: JBoss 7

In case you have a cluster of more than one ConSol CM servers in operation, each server has to have its own properties file.

The cm6-kerberos.properties file should contain:

• Reference to a Kerberos configuration file (e.g., krb5.ini or krb5.conf)
• One or more service principals, i.e., reference to the keytab file

Code example 87: cm6-kerberos.properties (Windows)

Code example 88: cm6-kerberos.properties (Linux)

Code example 89: krb5.ini

keytab File

Copy the keytab file generated on the Windows domain controller to the location you specified in cm6-kerberos.properties.

You have to restart the ConSol CM server process for this change to take effect!

Configuring the CM Engineers for Kerberos

If the system property cmas-core-security, kerberos.v5.enabled is set to true, the field Kerberos Principle Name is available in the engineer details in the Engineers section of the Admin Tool.

The Kerberos Principal Name is a user name along with the respective Kerberos realm/domain name, for example SusanServiceDesk@consol.de. This allows to authenticate users with the login SusanServiceDesk that belong to different Kerberos realms (SusanServiceDesk@consol.de and SusanServiceDesk@consol.pl are in fact different users). If the field Kerberos Principal Name is empty for an engineer, the user name (field Login) is used. If Kerberos authentication fails, the regular authentication mechanism (DATABASE or LDAP) is used. In that case, single sign-on is not possible and the engineer sees the login dialog.

Mapping Kerberos User Name to Engineer Name

Using Kerberos-based single sign-on, the Kerberos principal (i.e., the user’s Windows login) has to be mapped to a ConSol CM engineer name.

By default, this mapping is done using one of the following two ways:

• Explicit mapping
  
  Take the principal name and try to find a ConSol CM engineer who has this principal stored as Kerberos Principal Name. If such an engineer is found, this engineer is used.
• Mapping via regular expression
  The regular expression defined in the system property kerberos.v5.username.regex is taken and applied to the principal. The result is taken and a ConSol CM engineer with this login is searched:
  • The first matching regular expression group (in brackets) is used as engineer login name,
    e.g., the default property value (.*)@.* converts Huber@SSO.CONSOL.DE to Huber.

If further customization is needed please refer to the UsernameAdapter interface javadoc.

Operations to Be Performed on the Client Machine

Micrsosoft Internet Explorer and Microsoft Edge

Internet Explorer and Edge need to be configured so that an automatic login is enabled. This is done in Internet options -> Security in the Windows Control Panel. By default, the security setting medium-low is used for the Local Intranet zone. This setting allows automatic login.

You can check it by clicking the Custom level button in the settings of the Local Intranet zone. The following settings for login behavior are available in the User Authentication section.

Figure 435: Internet Explorer login configuration

Each setting and the resulting behavior:

• Anonymous logon
  No single sign-on is possible, the user (CM engineer) will get the ConSol CM login dialog.
• Automatic logon only in Intranet zone
  Single sign-on is performed automatically but only if the site is part of the Local intranet zone.
• Automatic logon with current user name and password
  Single sign-on is performed automatically with the current user credentials.
• Prompt for user name and password
  OS displays a login dialog, user can enter OS login information, which is then used in Kerberos authentication.

Firefox

With the default settings, Firefox does not support Kerberos single sign-on. To enable single sign-on, you have to add the URI of the ConSol CM Web Client in the Firefox configuration.

To do this:

• Open about:config.
• Add the web server to the property network.automatic-ntlm-auth.trusted-uris
  (for example http://mycm6server if that is the URI).
  If this does not work, perform the following step:
• Add the web server to the property network.negotiate-auth.trusted-uris
  (for example http://mycm6 server if that is the URI).

You can set this property also in the file system. Open the file

C:\Users\[USER]\AppData\Roaming\Mozilla\Firefox\Profiles\[XYZ].default\prefs.js

and add/replace the following line:

user_pref("network.automatic-ntlm-auth.trusted-uris", "http://mycm6server");

or

user_pref("network.negotiate-auth.trusted-uris", "http://mycm6server");

You have to restart Firefox after this change.

Using Kerberos Single Sign-On with ConSol CM

Single Sign-On from the User’s Point of View

An engineer using single sign-on to log into ConSol CM will notice the following:

• No ConSol CM login screen is displayed.
• Instead, there may be (for a short time) an intermediate text screen (which is used to gather some client data via JavaScript) which immediately forwards the user to the main screen of the ConSol CM Web Client, where a message is displayed:

  

It is still possible to log in as another ConSol CM user by clicking the logout button, which will lead you to the login page, or by explicitly using the .../cm-client/login URL.

Multi Domains Single Sign-On

For each domain which you will enable single sign-on for, create a new domain/user and Kerberos principal and put all of them into the cm6-kerberos.properties file:

Starting and Stopping Kerberos Authentication

Kerberos authentication can be started/stopped in the Admin Tool navigation group Services -> navigation item CM Services -> Kerberos v5 authentication provider, see section CM Services.