Apache Tomcat 7 (7.0.27) - Windows Authentication How-To

# Apache Tomcat 7

Version 7.0.27, Mar 31 2012

Links

- Docs Home
- FAQ

User Guide

- 1) Introduction
- 2) Setup
- 3) First webapp
- 4) Deployer
- 5) Manager
- 6) Realms and AAA
- 7) Security Manager
- 8) JNDI Resources
- 9) JDBC DataSources
- 10) Classloading
- 11) JSPs
- 12) SSL
- 13) SSI
- 14) CGI
- 15) Proxy Support
- 16) MBean Descriptor
- 17) Default Servlet
- 18) Clustering
- 19) Load Balancer
- 20) Connectors
- 21) Monitoring and Management
- 22) Logging
- 23) APR/Native
- 24) Virtual Hosting
- 25) Advanced IO
- 26) Additional Components
- 27) Mavenized
- 28) Security Considerations
- 29) Windows Service
- 30) Windows Authentication
- 31) Tomcat's JDBC Pool
- 32) WebSocket

Reference

- Release Notes
- Configuration
- Tomcat Javadocs
- Servlet Javadocs
- JSP 2.2 Javadocs
- EL 2.2 Javadocs
- JK 1.2 Documentation

Apache Tomcat Development

- Building
- Changelog
- Status
- Developers
- Architecture
- Functional Specs.

# Windows Authentication How-To

Table of Contents

> - Overview
> - Built-in Tomcat support
>   1. Domain Controller
>   2. Tomcat instance
>   3. Web application
>   4. Client
>   5. References
> - Third party libraries
>   1. Waffle
>   2. Spring Security - Kerberos Extension
>   3. SPNEGO project at SourceForge
> - Reverse proxies
>   1. Microsoft IIS
>   2. Apache httpd

Overview

> Integrated Windows authentication is most frequently used within intranet environments since it requires that the server performing 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.

> There are several options for implementing integrated Windows authentication with Apache Tomcat. They are:

> - Built-in Tomcat support.
> - Use a third party library such as Waffle.
> - Use a reverse proxy that supports Windows authentication to perform the authentication step such as IIS or httpd.
> The configuration of each of these options is discussed in the following sections.

Built-in Tomcat support

> This is a work in progress. There are a number of outstanding questions that require further testing. These 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

> 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.

> Domain Controller

> > 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:

> >       setspn -A HTTP/win-tc01.dev.local tc01

> > - 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):

> >       ktpass /out c:\tomcat.keytab /mapuser tc01@DEV.LOCAL
> >                 /princ HTTP/win-tc01.dev.local@DEV.LOCAL
> >                 /pass tc01pass /kvno 0

> > - 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.

> Tomcat instance

> > These steps assume that Tomcat and a Java 6 JDK/JRE have already been installed and configured and that Tomcat is running as the tc01@DEV.LOCAL 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:

> >       [libdefaults]
> >       default_realm = DEV.LOCAL
> >       default_keytab_name = FILE:c:\apache-tomcat-7.0.x\conf\tomcat.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]
> >       DEV.LOCAL = {
> >               kdc = win-dc01.dev.local:88
> >       }

> >       [domain_realm]
> >       dev.local= DEV.LOCAL
> >       .dev.local= DEV.LOCAL

> >   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:

> >       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-7.0.x/conf/tomcat.keytab"
> >           storeKey=true;
> >       };

> >       com.sun.security.jgss.krb5.accept {
> >           com.sun.security.auth.module.Krb5LoginModule required
> >           doNotPrompt=true
> >           principal="HTTP/win-tc01.dev.local@DEV.LOCAL"
> >           useKeyTab=true
> >           keyTab="c:/apache-tomcat-7.0.x/conf/tomcat.keytab"
> >           storeKey=true;
> >       };

> >   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.

> Web application

> > 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.

> 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.

> 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.

> > 1. IIS and Kerberos
> > 2. SPNEGO project at SourceForge
> > 3. Oracle JGSS tutorial
> > 4. Geronimo configuration for Windows authentication
> > 5. Encryption Selection in Kerberos Exchanges
> > 6. Supported Kerberos Cipher Suites

Third party libraries

> Waffle

> > Full details of this solution can be found through the Waffle site. The key features are:

> > - Drop-in solution
> > - Simple configuration (no JAAS or Kerberos keytab configuration required)
> > - Uses a native library

> Spring Security - Kerberos Extension

> > Full details of this solution can be found through the Kerberos extension site. The key features are:

> > - Extension to Spring Security
> > - Requires a Kerberos keytab file to be generated
> > - Pure Java solution

> SPNEGO project at SourceForge

> > Full details of this solution can be found through the project site. The key features are:

> > - Uses Kerberos
> > - Pure Java solution

Reverse proxies

> Microsoft IIS

> > There are three steps to configuring IIS to provide Windows authentication. They are:

> > 1. Configure IIS as a reverse proxy for Tomcat (see the IIS Web Server How-To).
> > 2. Configure IIS to use Windows authentication
> > 3. Configure Tomcat to use the authentication user information from IIS by setting the tomcatAuthentication attribute on the AJP connector to `false`.

> Apache httpd

> > Apache httpd does not support Windows authentication out of the box but there are a number of third-party modules that can be used. These include:

> > 1. mod_auth_sspi for use on Windows platforms.
> > 2. mod_auth_ntlm_winbind for non-Windows platforms. Known to work with httpd 2.0.x on 32-bit platforms. Some users have reported stability issues with both httpd 2.2.x builds and 64-bit Linux builds.

> > There are three steps to configuring httpd to provide Windows authentication. They are:

> > 1. Configure httpd as a reverse proxy for Tomcat (see the Apache httpd Web Server How-To).
> > 2. Configure httpd to use Windows authentication
> > 3. Configure Tomcat to use the authentication user information from httpd by setting the tomcatAuthentication attribute on the AJP connector to `false`.

Copyright © 1999-2012, Apache Software Foundation