Enabling IWA in WSO2 Identity Server

To work with Integrated Windows Authentication in WSO2 Identity Server, you need to know the following:

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.

The following is the sequence diagram to demonstrate how the authentication is done in the 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.

Prerequisites:

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.

To configure IWA in WSO2 Identity Server:

Download the WSO2 Identity Server from the product page.
Extract the ZIP file in the file system.
Open the <wso2is_home>/repository/conf/user-mgt.xml file and configure it to use your Active Directory as the user store (WSO2 is configured to use a built-in LDAP server by default).
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.
Start from this step if you have WSO2 Identity Server already configured to use Active Directory.
Stop the WSO2 Identity Server if the server is already running.
Open the <wso2is_home>/repository/conf/security/authenticators.xml file and add the following lines inside the <Authenticators> tag.
```
<Authenticator name="IWAUIAuthenticator" disabled="false">
    <Priority>5</Priority>
</Authenticator>
```
This indicates to the WSO2 Identity Server that "IWAUIAuthenticator" is to be enabled with a priority level of 5.

Open the <wso2is_home>/repository/conf/tomcat/web.xml file and add the following lines just before "</web-app>".

<security-constraint>
  <display-name>Security Constraint for IWA</display-name>
  <web-resource-collection>
    <web-resource-name>Protected Area</web-resource-name>
    <url-pattern>/</url-pattern>
    <http-method>DELETE</http-method>
    <http-method>GET</http-method>
    <http-method>POST</http-method>
    <http-method>PUT</http-method>
  </web-resource-collection>
  <auth-constraint>
    <role-name>Everyone</role-name>
  </auth-constraint>
</security-constraint>

This prevents unauthorized access to the WSO2 Identity Server and redirects the requests to the authenticator to authenticate them.

Open the <wso2is_home>/repository/conf/tomcat/carbon/META-INF/context.xml and add the following lines just before "</Context>".
```
<Valve className="waffle.apache.NegotiateAuthenticator" principalFormat="fqn" roleFormat="both"/>
<Realm className="waffle.apache.WindowsRealm"/>
```
This uses Valve and Realm from Waffle library which is used to negotiate authentication.
Start the WSO2 Identity Server. Now the server is configured to use the IWA authenticator.

Usage:

Access the WSO2 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., https://192.168.4.108:9443/carbon) from your client browser. You are logged into the WSO2 Identity Server without having to enter your password. The following is a part of the server log when the 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.
- 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 displays 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 attempting to access the WSO2 Identity Server from outside the domain of the user.
The user may not have the sufficient permission within WSO2 Identity Server to log in to the system.