IBM Marketing Platform supports multiple authentication mechanisms. Microsoft Windows Integrated login (NTLM v1) is one such mechanism that is widely deployed especially in conjunction with the Microsoft Windows 2003 Active Directory services. With the arrival of Microsoft Windows 2008 Server and Microsoft Windows 7 the default minimum standard (LmCompatibilityLevel) has changed and requires usage of NTLM v2 protocol. NTLM v2 is the successor to NTLM v1 with enhanced security. NTLM v2 is not natively supported by IBM Marketing Platform. The purpose of this article is to outline a solution using Microsoft Internet Information Services (a component of the Windows 2008 Server OS) that gets NTLM v2 working with the IBM Cross Channel Marketing suite and is compatible with the already released application versions.

This article is written by Abdul Rahim Suriya who works as Software Engineer for IBM Software Labs for IBM Cross Channel Marketing products (formerly Unica).

Target Audience

• Administrators at the customer site using Windows integrated login and considering upgrade to Windows 2008 servers
• Consultants and Services team members performing a deployment to support NTLM v2
• Tech Support team members supporting Platform deployments working with NTLM v2

1. Introduction

Integrated Windows Authentication refers to the Microsoft devised authentication mechanism that does not prompt users for the username and password. It involves cryptographic exchange between a user agent (browser) and the Active Directory aware applications (IIS for example) to ensure the user agent is a valid AD domain user. IWA is typically deployed in an intranet environment. IWA can be performed using underlying authentication protocols like NTLM, Kerberos.

IBM Marketing Platform supports windows integrated login as an authentication mechanism utilizing NTLM v1 as the authentication protocol in conjunction with Internet Explorer and Windows Active Directory. The default LmCompatibilityLevel setting for the newer server OS (Windows Server 2008, Windows Server 2008 R2, Windows Server 2012) and the new clients (Windows 7) requires the NTLM v2 authentication protocol to be the default authentication protocol.

The remainder of this article describes how you can use NTLM v2 for the IBM Cross Channel Marketing suite with some help from the Microsoft Internet Information Services web server.

2. Solution Concept

IBM Marketing Platform supports a windows integrated login mechanism that enables sign in from Internet Explorer that can negotiate the NTLM v1 headers. The native support for the NTLM protocol is limited to NTLM v1 in IBM Marketing Platform. A basic deployment of IBM Marketing Platform with windows integrated login is depicted in Fig 1

Figure 1- Basic Deployment of Marketing Platform with Windows integrated login

To support NTLM v2, the basic deployment outlined in Fig 2 is proposed

Figure 2- Marketing Platform deployed with web server supporting NTLMv2

For Windows Integrated Login using NTLM V2, IBM Marketing Platform leverages another supported authentication mechanism – web access control. The web access control mechanism enables user authentication to occur outside the suite and expects the authenticated user information to be supplied to IBM Marketing Platform in the form of a configurable HTTP(s) request header.

This mechanism is typically used in conjunction with the IBM Tivoli Access Manager or CA SiteMinder. These access control mechanisms authenticate the users and set a request header which is then made available to the backend web application server (WebSphere or WebLogic) and is consumed by IBM Marketing Platform. For NTLMv2 we will use Internet Information server (Microsoft IIS) which understands and supports NTLM v2 natively. The authentication is carried out by IIS using the request header along with Web access control. This mechanism conveys the logged-in user information is conveyed to Marketing Platform.

3. Additional Components required

This solution requires intermediate components that can handle the authentication using NTLM v2 and pass on the logged-in user information to IBM Marketing Platform.

The following third party components are required for this solution (as compared to an IBM Marketing Platform installation that works with NTLM v1):

• Microsoft Internet Information Services (IIS). To enable communication between IIS and our Application server you will need Application server plug-in for Microsoft IIS – ensure the correct plug-ins are selected for the your OS and Application Server version combination
• URL re-writer that has access to authentication information – you can ISAPI Rewrite Lite Edition, a free component. NOTE: Microsoft provides a URL Rewriter module for IIS. However that module will not work for this solution due to the architecture – the module is invoked before the authentication has happened and hence the URL Rewrite module does not have access to the authentication information. This necessitates usage of an ISAPI Filter for IIS that has access to the authentication information and can pass it on to the backend as a HTTP request header

3.1 Microsoft Internet Information Services (IIS)

The following instructions apply to Microsoft IIS 7 or later

1. Ensure IIS is installed on a system that has the same network domain suffix (unicaindia.com in examples below) as the IBM Marketing Platform application server host.
2. For WebSphere + IIS combination, enable the IIS Role Services for IIS 6 Management compatibility components as outlined in the WebSphere IIS plugin documentation
3. Ensure Windows Integrated authentication is allowed on IIS. For more details – refer (A)
4. Disable anonymous access for your web site and then enable Windows authentication (you might want to do this step after a confirmation that the web server is able to correctly pass on the requests to backend application server)
5. If using 32-bit plug-ins on 64-bit OS, Enable 32-bit application support within IIS. Refer (C)

