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 (encrypted or plain) 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 current version of Kerberos is V5, which was initially developed in 1993. If you want to really dig into this topic, you might want to read RFC 1510 (initial RFC) or RFC 4120 (V5).
The following components are important in a Kerberos infrastructure:
The Key Distribution Center, which contains two active components:
The single sign-on feature allows users to authenticate against ConSol CM automatically with, e.g., their Windows credentials.
This authentication mechanism ...
The single sign-on feature is based on the Kerberos V5 protocol, which is integrated in the Windows Active Directory (AD).
The ConSol CM server works as a non-Windows Kerberos service and can be installed on any operating system/application server.
The ConSol CM server is part of a Windows domain where the Domain Controller is the Key Distribution Center and also runs the Active Directory which stores the user authentication information.
The following graphic provides an (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 this sections will guide you through the entire configuration process which is required to run ConSol CM with Kerberos authentication.
Figure 409: Kerberos Authentication in a Windows domain for ConSol CM access
The user logs in to the PC/laptop with username and password. The PC/laptop sends a message to the Authorization Server requesting a ticket granting ticket (TGT).
In case pre-authentication has been enabled, a time stamp will be encrypted using the user's password hash as an encryption key. If the Authentication Server reads a valid time when using the user's password hash (stored in the Active Directory) to decrypt the time stamp, the Authentication Server knows that request is not a renewal of a previous request.
In the example, the pre-authentication is disabled.
The Authorization Server verifies the user’s access rights in the Active Directory and the AD provides the user's password for step 3.
The Authentication Service creates a Ticket Granting Ticket (TGT) and a session key. These are sent in a message to the client, encrypted with a key derived from the user’s password.
The PC/laptop prompts the user for a password and uses the password to decrypt the incoming message. When decryption succeeds, the user will be 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.
When the user wants access to a service, i.e., when an engineer wants lo log in to ConSol CM, the workstation client application (CM 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.
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 (engineer) name. It also contains the realm/domain name and service ticket lifespan. The Service Ticket is encrypted using the Services (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.
The client application (CM 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).
The client/server session is in operation.
Usually, Kerberos is run with symmetric encryption (i.e., one key is used to encrypt and decrypt the message). In Kerberos, encryption is based on the user's password. Optionally, public-key cryptography might be used in a Kerberos environment.
Microsoft Windows uses Kerberos as default authentication method, using RC4 for encryption, together with HMAC (Hash-based Message Authentication Code).
A Kerberos principal is a unique identity to which Kerberos can assign tickets. This might be a user's (person's) 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.
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 means, when the password of the (system) user (tomcat in our example) has changed, not when a CM engineer has changed his password.
For Kerberos-based single sign-on in ConSol CM you need:
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! For example, a time server/service based on NTP can be used. (Some Win DCs tolerate a max. five-minute difference.)
In order to work with SSO as CM engineer, the respective CM server has to be a member of a Windows domain. The domain controller acts as Kerberos Key Distribution Center (KDC) and the user/account names and passwords are managed in the Active Directory. Therefore, you have to
ConSol CM has to be registered as Kerberos service so that Kerberos service tickets can be created for users who want to work with CM. Therefore CM has to be registered with Kerberos. Because CM runs under a certain system user (tomcat in our example) this system user has to be registered for the respective machine. This is why you will have to
Since it is not the system user (tomcat) who will then work with CM but the CM engineers,
On the CM machine, it is required to configure the application server in a way that Kerberos can be used and to let CM know where to find the keytab file with its system user and principal name to use in Kerberos encryption and communication. This is why you have to
For users who want to use SSO with Kerberos and CM, a CM engineer name must be assigned to a Kerberos principal name. This is why you have to
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 mywin2003srv, the domain is MYSSODOMAIN.COM.
First, the ConSol CM server machine needs to be registered in the Active Directory of the domain controller. In our example, the domain controller is the computer MyComputer.
The radio button Trust this computer for delegation to any service (Kerberos only) must be activated!
execute: dsamsc, machines
Figure 410: Registering the ConSol CM server machine
Second, 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 tomcat.
The following account options must be enabled:
execute: dsamsc, users
Figure 411: Registering the ConSol CM server user
Make sure that the CM application server process (e.g., JBoss) runs under the indicated user on the CM machine!
On the domain controller the ConSol CM server is created as a new (non-Windows) Kerberos service and a Kerberos keytab file is 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:\Program Files\Support Tools>ktpass /out tomcat.keytab /ptype KRB5_NT_PRINCIPAL /princ HTTP/MyComputer.MySSODomain.com@MYSSODOMAIN.COM /pass consol.123 /mapuser tomcat /crypto rc4-hmac-nt
If ktpass is not available, the Windows Server 2003 Support Tools must be installed, available here.
/out tomcat.keytab
=> Use tomcat.keytab as output file
/ptype KRB5_NT_PRINCIPAL
=> Specifies the principal type.
/princ HTTP/MyComputer.MySSODomain.com@MYSSODOMAIN.COM
=> Specifies the Kerberos principal name in the form host/computer.<domain>@<realm> . See User logon name in configuration (figures above)
/pass consol.123
=> sets the password for the princ user indicated with /princ
/mapuser tomcat
=> 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:
Run the application server (e.g., JBoss) under the system user which is registered in the Windows domain (tomcat in our example).
Install ConSol CM as usual, then enable and configure Kerberos as described in the next steps.
If you do an initial set-up, 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.
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.)
../jboss/server/{domain}/conf/cm6-kerberos.properties../{domain}/cm6-kerberos.properties<module xmlns="urn:jboss:module:1.1" name="com.consol.cmas">
<resources>
<resource-root path="."/>
</resources>
</module>
<subsystem xmlns="urn:jboss:domain:ee:1.1">
...
<global-modules>
<module name="com.consol.cmas" slot="main" />
</global-modules>
</subsystem>
<subsystem xmlns="urn:jboss:domain:ee:2.0">
...
<global-modules>
<module name="com.consol.cmas" slot="main" />
</global-modules>
</subsystem>
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 .properties file should contain:
# path to kerberos configuration
kerberos.config.location=C:\\conf\\krb5.ini
# one or more service principals (principal = path to keytab file)
HTTP/MyComputer.MySSODomain.com@MYSSODOMAIN.COM=C:\\conf\\tomcat.keytab
Code example 75: cm6-kerberos.properties
[libdefaults]
default_realm = MYSSODOMAIN.COM
default_tkt_enctypes = rc4-hmac des-cbc-md5 des-cbc-crc des3-cbc-sha1
default_tgs_enctypes = rc4-hmac des-cbc-md5 des-cbc-crc des3-cbc-sha1
[realms]
MYSSODOMAIN.COM = {
kdc = mywin2003srv
admin_server = mywin2003srv:8888
}
[domain_realm]
.mywin2003srv = MYSSODOMAIN.COM
mywin2003srv = MYSSODOMAIN.COM
Copy the keytab file you generated on the domain controller to the location you specified in the cm6-kerberos.properties config file.
You have to restart the ConSol CM server process for this change to take effect!
When the system property cmas-core-security, kerberos.v5.enabled has been set to true, the field Kerberos Principle Name will be available for engineer data.
Figure 412: ConSol CM Admin Tool - Kerberos Principal Name in engineer data
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 of 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 username (Login) will be used. If Kerberos authentication fails, the regular authentication mechanism (DATABASE, LDAP) will be used. In that case, single-sign-on is not possible and the login dialog will be displayed for the engineer.
Internet Explorer needs to be configured so that an automatic login is enabled. By default, this is allowed in the medium-low security setting, which by default is set for the local Intranet zone.
The following settings for login behavior are available.
Figure 413: Internet Explorer login configuration
Each setting and the resulting behavior:
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:
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.
An engineer using single sign-on to log into ConSol CM will notice that ...
It is still possible to login 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.
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:
# path to kerberos configuration (think krb5.conf or krb5.ini)
kerberos.config.location=/etc/krb5.conf
# one or more service principals (principal = path to keytab file)
HTTP/MyServerMyDomain.com@MYDOMAIN.COM=/etc/krb5_mycompanycom.keytab
HTTP/MyServer.MyDEDomain@MYDOMAIN.DE=/etc/krb5_mycompanyde.keytab
Using Kerberos-based single sign-on, the Kerberos principal (i.e., the user's OS login) has to be mapped to a ConSol CM engineer name.
By default, this mapping is done using one of the following two ways:
If further customization is needed please refer to UsernameAdapter interface javadoc.
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.