Kerberos ticket (integrated Windows login)

JAAS module name: de.espirit.firstspirit.server.authentication.KerberosLoginModule

To log in, a Kerberos ticket is accepted, which is transferred from the web browser to FirstSpirit-Server. If using this login module, the FirstSpirit editor only needs to log in to their workstation (Windows, Mac, GNU/Linux) once, provided that a Kerberos infrastructure exists, and can then use FirstSpirit without renewed password input. Under Microsoft Windows, Kerberos is already known since Windows 2003 and XP as an “Integrated Windows login” and therefore replaces NTLM.

Parameter:

useFullPrincipal

Defines whether the full Kerberos login name including @ characters and realm (value true) or without @ and realm (value false) is used as the FirstSpirit user name.  false  is sufficient for systems whose user accounts are all entered in a Kerberos realm (corresponds to an Active Directory Domain under Windows). If logins take place from several Kerberos realms or Active Directory Domains, true must be given, as in most cases the pure user name is not unique over several domains.        
Default value: false

userAgents

Here it is possible to enter a search pattern to activate Kerberos login for selected web browsers only, as Kerberos uses an HTTP header which does not fully conform to the standard ("WWW-Authenticate: Negotiate"); several older web browsers interpret this as an error. To use Kerberos for all web browsers, enter ".*".                                   
Default value: .*(Chrome|Firefox|Iceweasel|Konqueror|MSIE|Trident|Opera|Safari|Shiretoko).*

sendAccepted

This parameter can be used to influence the HTTP status code in the case of a handshake. If the handshake is successful, OK (200) is sent. ACCEPTED (202) was sent prior to FirstSpirit Version 5.2R2. Depending on the infrastructure in use, this status (202) may not be accepted as “valid”, something which may cause indexing problems, for example (the SharePoint crawler in Windows is a known problem). This default behavior has therefore been changed as of 5.2R2. It is possible to restore the old behavior by setting the parameter sendAccepted to the value true (default value: false). It is only possible to set this parameter using a corresponding entry in the fs-jaas.conf file (websso area):

de.espirit.firstspirit.server.authentication.KerberosLoginModule sendAccepted="true";

The KerberosLoginModule is entered in the websso area of the fs-jaas.conf file. In addition, the following new area must be added in the same file, at the end of the file:

com.sun.security.jgss.accept {
  com.sun.security.auth.module.Krb5LoginModule required
    principal="HTTP/fs5host.mydomain.net@MYDOMAIN.NET"
    keyTab="/opt/firstspirit5/conf/fs5host-HTTP.keytab"
    useKeyTab="true"
    storeKey="true"
    isInitiator="false"
    doNotPrompt="true"
    debug="true";
};

The paths and domain names must be adjusted according to the local system. The following parameters must be adjusted:

principal

The Service-Principal name of the FirstSpirit-Servers is given here.

keyTab

The path to the Kerberos-Keytab file is given here, which contains the private key, mostly in different encryption methods (e.g. DES and AES), matching the Service-Principal name. This file must be created first, as described in the following Chapter.

Notes on the service principal name (SPN):

The keyword “HTTP” applies to the use of HTTP and HTTPS.

The host name given in the SPN including the DNS domain must be the real host name of the server. There are two options if a virtual web server is used: If the virtual server is entered as a CNAME record in the DNS, the host name to which the CNAME refers is entered in the SPN. If the virtual web server is entered as an A record in the DNS, the host name entered in the A record is used in the SPN. In both cases the IP address to which the host name entered in the SPN points, must refer back to the host names in the SPN.

Creating the Kerberos-Keytab file in the example under Microsoft Active Directory:

To create the file on a Kerberos server in a Microsoft Active Directory Domain, the additional Windows Support Tools to be installed are required; they are supplied by Microsoft on the installation media of the operating system or can be downloaded from http://microsoft.com.

A normal user account is first created on the Windows Domain Controller. The password must not expire and the user must not be able to change it. The password is irrelevant and is overwritten in the next step. It is sensible to give the “host name”-“service name” as the user name, for example, fs5host-HTTP. To increase security, the “Do not trust user for delegation” option can be activated.

A private key to the service principle name is now created on the Windows Domain Controller with AES256-SHA1 encryption:

ktpass -princ HTTP/fs5host.mydomain.net@MYDOMAIN.NET \
 +rndpass -mapuser fs5host-HTTP \
 -crypto AES256-SHA1 –ptype KRB5_NT_PRINCIPAL \
 -out fs5host-http-aes256.keytab

If the version of the ktpass used does not provide +rndpass, a manually entered random password can also be used here via -pass PASSWORT.

Calling ktpass –h displays the available crypto-algorithms, although it should be noted that these are only used if they are supported by all other domain servers and the respective client.

If problems occur, the list of all Service-Principal names of the user account can be displayed as follows:

setspn -l fs5host-HTTP

If errors occur during the input, a Service-Principal name can be removed using the following call:

setspn -d HTTP/fs5host.mydomain fs5host-HTTP

The keytab file created with kpass is now copied onto the FirstSpirit server or the external application server, to the path given in fs-jaas.conf at keyTab.
Example: /opt/firstspirit5/conf/fs5host-HTTP.keytab.

The file can be checked with the following call under Unix:

kinit -V -k –t fs5host-HTTP.keytab HTTP/fs5host.domain.net@DOMAIN.NET

As a result, "Authenticated to Kerberos v5" should be displayed.

If several crypto-algorithms are used, the individually generated keytab files must first be merged. To do this, start the ktutil service program under Unix:

/usr/sbin/ktutil

and make the following entries in order to save the keytab file under the path given in fs-jaas.conf at keyTab:

rkt krb5-fs5host-HTTP-aes256.keytab
wkt /opt/firstspirit5/conf/fs5host-HTTP.keytab
q

If an external application server is used for the FirstSpirit-Server, the following parameters must be transferred to the application server on starting, for example, for Tomcat via the environmental variable “CATALINA_OPTS”:

-Djava.security.auth.login.config=/opt/firstspirit5/conf/fs-jaas.conf

The use of Kerberos tickets increases the size of the HTTP request header by a few kilobytes, exceeding the default configuration with regard to the usual maximum length of only 4 kilobytes for some web servers. Here is how to configure the different web servers in order to increase the maximum length of the HTTP request:

Tomcat:
In the tomcat/conf/server.xml file of the <Connector protocol="HTTP/1.1" section, add the following parameter:

 maxHttpHeaderSize="65536"

Apache httpd:
In the httpd.conf file, or in the equivalent file on virtual hosts, add the following parameter:

 LimitRequestLine 65536

If the Kerberos server cannot be determined via DNS, i.e. there are no SRV records such as _kerberos._udp.mydomain.net or _kerberos._tcp.mydomain.net available, the server needs the /etc/krb5.conf or c:\windows\krb5.ini file:

[libdefaults]
 default_realm = MYDOMAIN.NET
 
[domain_realm]
 .mydomain.net = MYDOMAIN.NET
 mydomain.net = MYDOMAIN.NET
 
[realms]
 MYDOMAIN.NET = {
 kdc = dc1.mydomain.net
 kdc = dc2.mydomain.net
 kdc = dc3.mydomain.net
 default_domain = mydomain.net
 }

Configuration of the Kerberos-based password-free login is now completed on the server side.

The Kerberos error messages are logged in the /opt/firstspirit5/log/fs-server.log and /opt/firstspirit5/log/fs-wrapper.log files and, if Tomcat is used as the external application server, in tomcat/logs/firstspirit.log.

As soon as the Kerberos-based login has been successfully tested by the workstations/PCs, the debug="true" parameter must be changed to debug="false" in the /opt/firstspirit5/conf/fs-jaas.conf file, in order to prevent an unnecessary number of log messages.

If the login does not work, look first in the log files of the FirstSpirit server (fs-wrapper.log and fs-server.log) and if using an external application server in tts log file (e.g. firstspirit.log and catalina.out). One frequent error is excessively large time differences between the individual computer clocks, which must run synchronously within a range of a few minutes if Kerberos is used.

Configuration of the Clients

Depending on the web browser used, the following configurations are necessary on the Client side (if password-free Kerberos-based login is already used at the workstations/PCs for other web servers within the company network, it is not necessary to make any configuration changes):

Firefox (Windows, Mac OS, GNU/Linux):                         
Enter about:config as the URL in the address line and enter the domain name of the FirstSpirit Server with leading dot in the parameter network.negotiate-auth.trusted-uris. Several domains can be separated by commas. Example: .mydomain.net                           

Safari (Mac OS):                   
Mac OS already offers full Kerberos-integration as a default, provided the user account used is a network-based user account and the workstation/PC is logged into the Active Directory Domain or Kerberos-realm. No configuration changes are necessary. In the case of local user accounts, the first time the FirstSpirit-Start page is accessed the user is asked for their own Kerberos-user name (username@MYDOMAIN.NET) Principal including password.

Konqueror (GNU/Linux):    
No further configuration is necessary if Kerberos has been activated in the operating system of the workstation/PC, i.e. a Kerberos ticket is automatically requested via /etc/pam.d/common-auth on logging in and unblocking of the screen is required.

If problems occur when setting up the Kerberos-based login, you can start Firefox with the debugging log to find out which ticket the browser is sending.

Windows:
Launch the command prompt (cmd.exe) and enter:           

set NSPR_LOG_MODULES=negotiateauth:5         
 cd "\program files\mozilla firefox"  || bzw. Pfad zur Firefox-Installation 
firefox -console

Unix:
Open the terminal window (konsole, xterm, or similar) and enter:

export NSPR_LOG_MODULES=negotiateauth:5
 firefox

Security notice: For security reasons, the KerberosLoginModule should be used in productive systems for successful prevention of replay attacks only in conjunction with HTTPS!