3.2 IIS URL Re-writing for setting a request header

The request header should be set for the application server to determine the authenticated user.

Use ISAPI Rewrite (Lite Edition) or another compatible IIS URL re-writer. Refer (B).

• Download the ISAPI_Rewrite filter from isapirewrite.com – the freeware lite edition is sufficient for this solution
• Install the ISAPI_Rewrite filter
• Configure the rewrite filter (httpd.conf) with the following rewrite rules (sample)

RewriteEngine on

RewriteCond %{REMOTE_USER} UNICAINDIA\\(.*)

RewriteHeader unicasso: .* %1

The above rewrite rule extracts the authenticated user name from the REMOTE_USER variable value and strips the domain name with trailing backslash (“UNICAINDIA\” in this case) before setting the remaining text as a new request header with the name unicasso

Figure 3- ISAPI Rewrite configuration

• Ensure that in the ordered list of ISAPI filters for the website, the URL rewriter appears before the application server specific ISAPI filter.

3.3 Application Server plug-in for Microsoft Internet Information Services

The application server plug-in for IIS is required to proxy the HTTP(s) request from IIS to the backend application server.

For WebLogic, the IIS plug-in is supplied as a DLL file named iisproxy.dll and can be found under the WL_HOME/server/plugin/win/ folder. Refer the Oracle WebLogic documentation for further information.

