Integrated Windows Authentication with WSO2 Identity Server

  • By Pulasthi Mahawithana
  • 12 Apr, 2013

Applies to

WSO2 Identity Server 4.0.0 or higher

Table of Contents

  • Introduction to Integrated Windows Authentication (IWA)
  • How IWA Works
  • Pros and Cons of IWA
  • Implementing IWA in a Java Web App
  • IWA Authenticator of WSO2 Identity Server

Introduction to Integrated Windows Authentication

Integrated Windows Authentication (IWA) is an authentication mechanism introduced by Microsoft to authenticate users in Microsoft Windows NT based operating systems. IWA authentication provides an easier way for users to log in to web applications that use Windows Active Directory as an user store. This is a popular choice of authentication among Windows server users and administrators.

Most often, we log in to web applications by providing a user name and password in a HTML page. This type of authentication systems are called form based authentication systems. However there are several other ways where the need for user name and password is eliminated when the user is already authenticated. Integrated Windows Authentication is one such method. It is as a browser based authentication mechanism because the authentication is handled by the browser. The web browser gets the credentials of the windows logged in user and uses those credentials to authenticate the user with the help of the server and Active Directory. The only requirement for the user is to simply enter the Protected web application's URL in the browser, and the browser and server takes care of the rest of the authentication and automatically logs the user in (provided that the user is in the same domain and is a valid and authorized user to log in). If the authentication fails, the user is prompted to enter valid credentials to log in to the system.

Authentication Procedure

Let's get into the some detailed on how the IWA works,

  1. The User (who is already authenticated to the Windows domain when they log in to Windows) sends an usual request to a protected page of a web application (protected by IWA).
  2. The server rejects the request and sends a response saying the user needs to be authenticated using NTLM.
  3. The client browser get the Windows logged in user's credentials, takes the hash of it and sends to the server
  4. With the hash received, the server looks up the user store and identifies the user and creates an unique and encrypted challenge to send back to the client browser. That challenge can be only decrypted using the user's password which the browser already has with itself.
  5. The client browser decrypts the challenge with the user's credentials which the browser already knows, and sends the response back to the server.
  6. The server checks whether the response for the challenge is correct and serves the user requested resource if the answer is correct. If the answer is wrong, the server denies the access to the requested resources and sends the unauthorized message.

Pros and Cons of IWA

The main advantage of this authentication mechanism is that the user doesn't need to explicitly give his or her credentials. Once users are logged into the Windows domain they are automatically authenticated for the IWA enabled web apps if the user is a valid user.

In IWA authentication, the user name and password are not sent over the network. Instead it uses a hash function and a challenge response scheme to authenticate. That makes the authentication more secure from man-in-the-middle type of attacks.

The disadvantage is that since the authentication is done using the Windows Active Directory it needs both the clients and the server to use Microsoft Windows NT based operating systems. Also the clients need to be connected to the domain hosted by the server. This can be used only within an intranet. Also IWA may need some configuration on certain browsers like Mozilla Firefox.

Implementing IWA for a Java Web Application

IWA was initially developed by Microsoft as an authentication mechanism for their .NET based IIS servers. However, neither Java nor the server applications that host Java web applications (like Tomcat) have native support for IWA. There are several third party libraries which provide the ability of enabling the IWA for the Java web applications. Here are some of those libraries

  • JCIFS – JCIFS is an open source library that had been commonly used few years ago for IWA authentication of Java web applications. However this library is no longer maintained and it is not recommended to use because of security flaws.
  • JESPA – JESPA is a commercial library that can be used to enable IWA in Java web applications
  • Tomcat IWA – This is tomcat's implementation of IWA. However this is not fully completed yet.
  • SPENGO – SPENGO is an open source library. It uses Java Authentication and Authorization Service (JAAS) for the authentication
  • WAFFLE – WAFFLE is also an open source library. It can be configured easily to use with the Java web applications.

IWA Authenticator in WSO2 Identity Server

WSO2 Identity Server has the support for the IWA authentication from version 4.0.0 onward. IWA authenticator of WSO2 Identity server consists of two components.

  • IWA Front-end Component – At the front end of the Identity Server, this component is responsible for accepting the requests that are of type "Negotiate" that are authenticated by the web browser, extract the user name of the user from the request and call to Back-end component to authenticate the user.
  • IWA Back-end Component – At the back end of the Identity server, this component is responsible for accepting the authenticated user name from the Front-end component and calling the user store manager to check whether the requested user is a valid user in the Active Directory.

Following is the sequence diagram to demonstrate how the authentication is done in IWA authenticator, and what each component does in the authentication process.

Step 1 – The authentication core first checks whether the authenticator is activated and if it is activated, it sends the request to the IWA Front-end Authenticator and asks whether it can handle the request given

