Windows Authentication How-To

Tomcat Home
The Apache Software Foundation
Apache Tomcat 10
Version 10.0.0-M4, Apr 3 2020
Links

Docs Home
FAQ
User Comments

User Guide

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

Reference

Release Notes
Configuration
Tomcat Javadocs
Servlet 5.0 Javadocs
JSP 3.0 Javadocs
EL 4.0 Javadocs
WebSocket 2.0 Javadocs
JASPIC 2.0 Javadocs
Annotations 2.0 Javadocs
JK 1.2 Documentation

Apache Tomcat Development

Building
Changelog
Status
Developers
Architecture
Functional Specs.
Tribes

Windows Authentication How-To
Table of Contents

Overview
Built-in Tomcat support
    Domain Controller
    Tomcat instance (Windows server)
    Tomcat instance (Linux server)
    Web application
    Client
    References
Third party libraries
    Waffle
    Spring Security - Kerberos Extension
    Jespa
    SPNEGO AD project at SourceForge
Reverse proxies
    Microsoft IIS
    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

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. It is important that the steps below are followed exactly. There is very little scope for flexibility in the configuration. From the testing to date it is known that:

The host name used to access 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.
The SPN must be HTTP/<hostname> and it must be exactly the same in all the places it is used.
The port number must not be included in the SPN.
No more than one SPN may be mapped to a domain user.
Tomcat must run as the domain account with which the SPN has been associated or as domain admin. It is NOT recommended to run Tomcat under a domain admin user.
Convention is that the domain name (dev.local) is always used in lower case. The domain name is typically not case sensitive.
Convention is that the Kerberos realm name (DEV.LOCAL) is always used in upper case. The realm name is case sensitive.
The domain must be specified when using the ktpass command.

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 2019 Standard using the Windows Server 2016 functional level for both the forest and the domain.
Tomcat instance (Windows server)

These steps assume that Tomcat and a Java 8 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-10.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 system 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-10.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-10.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 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. If only the authenticated user name is required then the AuthenticatedUserRealm may be used that will simply return a Principal based on the authenticated user name that does not have any roles.

The above steps have been tested on a Tomcat server running Windows Server 2019 Standard with AdoptOpenJDK 8u232-b09 (64-bit).
Tomcat instance (Linux server)

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 8 release 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 jaas.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/...).

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.

IIS and Kerberos
SPNEGO project at SourceForge
Oracle Java GSS-API tutorial (Java 7)
Oracle Java GSS-API tutorial - Troubleshooting (Java 7)
Geronimo configuration for Windows authentication
Encryption Selection in Kerberos Exchanges
Supported Kerberos Cipher Suites

Third party libraries
Waffle

Full details of this solution can be found through the Waffle web 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 web site. The key features are:

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

Jespa

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

Pure Java solution
Advanced Active Directory integration

SPNEGO AD project at SourceForge

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

Pure Java solution
SPNEGO/Kerberos Authenticator
Active Directory Realm

Reverse proxies
Microsoft IIS

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

Configure IIS as a reverse proxy for Tomcat (see the IIS Web Server How-To).
Configure IIS to use Windows authentication
Configure Tomcat to use the authentication user information from IIS by setting the tomcatAuthentication attribute on the AJP connector to false. Alternatively, set the tomcatAuthorization attribute to true to allow IIS to authenticate, while Tomcat performs the authorization.

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:

mod_auth_sspi for use on Windows platforms.
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:

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

Copyright © 1999-2020, The Apache Software Foundation