Using ntlmv2auth for Single Sign-On in a Servlet Container

In the following I’m going to show how to use NTLMv2 in order to authenticate with Single Sign-On (SSO) in a web servlet container. The presented solution uses ntlmv2auth, a solution which is based on [Liferay NTLM v2 SSO authentication][ref-1-2]. For the basics and the decision when to use ntlmv2auth with NTLMv2 please refer to my previous posting.

Note that even though NTLM can be secure, if the password has a certain length and the hash is transported over a secured connection, there are flaws in the NTLM mechanism which make it not suitable for high security environments. Best is to ask your security officer, whether NTLMv2 is suitable in your environment or not.

ntlmv2auth will be a generic solution that runs any operating system that is running the Java servlet container but doing a single sign-on against Microsoft domain infrastructure, i.e., Active Directory. Using NTLM should be fine if used inside a corporate network with some fulfilled side-conditions. The most important one is that a long and complex password is enforced for the Active Direcotory User Account, which may be done by using a group policy that can be distributed automatically over the client computers of your network. Ask the person in charge of security whether this is fulfilled or not. For more details on security concerns, please have a look at https://blog.varonis.com/closer-look-pass-hash-part-iii-ntlm-will-get-hacked/ and https://en.wikipedia.org/wiki/NT_LAN_Manager.

In the following the necessary settings for NTLM are discussed, as well as a simple example in a Java web application is given.

Settings in Windows Clients

In order to enable NTLMv2 SSO on Windows client operating systems, you need to do two steps:

You need to configure the browser(s) of your choice to handle the NTLM protocol for a particular service. In the following this is shown for Firefox, Internet Explorer, and Google Chrome.
You need to set the correct Lan Manager authentication level in the local security policy of your computer.

In big corporate networks, you will usually not set manually these settings in the windows client computers, but rather distribute them by group policy to the clients or by automated client computer update procedures. Ask your Windows Domain administrators how this is done.

Nevertheless, in the following is shown how the settings for NTLMv2 is set up manually in the client Windows computers in order to be capable of handling NTLMv2.

Firefox settings

In order to enable the Firefox Browser for being capable of handling NTLMv2, you will need to register the web sites which are allowed to negotiate SSO logins with NTLMv2. In order to do so, enter the URL about:config and press Enter in the address bar of the browser. You will be asked that you are sure to enter the configuration of Firefox. Confirm that you will be careful and select the configuration key:

network.automatic-ntlm-auth.trusted-uris

A window will open as shown in the following screenshot:

Figure 1: Firefox settings Figure 1: Firefox settings

Please enter here the domain name of your server container the Java servet application. If you have multiple sites which need to do a NTLMv2 SSO login on the same Firefox browser, you may enter the domain names separated by commas. If done so, confirm with OK and close the configuration dialog. You’re done.

Internet Explorer Settings

For Internet Explorer you need to define also the sites that are trusted for doing a NTLMv2 SSO. This is done by choosing Extras / Internet options, which brings up the following window:

Figure 2: Internet Explorer Settings Figure 2: Internet Explorer Settings

Choose the Trusted Sites selection and click the Sites button:

Figure 3: Trusted Sites Figure 3: Trusted Sites

Here, you can add the server where the Web-Application is running that is doing a NTLM SSO. Uncheck Require Server verification (https:) for all sites in this zone, if necessary.

Figure 4: Add trusted sites Figure 4: Add trusted sites

After adding the site, you need to tweak the settings for the automatic login. Thus, go back to the Trusted Site Tab and click on Custom level…. The following dialog appears:

Figure 5: Set automatic login in intranet zone Figure 5: Set automatic login in intranet zone

Select User Authentication / Login –> Automatic logon only in Intranet Zone. Click OK.

You may set these settings also for the Local Intranet in the Security Tab. Then you are done.

Chrome Settings

Google Chrome uses the security settings of Internet Explorer. So, if you have mutliple browsers on your Windows clients and you need to configure also Internet Explorer, you are a lucky guy and you don’t need to do anything. If you have not yet done the configuration for Internet Explorer, do the configurations steps for the Internet Exploerer as described above and you are also done for Chrome.

Windows Settings

In Windows (the follwoing Screenshots are taken from Windows 7), you need to set that NTLMv2 is used. This option can be found in the Control Panel / Administrative Tools / Local Security Policies:

Figure 6: Open local security policy Figure 6: Open local security policy

Select Local Policies / Security Options. There, the option Network security LAN Manager authentication Level must be set to Send NTLMv2 responses only. Refuse LM & NTLM, which ensures that only NTLMv2 is valid for LAN Manager authentication and older protocols like NTLMv1 are invalid.

