Tomcat Kerberos

Posted onby admin

I’ve added a Tomcat Negotiate (Kerberos + NTLM) authenticator to Waffle 1.3 for Tomcat 6. Here’s how to use it.

Built-in Tomcat support Kerberos (the basis for integrated Windows authentication) requires careful configuration. If the steps in this guide are followed exactly, then a working configuration will result. There may be some flexibility in some of the steps. A Tomcat Single Sign-On + Form Authentication Mixed Valve, built for the Tomcat Web Container and allowing users to choose whether to do form authentication (a username and password sent to the server from a form) or Windows SSO (NTLM or Kerberos). A Spring-Security Negotiate (NTLM and Kerberos) Filter. Dec 20, 2020 Tomcat starts but doesn’t display webpage; Can’t connect to Tomcat even though it’s running; How to Solve Common Tomcat Problems; Can’t connect to localhost via browser. Can ping localhost; How to open tomcat home page in browser; localhost 8080 not working for tomcat; For all above types of issues, you are at right place.

Download

Download Waffle 1.3. The zip contains Waffle.chm that has the latest version of this tutorial.

Configure Tomcat

Copy Files

I started with a default installation of Tomcat 6. Checked that I could start the server and navigate to http://localhost:8080. Copy the following files into tomcat’s lib directory.

Tomcat Kerberos Vs

Tomcat single sign on
  • jna.jar: Java Native Access
  • platform.jar: JNA platform-specific API
  • waffle-jna.jar: Tomcat Negotiate Authenticator

Authenticator Valve

Add a valve and a realm to the application context in your context.xml (for an application) or in server.xml (for the entire Tomcat installation).

Security Roles

Configure security roles in your application’s web.xml. The Waffle authenticator adds all user’s security groups (including nested and domain groups) as roles during authentication.

Restrict Access

Restrict access to website resources. For example, to restrict the entire website to locally authenticated users add the following in web.xml.

Test

TomcatTomcat Kerberos

Restart Tomcat and navigate to http://localhost:8080.

You should be prompted for a logon with a popup. This is because by default localhost is not in the _Intranet Zone _and the server returned a 401 Unauthorized. Internet servers with a fully qualified named are detected automatically.

Internet Explorer

Ensure that Integrated Windows Authentication is enabled.

  1. Choose the_ Tools, Internet Options_ menu.
  2. Click the Advanced tab.
  3. Scroll down to Security
  4. Check Enable Integrated Windows Authentication.
  5. Restart the browser.

The target website must be in the Intranet Zone.

  1. Navigate to the website.
  2. Choose the Tools, Internet Options menu.
  3. Click the Local Intranet icon.
  4. Click the Sites button.
  5. Check Autmatically detect intranet network.
  6. For localhost, click Advanced.
  7. Add http://localhost to the list.

Firefox

  1. Type about:config in the address bar and hit enter.
  2. Type network.negotiate-auth.trusted-uris in the Filter box.
  3. Put your server name as the value. If you have more than one server, you can enter them all as a comma separated list.
  4. Close the tab.

Navigate to http://localhost:8080 after adding it to the Intranet Zone.

You should no longer be prompted and automatically authenticated.

Logs

In the logs you will see the following output for a successful logon.

Tomcat kerberos vs

My laptop is not a member of an Active Directory domain, but you would see domain groups, including nested ones here. There’s nothing special to do for Active Directory. The authenticator also automatically handles all aspects of the Negotiate protocol, chooses Kerberos vs. NTLM and supports NTLM POST. It basically has the same effect in Tomcat as choosing Integrated Windows authentication options in IIS.

Related Projects

  • Tomcat SPNEGO by Dominique Guerrin: this is a very good prototype of a filter. It uses JNI and not JNA, doesn’t support NTLM POST and the code is pretty thick.
  • SPNEGO Sourceforge: it’s a nightmare to configure, doesn’t work without an Active Directory domain and requires an SPN
  • JCIFS NTLM: no longer supported and they recommend using Jespa
  • Jespa: a commercial implementation that claims to do the same thing as Waffle, but uses the Netlogon service instead of the native Windows API
Please enable JavaScript to view the comments powered by Disqus.comments powered by Disqus