Step 2 – The Front End (FE) component checks whether the request provided is a valid Negotiate request by checking its headers. If the request contains those headers the FE component replies that it can handle the request. If the request doesn't contain the required headers the FE component replies that it can't handle the request so that the authentication core can either call the next activated authenticator or reply the client that the request cannot be authenticated.

Step 3 – If the authenticator replied that it can handle the request the authentication core sends the request again to the FE component to process.

Step 4 – The FE component extracts the remote user name that is already authenticated by the web browser. Then it signs those information and sends to the Back-end component to complete the authentication

Step 5 – The Back-end (BE) component receives the authentication request details. It first checks and verifies whether the signature is valid one or not. If the signature validation fails it throws an exception in order to prevent unauthorized access (any external service client other than the FE component should not be able to send authentication requests to the BE component). If the signature validation succeeds, it communicates with the user store and verifies that the user is a valid user.

Step 6 – The BE returns the authentication results to the FE component. This message is also sent as a signed message.

Step 7- The FE component checks the signature of the authentication response from the BE component. If the signature validation succeeds and the request has been validated by the BE component, it replies the authentication core that the user is an authenticated user, and completes the authentication process.

Enabling IWA in WSO2 Identity Server

WSO2 identity server is capable of running in multiple platforms. But the IWA authenticator is designed only for the Windows server. And enabling IWA authenticator may sometime conflict with other authenticators. Because of these reasons IWA authenticator is not enabled in WSO2 Identity Server by default. However the authenticator can be enabled in WSO2 Identity Server with some configurations.


  • Web Server
    • Windows Server 2003 or later
    • An Active Directory configured in the Windows server
    • WSO2 Identity Server 4.0.0
  • Client
    • Microsoft Windows Operating System (XP, Vista, 7)
    • Internet Explorer 7+ , Mozilla Firefox, Google Chrome (or any other web browser that support IWA)

Following are the steps to configure IWA in WSO2 Identity Server.

  1. Download WSO2 Identity Server 4.0.0
  2. Extract the zip file in the file system
  3. Open the <wso2is_home>/repository/conf/user-mgt.xml and configure it to use your Active Directory as the user store (WSO2 is configured to use a built-in LDAP server by default). You may start the WSO2 Identity Server with <wso2is_home>/bin/wso2server.bat and check whether the user store is configured properly before the IWA is activated
  4. You may start from here if you have WSO2 Identity Server already configured to use Active Directory

  5. Stop the WSO2 Identity Server if the server is already running
  6. Open <wso2is_home>/repository/conf/security/authenticators.xml file and add the following lines inside somewhere in <Authenticators> tag.
  7. <Authenticator name="IWAUIAuthenticator" disabled="false">

    This will tell WSO2 Identity Server that we are going to enable the "IWAUIAuthenticator" with a priority level of 5.

  8. Open the <wso2is_home>/repository/conf/tomcat/web.xml file and add the following lines just before "</web-app>"
  9. <security-constraint>
     <display-name>Security Constraint for IWA</display-name>
      <web-resource-name>Protected Area</web-resource-name>

    This will prevent unauthorized access to the WSO2 Identity Server and will redirect the requests to the authenticator to authenticate them.

  10. Open the <wso2is_home>/repository/conf/tomcat/carbon/META-INF/context.xml and add the following lines just before the "</Context>"
  11. <Valve className="waffle.apache.NegotiateAuthenticator" principalFormat="fqn" roleFormat="both" />
    <Realm className="waffle.apache.WindowsRealm" />

    This will use the Valve and Realm from Waffle library which is used for Negotiate authentication.

  12. Start the WSO2 Identity Server

Now the server is configured to use the IWA authenticator.

Access the Identity server from a client machine (The user should be logged in to the domain of the server) by entering the WSO2 Identity Server's URL (e.g. from your client browser. You will notice that you are logged into the WSO2 Identity Server without prompting for the password.

A part of the server log when user is logged with IWA

Sometimes you may not be logged in automatically and you may be prompted to enter the username and password. The reason for that could be one of the following.

  • The browser is either unable to do the IWA authentication or it is not configured to use the IWA authentication properly. The web server should be added to the trusted websites of the browser.
    • For Internet explorer, go to “Tools → Internet Options” and in the “security” tab select local intranet.

      And click the sites button. Then add the URL of WSO2 Identity Server there.

    • For Firefox, type “about:config” in the address bar, ignore the warning and continue, this will display the advanced settings of Firefox. In the search bar, search for the key "network.negotiate-auth.trusted-uris" and add the WSO2 Identity Server URL there.
  • The user may be trying to access the WSO2 Identity Server outside from the domain of the user
  • The user may not have the sufficient permission within WSO2 Identity Server to log in to the system



Integrated Windows Authentication has been an easier and secure way of authentication for web applications in Microsoft Windows servers. It can be enabled in WSO2 Identity Server deployed in a Windows server to provide users of an intranet in a easy and secure authentication mechanism.

About Author

  • Pulasthi Mahawithana
  • Software Engineer
  • WSO2 Inc.