NTLM Authentication

The NTLM authentication method reuses the identity information associated with the user's current Windows session that is created when the user initially logs in to Win-dows. When both the client computer and the server computer belong to the same Windows domain or two separate Windows domains with established trust between them, this can provide a single sign-on experience.

If the client computer belongs to a separate Windows domain (without trust estab-lished to the server computer’s domain), the current Windows session is not valid in the Windows domain of the server computer and the user will be prompted for user name and password. The user must then enter user name and password of a valid account that belongs to the Windows domain of the server computer.

It is not possible to delegate NTLM authentication, Spotfire Server can not reuse the authentication credentials presented by the client, for example when authenticating against an Information Services data source that also uses NTLM. If you need such functionality, you must use Kerberos instead.

Upgrading to 5.0 or later: Spotfire Server supports NTLMv2 since version 3.2. The older NTLMv1 authentication mechanism was deprecated in version 4.5 and has now been removed. The instructions below explain how to set up the newer NTLMv2 authentication mechanism.

The NTLM authentication method needs to be combined with a User Directory in either:

 LDAP mode, recommended, see “User Directory in LDAP Mode” on page 81.

 Spotfire database mode, provided that the default Post-Authentication Filter is configured in auto-creating mode, see “User Directory in Spotfire Database Mode” on page 80.

The following instructions assume that either of these combinations is already fully working.

When using the NTLM authentication method, the User Directory is typically config-ured for the NetBIOS domain name style.

Setting up NTLM authentication involves two steps:

1 Creating a computer service account in your Windows Domain

You must create a computer service account in your Windows Domain. A Visual Basic script, SetupWizard.vbs (developed by IOPLEX Software) is distributed with Spotfire Server and will perform this task. The script must be run on a Windows machine, but does not have to be run on the same machine as the server is installed on.

If you are unable to run this script, or prefer to create the account manually, make sure to create a computer account. A user account will not work. Reusing an existing com-puter account will not work. See “Creating a Comcom-puter Account Manually” on page 63.

2 Configuring NTLM authentication using configuration commands.

Note: If you have more than one Spotfire Server in the cluster, you must also perform additional steps on each Spotfire Server.

 To create a computer service account in your Windows domain:

You must be logged into your Windows domain as a member of the group Account Operators or Administrators to run the SetupWizard.vbs script.

1 Double click on the setupwizard.vbs script located in the directory <installation dir>/

tomcat/bin. If the server is installed on a Linux or Solaris machine, the script has to be copied to a Windows machine first.

2 In the Domain Controller Hostname panel, enter the hostname of one of your domain controllers. Click OK.

3 In the Account Name panel, enter the short name of the computer account to be created. The short name must not exceed 15 characters. Click OK.

4 In the Distinguished Name panel, enter a distinguished name for the account to be created. A distinguished name based on the short name entered in the previous panel is suggested. You should edit this to match your Windows domain, with regards to parameters such as in which Organizational Units (OU) the account should be placed.

Click OK.

5 In the Account Password panel, enter a password for the account to be created.  Click OK.

6 A dialog will show with text indicating if the tool was successful or not.  Click OK.

Note: If the tool was unsuccessful, you should make sure that the logged in user has the required permissions to create accounts in the Windows Domain, and that the Domain Controller can be reached.

7 The file SetupWizard.txt, created by the tool in the folder where the tool is located, will open. If it does not, open it manually. The information is required to run the NTLM authentication configuration commands. File example:

# Generated by the Jespa Setup Wizard from IOPLEX Software on 2011-04-07 jespa.bindstr = dc.example.research.com

jespa.dns.servers = 192.168.0.1

jespa.dns.site = Default-First-Site-Name

jespa.service.acctname = [email protected] jespa.service.password = Pa33w0rd

Creating a Computer Account Manually

If you prefer to create the computer account manually, you should do so using the Microsoft Management Console snap-in Domain Users and Computers. Refer to Microsoft documentation for details on how to use this tool.

When you have created a new computer account, you need to set a password for this account. Unfortunately, this is not possible to do in the Microsoft Management Con-sole. In the directory <installation dir>/tomcat/bin there is a VBS script called SetComputerPassword.vbs. Run this script from the command line with the account name and password as arguments to the command.

Note: The SetComputerPassword.vbs file can only be executed on a Windows machine.

The script must be copied to a Windows machine, but does not have to be run on the same machine as the server is installed on.

Example:

SetComputerPassword.vbs  jespa‐[email protected]  Pa33w0rd

 To configure NTLM for a single server Use the Configuration tool

or

1 Use the command config‐ntlm‐auth (page 221) and list‐ntlm‐auth (page 261) to configure NTLM authentication.

2 Use the set‐auth‐mode (page 273), import the configuration and restart the server to activate the NTLM SSO authentication method.

