Kerberos is a network authentication protocol. It is designed to provide strong authentication for client/server applications by using secret-key cryptography. A free implementation of this protocol is available from the Massachusetts Institute of Technology. Kerberos is available in many commercial products as well.
1. The tools
- Java JDK
- Apache Tomcat
2. Introduction
Kerberos authentication is used to make Tomcat Web applications use the domain windows controller credentials to authenticate the Tomcat hosted web applications. Integrated Windows authentication is most frequently used within intranet environments since it requires that both the server which performs the authentication and the user being authenticated are part of the same domain. For the user to be authenticated automatically, the client machine used by the user must also be part of the domain.
3. Prerequisites
- JDK installed
4. Download Tomcat
Go to the page https://tomcat.apache.org/download-80.cgi and download the tomcat server as a zip compressed file for windows.
5. Tomcat Installation
5.1 Uncompress Apache Tomcat
Choose an installation directory and uncompress the Tomcat server in its own directory.
5.2 Install the Tomcat service
Open the Window terminal and go to the Tomcat Installation bin directory.
Tomcat installation directory
C:\Java\Apache Tomcat 8.0.15\bin>
Install the service with the following command:
Install Tomcat service
C:\Java\Apache Tomcat 8.0.15\bin>service install
You should get an output similar to this:
install Tomcat output
Installing the service 'Tomcat8' ... Using CATALINA_HOME: "C:\Java\Apache Tomcat 8.0.15" Using CATALINA_BASE: "C:\Java\Apache Tomcat 8.0.15" Using JAVA_HOME: "C:\Java\jdk1.8.0_40" Using JRE_HOME: "C:\Java\jre1.8.0_40" Using JVM: "C:\Java\jre1.8.0_40\bin\client\jvm.dll" The service 'Tomcat8' has been installed.
5.3 Start the Tomcat service
Start the service with the following command:
Start tomcat output
C:\Java\Apache Tomcat 8.0.15\bin>sc start Tomcat8
You should get an output similar to the following:
console
SERVICE_NAME: Tomcat8
TYPE : 10 WIN32_OWN_PROCESS
STATUS : 2 START_PENDING
(NOT_STOPPABLE, NOT_PAUSABLE, IGNORES_SHUTDOWN)
WIN32_OUTPUT_CODE : 0 (0x0)
SERVICE_OUTPUT_CODE: 0 (0x0)
CHECK-POINT : 0x0
START-INDICATOR : 0x7d0
PID : 5552
MARKS :
5.4 Check that tomcat is running
Open the browser in the URL: http://localhost:8080 and you the Tomcat Welcome screen should appear.
6. Checklist before enable Kerberos Authentication
- The host name used to access the Tomcat server must match the host name in the Service Principal Name.
- The client must be part of the local trusted intranet.
- The Service Principal Name must be HTTP/
- The port number must not be included in the Service Principal Name.
- No more than one Service Principal Name may be mapped to a domain user.
- Tomcat must run as the domain account with which the Service Principal Name has been associated.
- The domain must be specified when using the ktpass command.
7 Components
The name of the Windows domain is:
MYDOMAIN.LOCAL.
There are four components to the configuration of the built-in Tomcat support for Windows authentication.
7.1 The domain controller
In our case is going to be:
mydomain-controller.mydomain.local
7.2 The server hosting Tomcat
In our case is going to be:
mytomcat.mydomain.local
7.3 The web application wishing to use Windows authentication
This application is hosted in tomcat so it uses the same domain name as the Tomcat instance.
7.4 The client machine.
In our case is going to be:
myclient.mydomain.local
As you can see the client is part of our window domain.
8. Configuring the domain controller
Create a domain user that will be mapped to the service name used by the Tomcat server. We are going to use the user MYTOMCATUSER and the password MYTOMCATPASSWORD
Map the service principal name to the user account. Service Principal Name take the form <service class>/<host>:<port>/<service name>.
The SPN used in this how-to is HTTP/mytomcat.mydomain.local. To map the user to the Service Principal Name, run the following:
setspn
setspn -A HTTP/mytomcat.mydomain.local MYTOMCATUSER
Generate the keytab file that the Tomcat server will use to authenticate itself to the domain controller. This file contains the Tomcat private key for the service provider account and should be protected accordingly. To generate the file, run the following command:
ktpass
ktpass /out c:\mytomcat.keytab /mapuser MYTOMCATUSER@MYDOMAIN.LOCAL
/princ HTTP/mytomcat.mydomain.local@MYDOMAIN.LOCAL
/pass MYTOMCATPASSWORD /kvno 0
Create a domain user to be used on the client. We are going to use the user myclientuser and the password myclientpassword.
9. Configuring the Tomcat instance
Install Tomcat following the steps explained before. Tomcat need to be run with the MYTOMCATUSER@MYDOMAIN.LOCAL user.
The steps to configure the Tomcat instance for Windows authentication are as follows:
$CATALINA_BASE is the tomcat install folder.
Copy the mytomcat.keytab file created on the domain controller to $CATALINA_BASE/conf/mytomcat.keytab. Create the kerberos configuration file $CATALINA_BASE/conf/krb5.ini.
krb5.ini
[libdefaults]
default_realm = MYDOMAIN.LOCAL
default_keytab_name = FILE:c:\apache-tomcat\conf\mytomcat.keytab
default_tkt_enctypes = rc4-hmac,aes256-cts-hmac-sha1-96,aes128-cts-hmac-sha1-96
default_tgs_enctypes = rc4-hmac,aes256-cts-hmac-sha1-96,aes128-cts-hmac-sha1-96
forwardable=true
[realms]
MYDOMAIN.LOCAL = {
kdc = mydomain-controller.mydomain.local:88
}
[domain_realm]
maydomain.local= MYDOMAIN.LOCAL
.mydomain.local= MYDOMAIN.LOCAL
Create the JAAS login configuration file $CATALINA_BASE/conf/jaas.conf.
jaas.conf
com.sun.security.jgss.krb5.initiate {
com.sun.security.auth.module.Krb5LoginModule required
doNotPrompt=true
principal="HTTP/win-tc01.dev.local@DEV.LOCAL"
useKeyTab=true
keyTab="c:/apache-tomcat/conf/tomcat.keytab"
storeKey=true;
};
com.sun.security.jgss.krb5.accept {
com.sun.security.auth.module.Krb5LoginModule required
doNotPrompt=true
principal="HTTP/mytomcat.mydomain.local@MYDOMAIN.LOCAL"
useKeyTab=true
keyTab="c:/apache-tomcat/conf/mytomcat.keytab"
storeKey=true;
};
10. Configuring the Web application
The web application needs to be configured to the Tomcat specific authentication method of SPNEGO in web.xml.
Find the filter section in the file and add your servlet’s initial parameter configuration.
filter
<filter>
<filter-name>SpnegoHttpFilter</filter-name>
<filter-class>net.sourceforge.spnego.SpnegoHttpFilter</filter-class>
<init-param>
<param-name>spnego.allow.basic</param-name>
<param-value>true</param-value>
</init-param>
<init-param>
<param-name>spnego.allow.localhost</param-name>
<param-value>true</param-value>
</init-param>
<init-param>
<param-name>spnego.allow.unsecure.basic</param-name>
<param-value>true</param-value>
</init-param>
<init-param>
<param-name>spnego.login.client.module</param-name>
<param-value>spnego-client</param-value>
</init-param>
<init-param>
<param-name>spnego.krb5.conf</param-name>
<param-value>krb5.conf</param-value>
</init-param>
<init-param>
<param-name>spnego.login.conf</param-name>
<param-value>login.conf</param-value>
</init-param>
<init-param>
<param-name>spnego.preauth.username</param-name>
<param-value>Zeus</param-value>
</init-param>
<init-param>
<param-name>spnego.preauth.password</param-name>
<param-value>Z3usP@55</param-value>
</init-param>
<init-param>
<param-name>spnego.login.server.module</param-name>
<param-value>spnego-server</param-value>
</init-param>
<init-param>
<param-name>spnego.prompt.ntlm</param-name>
<param-value>true</param-value>
</init-param>
<init-param>
<param-name>spnego.logger.level</param-name>
<param-value>1</param-value>
</init-param>
</filter>
<filter-mapping>
<filter-name>SpnegoHttpFilter</filter-name>
<url-pattern>*.jsp</url-pattern>
</filter-mapping>
11. Configuring the client
The client must be configured to use Kerberos authentication. For Internet Explorer this means that you have to make sure that the Tomcat instance is in the “Local intranet” security domain and that it is configured (Tools > Internet Options > Advanced) with integrated Windows authentication enabled. Note that this will not work if you use the same machine for the client and the Tomcat instance as Internet Explorer will use the unsupported NTLM protocol.
12. Conclusion
Authentication is the process of identifying yourself to the network and is fundamental to the security of computer systems. Without knowing who is requesting an operation it is hard to decide whether the operation should be allowed. Weak authentication systems are authentication by assertion and assume that services and machines cannot be compromised or spoofed and that network traffic cannot be monitored. Strong authentication systems that do not disclose secrets on the network and use encryption are becoming increasingly popular and important.
Kerberos has strong mutual authentication. Secrets are not transmitted across the network. Critical authentication data is encrypted. The client (normally a user) is authenticated to the server and the server is authenticated to the client. The client identity is used to authorize services on the server. The server identity prevents the spoofing and hijacking of services.
Single sign-on. A user convenience meaning a single identity and password can be used for many services with only one login sequence.
