A default xMatters - SQL Server installation uses SQL Authentication to connect to the xMatters database. This article outlines and explains the configuration process and requirements for using Windows NTLM Authentication between xMatters and SQL Server 2008.
Using Windows Authentication requires that the same trusted domain user runs the xMatters Services on the xMatters server, and owns the xMatters database on the SQL Server machine.
Note: This functionality is currently supported on xMatters 4.1 and 5.0 (support for xMatters 5.0 was added in xMatters 5.0 patch 008.)
The following configuration is recommended:
- xMatters and SQL Server 2008 installed on separate Windows 2008 R2 systems.
- Both systems installed in the same domain, with a trusted domain user configured on both systems.
Before applying any of the changes or configuration steps described in this article, ensure that you stop the xMatters Node and Webserver Services.
Install xMatters according to the instructions in the xMatters installation and administration guide, and use the installer to create the xMatters schema on your SQL Server 2008 database. (You can use any name and password for the xMatters database owner during installation of the schema; you will be changing them later in this process.)
Note: the DLL architecture must match the architecture of the xMatters JVM. To determine the JVM architecture, run the following command from a command prompt:
If 64-bit Java is found, the response will include "Java Hotspot(TM) 64-bit Server VM".
To install the Windows Authentication components:
- Download the attached ntlmauth-1.2.7.zip file, and extract the contents.
- Determine your Java version, as explained above.
- Copy the appropriate ntlmauth.dll file (32-bit or 64-bit Java) to your <xMHOME>\jre\bin folder.
Configuring SQL Server
Once you have installed xMatters and the DLL, open SQL Management Studio and, using the system administrator account, connect to the database that xMatters has been configured to use.
To configure SQL Server:
- Ensure that the Server Authentication is configured to support "Windows Authentication Mode" OR "SQL Server and Windows Authentication Mode".
- Navigate to Security > Logins.
- Right-click the Logins folder, and then select New Login.
- In the Login name field, type or select the trusted domain user that will be used to run the xMatters application and own the xMatters database.
- Select the Windows Authentication radio button.
- In the Default database field, select the xMatters database.
- Click User Mapping, and map the user to the newly installed xMatters database.
- Set the Default Schema to the xMatters schema,
The domain user should now be added as a new user in the xMatters database. (To confirm, navigate to Databases > XMATTERS > Security > Users.)
The default installation will configure xMatters to use SQL Authentication to connect to the database. To use Windows Authentication, you must edit the common.properties file.
To configure the connection properties:
- Open a command prompt, and navigate to <xMHOME>.
- Decrypt the common.properties file by running the following command:
APSecure.bat decrypt common\common.properties common\common.txt.
- Open the newly created common\common.txt file in a text editor.
- Blank the JDBC_USERNAME and JDBC_PASSWORD parameters.
- Do NOT delete the keys; set the value to blank, as follows:
- Re-encrypt the file by running the following command:
APSecure.bat encrypt common\common.txt common\common.properties
- Delete the common\common.txt file.
Configuring JTDS for xMatters 4.1
Windows Authentication over NTLM requires that the jtds library is only loaded by the application root classloader. If the JTDS jar is in the individual classpaths of the web applications, NTLM authentication will fail as the static initialization block in the JTDS library that loads the NTLM native code will be called multiple times and throw an exception.
To ensure that the correct JTDS library is in the classpath, delete the existing JTDS 1.2 jar in any/all of the following locations:
To install the JTDS jar for Windows Authentication:
- Replace the JTDS jar in <xMHOME>\webserver\lib\ext with the attached jtds-1.2.7.jar file.
- Create a new folder in <xMHOME>\node\lib\foundation-lib called jtds-1.2.7 and copy the attached jtds-1.2.7.jar into the new folder.
- Delete the <xMHOME>\node\lib\foundation-lib\jtds-1.2 folder and its contents.
- Open the node-start.conf file in a text editor, and search-and-replace the textnode\lib\foundation-lib\jtds-1.2\jtds-1.2jar with node\lib\foundation-lib\jtds-1.2.7\jtds-1.2.7jar
- Save and close the file.
Before restarting the xMatters node and web server, the services need to be updated to run as the trusted domain user that has been configured on the SQL Server database for xMatters.
To configure the Windows Services:
- Open the Windows Services Control Panel, and then double-click the xMatters Node service.
- In the Properties dialog, click the Log On tab and update the credentials to log on as the trusted domain user (see screenshot below). Enter the password, and then click OK.
- Start the service.
- Repeat this for the xMatters Webserver service entry.
DTN-3179, XFO-3597, JDN-3822
Originally created by Don Clark