Kerberos (the basis for integrated Windows authentication) requires careful configuration. If the steps in this guide are followed exactly, then a working configuration will result. There may be some flexibility in some of the steps below but further testing is required to explore this. From the testing to date it is known that:

  • The host name of the Tomcat server must match the host name in the SPN exactly else authentication will fail. A checksum error may be reported in the debug logs in this case.
  • The client must be of the view that the server is part of the local trusted intranet.

Tomcat Kerberos Debug

The areas where further testing is required include:

  • Does the domain name have to be in upper case?
  • Does the SPN have to start with HTTP/...?
  • Can a port number be appended to the end of the host in the SPN?
  • Can the domain be left off the user in the ktpass command?
  • What are the limitations on the account that Tomcat can run as? SPN associated account works, domain admin works, local admin doesn't work
Basic

There are four components to the configuration of the built-in Tomcat support for Windows authentication. The domain controller, the server hosting Tomcat, the web application wishing to use Windows authentication and the client machine. The following sections describe the configuration required for each component.

The names of the three machines used in the configuration examples below are win-dc01.dev.local (the domain controller), win-tc01.dev.local (the Tomcat instance) and win-pc01.dev.local (client). All are members of the DEV.LOCAL domain.

Note: In order to use the passwords in the steps below, the domain password policy had to be relaxed. This is not recommended for production environments.

These steps assume that the server has already been configured to act as a domain controller. Configuration of a Windows server as a domain controller is outside the scope of this how-to. The steps to configure the domain controller to enable Tomcat to support Windows authentication are as follows:

  • Create a domain user that will be mapped to the service name used by the Tomcat server. In this how-to, this user is called tc01 and has a password of tc01pass.
  • Map the service principal name (SPN) to the user account. SPNs take the form <service class>/<host>:<port>/<service name>. The SPN used in this how-to is HTTP/win-tc01.dev.local. To map the user to the SPN, run the following:
  • 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 (all on a single line):
  • Create a domain user to be used on the client. In this how-to the domain user is test with a password of testpass.

The above steps have been tested on a domain controller running Windows Server 2008 R2 64-bit Standard using the Windows Server 2003 functional level for both the forest and the domain.

These steps assume that Tomcat and a Java 6 JDK/JRE have already been installed and configured and that Tomcat is running as the [email protected] user. The steps to configure the Tomcat instance for Windows authentication are as follows:

  • Copy the tomcat.keytab file created on the domain controller to $CATALINA_BASE/conf/tomcat.keytab.
  • Create the kerberos configuration file $CATALINA_BASE/conf/krb5.ini. The file used in this how-to contained: The location of this file can be changed by setting the java.security.krb5.conf systm property.
  • Create the JAAS login configuration file $CATALINA_BASE/conf/jaas.conf. The file used in this how-to contained: The location of this file can be changed by setting the java.security.auth.login.config system property. The LoginModule used is a JVM specific one so ensure that the LoginModule specified matches the JVM being used. The name of the login configuration must match the value used by the authentication valve.
  • The system property javax.security.auth.useSubjectCredsOnly is automatically set to the required value of false if a web application is configured to use the SPNEGO authentication method.

The SPNEGO authenticator will work with any Realm but if used with the JNDI Realm, by default the JNDI Realm will use the user's delegated credentials to connect to the Active Directory.

The above steps have been tested on a Tomcat server running Windows Server 2008 R2 64-bit Standard with an Oracle 1.6.0_24 64-bit JDK.

This was tested with:

  • Java 1.7.0, update 45, 64-bit
  • Ubuntu Server 12.04.3 LTS 64-bit
  • Tomcat 8.0.x (r1546570)

It should work with any Tomcat 7 release from 7.0.12 onwards although it is recommended that the latest stable release is used.

The configuration is the same as for Windows but with the following changes:

  • The Linux server does not have to be part of the Windows domain.
  • The path to the keytab file in krb5.ini and jass.conf should be updated to reflect the path to the keytab file on the Linux server using Linux style file paths (e.g. /usr/local/tomcat/...).

The web application needs to be configured to the use Tomcat specific authentication method of SPNEGO (rather than BASIC etc.) in web.xml. As with the other authenticators, behaviour can be customised by explicitly configuring the authentication valve and setting attributes on the Valve.

Apache User Authentication

Client

The client must be configured to use Kerberos authentication. For Internet Explorer this means making 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.

Tomcat Sso

References

Correctly configuring Kerberos authentication can be tricky. The following references may prove helpful. Advice is also always available from the Tomcat users mailing list.