Figure 7: Set NTLMv2 only security policy - step 1 Figure 7: Set NTLMv2 only security policy - step 1

Figure 8: Set NTLMv2 only security policy - step 2 Figure 8: Set NTLMv2 only security policy - step 2

For more information, about the Windows settings, please have a look at https://technet.microsoft.com/en-us/library/jj852207(v=ws.11).aspx.

Note: usually you would do the settings for Internet Explorer and Windows in a corporate network by defining corresponding group policies that are distributed automatically on the client. Check with your domain administrator how this is done. Firefox settings may be distributed using a client-side installer script. See for more details in https://wiki.mozilla.org/Firefox:2.0_Institutional_Deployment.

Servlet Filters

The SSO with ntlmv2auth is done using a servlet filter to provide automatically the authenticated login name to the underlying servlet. The servlet in turn may use the authentication information to do the authorization on the servlet’s functionality. If you like to get to know more about servlet filters, check a tutorial on the net, e.g., http://www.journaldev.com/1933/java-servlet-filter-example-tutorial.

Hands-On ntlmv2auth

In order to start, download the library as well as the ntlmv2 filter jar from https://sourceforge.net/projects/ntlmv2auth/. Use the current version (1.0.5).

Alternatively, if you are using Maven as a build tool for your project, use the following dependencies in your pom.xml for the automatic dependency management of the library and the filter (see also https://mvnrepository.com/artifact/ch.poweredge.ntlmv2-auth/ntlmv2-lib/1.0.5 and https://mvnrepository.com/artifact/ch.poweredge.ntlmv2-auth/ntlmv2-filter):

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11


<dependency>
    <groupId>ch.poweredge.ntlmv2-lib</groupId>
    <artifactId>ntlmv2-filter</artifactId>
    <version>1.0.5</version>
</dependency>

<dependency>
    <groupId>ch.poweredge.ntlmv2-auth</groupId>
    <artifactId>ntlmv2-filter</artifactId>
    <version>1.0.5</version>
</dependency>

Configuring Servlet filter

The servlet filter must be configured as follows, see also the demo app of ntlmv2-auth-root-1.0.5\ntlmv2-demoapp\src\main\webapp\WEB-INF https://mvnrepository.com/artifact/ch.poweredge.ntlmv2-auth/ntlmv2-lib/1.0.5.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52


<?xml version="1.0" encoding="utf-8"?>
<web-app xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns="http://java.sun.com/xml/ns/javaee"
xmlns:web="http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd"
xsi:schemaLocation="http://java.sun.com/xml/ns/javaee
http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd" version="2.5">

  <filter>
        <filter-name>ntlmv2-auth</filter-name>
        <filter-class>org.ntlmv2.filter.NtlmFilter
  </filter-class>

  <init-param>
   <!-- Windows domain name -->
   <param-name>ntlm-domain</param-name>
   <param-value>MYDOMAIN</param-value>
  </init-param>

  <init-param>
   <!-- IP-address of domain controller -->
   <param-name>ntlm-dc</param-name>
   <param-value>domain-controller1.mydomain.com</param-value>
  </init-param>

  <init-param>
   <!-- Simple (non-FQDN) hostname of DC host -->
   <param-name>ntlm-dc-name</param-name>
   <param-value>DOMAIN-CONTROLLER1</param-value>
  </init-param>

  <init-param>
   <!-- Computer account for connection to DC -->
   <param-name>ntlm-account</param-name>
   <param-value>NTLM-SSO$@mydomain.com</param-value>
  </init-param>

  <init-param>
   <!-- Password of computer account -->
   <param-name>ntlm-password</param-name>
   <param-value>***********************</param-value>
  </init-param>
 </filter>

 <filter-mapping>
  <filter-name>ntlmv2-auth</filter-name>
  <url-pattern>/*</url-pattern>
 </filter-mapping>

 <welcome-file-list>
  <welcome-file>index.html</welcome-file>
 </welcome-file-list>
</web-app>

Some Pitfalls

One pitfall might be, that when configuraing the domain name (ntlm-domain), it must be the netbios group name. Any other domain name will not work. The ntlm-account name must be a computer account that has been enabled for being used as NTLM-Service account. It must refer to the computer, on which the service is running on.

Conclusion

In this article, I have shown how to use NTLMv2 and how the settings must be configured in order to run NTLM. However, be sure that you only use NTLMv2 if it fits your security requirements. Please ask your security officer if the use is valid inside your organization.