To run these commands, you need some of the specific information described below.

Server  (optional)

The name of the server instance to which the specified configuration options belong. If no server name is specified, then all parameters will be shared, applying to all servers in the cluster. It is common to use server-specific values for the account name, password and localhost  NetBIOS name configuration options.

Account name

(required)

Specifies the fully qualified name of the Active Directory computer account that is to be used by the NTLM authentication service. This account must be a proper computer account, created solely for the purpose of running the NTLM authentication service. It can neither be an ordinary user account, nor an account of an existing computer. that the local part of an Active Directory computer account name always ends with a dollar sign, for instance: 

ntlm‐[email protected]. The local part of the account name (excluding the dollar sign) must not exceed 15 characters.

Example: ntlm‐[email protected] Password 

(required)

Specifies the password for the computer account used by the NTLM authentication service.

DNS domain name (optional)

The DNS name of the Windows domain to which Spotfire Server’s computer belongs. The specified domain name will automatically be resolved into domain controller hostnames. As an alternative to specifying a DNS domain name, it is also possible to specify a domain controller hostname directly. It is recommended to use the DNS domain name option, since you then automatically get the benefits of fail-over and load-balancing, provided that you have more than one domain controller. The DNS domain name and domain controller arguments are mutually exclusive.

Example: research.example.com Domain controller

(optional)

The DNS hostname of an Active Directory domain controller. It is recommended that the DNS domain name option is to be used instead, since that option gives the benefits of fail-over and load-balancing. The domain controller and DNS domain name arguments are mutually exclusive.

Example: dc01.research.example.com DNS servers

(optional)

A comma-separated list of IP addresses of the DNS servers associated with the Windows domain. When no DNS servers are specified, the server will fall back to use the server computer’s default DNS server configuration.

Example: 192.168.1.1,192.168.1.2 AD site 

(optional)

Specifies the Active Directory site where the Spotfire system is located. Specifying an Active Directory site can potentially increase performance, since the NTLM authentication service will then only communicate with the local Windows domain controllers.

Example: VIENNA DNS cache TTL

(optional)

Specifies how long (in milliseconds) name server lookups should be cached. The default value is 5000 ms.

 To configure NTLM for a cluster with multiple servers

To set up NTLM for a cluster with multiple servers, start with configuring the options common to all servers in the cluster. This is performed according to the instructions in

“To configure NTLM for a single server” on page 63, with the following modifica-tions.

This step involves specifying a DNS domain name (recommended) or a domain control‐

ler (not recommended) and possibly also an AD site name. The account name and pass‐

word options must be left out at this point (will be specified later). It is also very important that the server argument is not specified at this stage.

The common NTLM configuration now needs to be completed with account informa-tion for each Spotfire Server in the cluster. When a server logs in to the domain con-troller, its identity is based on the name of the computer account it uses for the connection. The resulting name is known as a localhost NetBIOS name. Since a domain controller only allows one connection per localhost NetBIOS name, multiple servers typically cannot login using the same computer account. Thus, each server ide-ally uses its own NTLM account.

Note: Sometimes, like when running two servers on the same computer, it happens to be possible to actually share the NTLM account by explicitly specifying individual localhost NetBIOS names that are used instead of the name derived from the NTLM account.

 If separate NTLM accounts are to be used, then use the account name and password options to specify the server's own NTLM account.

 If a shared NTLM account is to be used, specify the account name and password for the shared account, as well as a unique localhost NetBIOS name. The localhost NetBIOS names must not exceed 15 characters.

When the decision has been made whether to use individual NTLM accounts or share an NTLM account by explicitly specifying localhost NetBIOS names, the command

Localhost NetBIOS  name 

(optional)

Specifies the NetBIOS name, used by a server to identify its

connection to the domain controller. The default value is derived from the account name option. This option is only necessary to specify when there is more than one server in the cluster. Since a domain controller only allows one connection per NetBIOS name, a cluster with multiple servers must either use separate NTLM accounts for each server or explicitly specify unique localhost NetBIOS names for the servers. The localhost NETBIOS name must not exceed 15 characters in length.

Example: ntlm‐svc‐server1 (for server1.research.example.com) Connection ID 

header name  (optional)

This parameter specifies the name of an HTTP header containing unique connection IDs in environments where the server is located behind some kind of proxy or load-balancer that does not properly provide the server with the client's IP address. The specified HTTP header must contain unique connection IDs for each client connection and is thus typically based on the client’s IP address together with the connection's port number on the client side.

config‐ntlm‐auth is run again, once for each server in the cluster. The command will update Spotfire Server configuration with the cluster server’s specific configuration options. This time, the server argument must be specified so that it reflects the server name, as defined in the server’s bootstrap.xml file.