For WebSphere, the IIS plug-in is part of a separate installation package (refer the technote http://www-01.ibm.com/support/docview.wss?rs=899&uid=swg21367202) to be additionally installed on the server hosting the IIS.

4. Detailed Instructions for WebLogic (WL 11gR1+ – Refer (D))

1.    Open IIS Manager from the control panel

2.    Create a new site (example: UMP) and assign a port to it

Figure 4- A new site defined in IIS

3.    Create a folder under IIS for the site (at the same level as wwwroot) under inetpub

4.    Copy the file iisproxy.dll and iisforward.dll from server\plugin\win\64 folder of the Application server installation to the folder created in step (3).

Figure 5- The Site folder on the file system containing WebLogic Application Server IIS plugin

5.    If you are using the 32 bit DLL on a 64-bt OS, enable 32-bit application support at the site level as follows

• Open IIS7.x and click on Application Pools.
• Right-click on the application pool for your website or the default application pool and go to the Advanced Settings tab.
• Ensure that Enable 32-bit applications is set to True

6.    Select your application name and add ISAPI filter as follows-

• filter name: WL_IIS_FORWARD
• executable: <path to the iisforward.dll>

Figure 6- WL IIS Forward ISAPI filter

7.    Click on Handler mapping at the application level. Add a script map with the following details

• Name: WL_IIS_PROXY
• Request Path: *
• Executable: <File system path to iisproxy.dll>

Figure 7- IIS Proxy handler mapping

8.    Create an iisproxy.ini file that will tell the WebLogic ISAPI filter about the location of the weblogic server (host, port) and the paths that should be forwarded to WebLogic instance
<sample content for iisproxy.ini>
WebLogicHost=wlserver.unicaindia.com
WebLogicPort=8500
WlForwardPath=/weblogic
PathTrim=/weblogic

9.    Restart the IIS server and WebLogic server instance.
10.    The URL for IIS host and site port should be followed by /weblogic/unica, the WebLogic IIS proxy would handle the trimming of the /weblogicfrom the request path (Refer the value of PathTrim from step 8 above). In case you want to change the access URL, adjust the PathTrim value and the access URL accordingly.

5. Detailed Instructions for WebSphere (Refer (E))

1.  Install the WebSphere web-server plug-ins including the latest fix pack. Use a path that does not include parenthesis. Ensure that the version number of the web server plug-in and the application server are compatible, Refer (F). Examples in this article use WebSphere Application Server 7.0.0.19 and 8.0.0.2 with their associated plug-ins

2.  On the WAS instance, update the virtual host setting to include the port number for the IIS web site you will be using.  Failure to do this step results in 404 errors when accessing the application via IIS.

Figure 8- Adding the IIS port to the Virtual host (default_host)

3. For WebSphere Application Server 8.x

• Define a web server of the type IIS on the WebSphere instance and set the plug-in properties as required for your environment
• Generate and Propagate the web-server plug-in. No changes should be required to the generated web-server plug-in. However, you might want to increase the ESI cache size or disable ESI altogether.

For detailed instructions refer to the IBM Websphere plugins documentation

4.  For WebSphere Application Server 7.x

• Execute <Plugins Home>\bin\configurewebserver1.bat passing in the parameter -profileName <WAS_PROFILE_NAME> this will define a web server of the type IIS on the WebSphere instance.
• plugin-cfg.xml file will be generated in <Plugin_Home>\config\webserver1 location. Generate and Propagate the web-server plug-in. Save the necessary changes.
• To configure IIS7 Plugin with WAS, navigate to the <Plugins Home>\bin path and execute configureIIS7Plugin.bat.e.g.  configureIIS7Plugin.bat -plugin.home C:\IBM\Plugins -plugin.config.xml  C:\IBM\Plugins\config\webserver1\plugin-cfg.xml For detailed instructions kindly refer the IBM Websphere plugins documentation

5.  On the IIS web site, create a site (example: Unica). Add a virtual directory to the web site. Name the alias “sePlugins”. The corresponding physical path for this virtual directory is the folder containing the iisWASPlugin_http.dll.

• Click the Test Settings button. If the settings test fails, then either change the permissions of the physical directory, or select Connect As, and let IIS connect as a Windows user account that has authority to files in that physical path.

NOTE: Even if you add a virtual directory the URL patterns will not change.

Figure 9- Virtual directory defined for IIS site

Figure 10- Physical folder contents corresponding to the sePlugins virtual directory

6.  In the navigation tree, select the sePlugins virtual directory that you just created. On the Features panel, double-click Handler Mappings, and then click Edit Feature Permissions on the Actions panel. Select Script and Execute, if they are not already selected. Click OK

Figure 11- Edit Feature permissions

7.  Within the same folder as iisWASPlugin_http.dll, edit the plugin-cfg.loc file (add the file if it does not exist) to contain 2 lines – the complete file system location of the plugin-cfg.xml file on line # 1 and a blank line # 2

8.  At the web site level, add an ISAPI filter with a name like iisWASPlugin and select the iisWASPlugin_http.dll as the executable

Figure 12- ISAPI filter for the WAS IIS plug-in

9.  At the top (server) level node in IIS manager, use the “ISAPI and CGI Restrictions” features panel item to add a new restriction entry with a description like “WASPlugin”, the location of the iisWASPlugin_http.dll in the “ISAPI or CGI Path” and select the checkbox against the “Allow extension path to execute”

Figure 13- ISAPI and CGI restriction setting for WAS IIS plug-in

10.  Restart IIS server and your WebSphere Application Server profile.

11.  If you cannot get the solution working as desired, changing the log level in the plugin-cfg.xml from ERROR to INFO or DEBUG and accessing the IIS URL from Internet Explorer may help. Check the following points

• The URI pattern defined in the plugin-cfg.xml should have /unica/* as one of the entries
• The transport hostname should point to the host machine where Platform web application is running
• The Virtual host settings should include the IIS site port number on which the plug-in is configured

6. Marketing Platform Settings

1.  Configure the LDAP server details (AD 2008+) in Marketing Platform and synchronize users. For more details refer to the IBM Marketing Platform Administrator’s Guide.

2.  Change the setting for “Web access control header variable”  to use the variable name as specified in the re-write rules (example: unicasso in the example used in this document)

Figure 14- Configure Web Access Control for IBM Marketing Platform

3.  Update the login mode of platform to “Web Access Control”

4.  Ensure that the navigation URL (IBM Marketing Platform URL) specified is the IIS site URL and restart the web application

Figure 15- Update the IBM Marketing Platform navigation URL as appropriate

5.  When using this solution along-with dashboard.war, users might notice issue with access to the dashboard (NullPointerException is displayed instead of the dashboard contents). A fix for this issue is targeted for release in 8.2.0.7 and 8.5.0.4

7. Important Points

Any web server that supports the NTLMv2 authentication mechanism and is able to communicate with the backend application server should work for the proposed solution Irrespective of Windows Integrated Login – Windows 2008 (R2) Server AD can still be used as a source of LDAP login with Marketing Platform without requiring any change in the setup. The end users can login using their domain username and password. Microsoft provides a URL Rewriter module for IIS. However that module will not work for this solution due to the architecture – the module is invoked before the authentication has happened and hence the URL Rewrite module does not have access to the authentication information. This necessitates usage of an ISAPI Filter for IIS that has access to the authentication information and can pass it on to the backend as a HTTP request header. For any IIS related problems/queries contact your system/network administrator

8. References

A. Windows Authentication with Microsoft IIS – http://www.iis.net/ConfigReference/system.webServer/security/authentication/windowsAuthentication

B. ISAPI Rewrite module – http://www.isapirewrite.com/

C. Issue when Enable 32-bit application is not set – http://helpdeskgeek.com/how-to/calling-loadlibraryex-on-isapi-filter/

D. Installing and Configuring Microsoft IIS plugin with WebLogic – http://docs.oracle.com/cd/E12840_01/wls/docs103/plugins/isapi.html

E. Configure WAS web server plug-in for the best results – http://www-01.ibm.com/support/docview.wss?uid=swg21450051&acss=dakc

F. IBM web server plug-in policy for Websphere Application Server – https://www-304.ibm.com/support/docview.wss?uid=swg21160581

G. Application Request Routing module for Microsoft IIS – http://www.iis.net/download/ApplicationRequestRouting