Configuration Instructions

The following instructions are required to configure Spotfire Server for the Kerberos authentication method.

As a Domain Administrator:

1 Create a Kerberos service account:

In this step the Kerberos service account is created. The following examples will assume that the account's name is spotsvc.

Logged in as a domain administrator or a user which is a member of the built in Account Operators domain group, launch the Active Directory Users and Computers MMC snap-in and create a normal user account with the following properties:

 Use the same identifier in the Full name and User logon name (pre‐Windows 2000) fields and make sure to use only lower case characters and that there are no spaces in these fields.

 Select the Password never expires option.

 Clear the User must change password at next logon option.

 If Kerberos unconstrained delegation is to be used for Information Services data sources, the account option Account is trusted for delegation must also be

selected.

 Kerberos constrained delegation can also be used for Information Services data sources, but is set up on a service-by-service basis and is not described here.

2 Register Service Principal Names:

While still logged in as a domain administrator or as a user which is a member of the built in Account Operators domain group, use the setspn.exe command-line tool to reg-ister two Service Principal Names (SPNs) for the Kerberos service account. The setspn.exe command-line tool is a part of the Microsoft Support Tools package which is typically installed on domain controllers. The Support Tools can also be down-loaded from Microsoft's web page.

The setspn.exe tool for Windows Server 2008 or later has been improved with extra argument checking to prevent that no duplicate Service Principal Names are created. If you use the improved version of the setspn.exe tool, then execute the following two commands to register the Service Principal Names:

>  setspn  ‐S  HTTP/<fully  qualified  hostname>[:<port>]  <service  account  name>

>  setspn  ‐S  HTTP/<hostname>[:<port>]  <service  account  name>

If you are using the setspn.exe tool for Windows Server 2003 or earlier, the extra argu-ment checking is not supported. Instead, execute the following two commands to reg-ister the Service Principal Names:

>  setspn  ‐A  HTTP/<fully  qualified  hostname>[:<port>]  <service  account  name>

>  setspn  ‐A  HTTP/<hostname>[:<port>]  <service  account  name>

Note: It is recommended not to have multiple Kerberos-enabled HTTP services on one machine.

Replace the <fully qualified hostname>, <service account name>, <hostname> and <port>

with the appropriate values. Note: It is vital to note that all values are case sensitive.

 fully qualified hostname: The fully qualified DNS hostname of the computer hosting Spotfire Server (written in lower case)

 hostname: The short DNS hostname, without domain suffix, of the computer hosting Spotfire Server (written in lower case)

 service account name: The user login name of the previously created Kerberos service account (written in lower case)

 port: The TCP port number that Spotfire Server is listening on

Note: You must use the name of an Arecord for Spotfire Server. A CNAME record will not work.

Note: Avoid explicitly specifying the port number if Spotfire Server is using the default HTTP port 80.

Example: Registering Service Principal Names for the spotsvc Kerberos service account to be used by a Spotfire Server installed on the spotfireserver.research.example

.com computer and listening on the default HTTP port 80 or the default HTTPS port 443:

>  setspn  ‐A  HTTP/spotfireserver.research.example.com  spotsvc

>  setspn  ‐A  HTTP/spotfireserver  spotsvc

This will create these two Service Principal Names:

 HTTP/spotfireserver.research.example.com

 HTTP/spotfireserver

Example: Registering Service Principal Names for the spotsvc Kerberos service account to be used by a Spotfire Server installed on the spotfireserver.research.example

.com computer and listening on the non-default HTTP port 8080:

>  setspn  ‐A  HTTP/spotfireserver.research.example.com:8080  spotsvc

>  setspn  ‐A  HTTP/spotfireserver:8080 spotsvc This will create two SPNs:

 HTTP/spotfireserver.research.example.com:8080

To list the resulting Service Principal Names for a Kerberos service account, you can execute the following command:

>  setspn  ‐L  <service  account  name>

Example: Verifying Service Principal Names for the spotsvc Kerberos service account

> setspn ‐L spotsvc

3 Create a keytab file for the Kerberos service account:

While still logged in as a domain administrator or as a user which is a member of the built in Account Operators domain group, execute the following command:

>  ktpass  /princ  HTTP/<fully  qualified  hostname>  [:<port>]@<realm>  /ptype  krb5_nt_principal  /crypto  rc4‐hmac‐nt  /mapuser  <service  account  name>  /out  spotfire.keytab  ‐kvno 0 /pass  *

Replace the <fully qualified hostname>, <port>, <realm>, and <service account name>

with the appropriate values.

Note: It is vital to note that all values are case sensitive.

 fully qualified hostname: The fully qualified DNS hostname of the computer hosting Spotfire Server, which must exactly match the fully qualified hostname used when registering the SPNs (written in lower case)

 port: The TCP port number that Spotfire Server is listening on (only specified if the port number was explicitly included in the registered SPNs)

 realm: The name of the Kerberos realm, which is the DNS domain name written in upper case

 service account name: The user login name of the service account with the registered SPNs (written in lower case)

The tool will prompt for the password of the service account. Enter the same password as when creating the service account.

It is not critical to use the name spotfire.keytab for the keytab file. However, the remaining instructions will assume that this is the name of the keytab file.

Note: If you ever change the password of the Kerberos service account in the future, you must re-create the keytab file.

Note: Older versions of the ktpass.exe tool will fail to create the keytab file when it is not being run on an actual domain controller.

Example: Creating a keytab file for the spotsvc Kerberos service account in the research.example.com domain for Spotfire Server listening on the default HTTP port 80 on the spotserver.research.example.com computer:

> ktpass /princ HTTP/[email protected] / ptype krb5_nt_principal /crypto rc4‐hmac‐nt /mapuser spotsvc /out spotfire.keytab ‐kvno  0 /pass *

Example: Creating a keytab file for the spotsvc Kerberos service account in the research.example.com domain for Spotfire Server listening on the HTTP port 8080 on the spotserver.research.example.com computer:

>  ktpass  /princ  HTTP/spotfireserver.research.example.com:8080@

RESEARCH.EXAMPLE.COM  /ptype  krb5_nt_principal  /crypto  rc4‐hmac‐nt  /mapuser  spotsvc  /out  spotfire.keytab  ‐kvno 0 /pass  *

On Spotfire Server:

4 Copy the Kerberos service account’s keytab file to Spotfire Server:

Copy the spotfire.keytab file to the directory <installation dir>\jdk\jre\lib\security (Windows) or <installation dir>/jdk/jre/lib/security (Unix) on Spotfire Server.

Note: Since this file contains sensitive information it must be handled with care. The file must not be readable for unauthorized users.

To list the contents of the keytab file, use the klist command-line tool which will list the principal name and security credentials. The tool is included in the bundled JDK and is only available when installed on Windows:

>  <installation  dir>\jdk\jre\bin\klist.exe  ‐k  ‐t  ‐K  <keytab  file>

To test the keytab file, use the kinit command-line tool which is also included in the bundled JDK on Windows platforms:

>  <installation  dir>\jdk\jre\bin\kinit.exe  ‐k  ‐t  <  keytab  file>  HTTP/<fully  qualified  hostname>  [:<port>]@<realm>

If the keytab file is correctly set up, a ticket cache file will be created in the logged in user’s home directory. It can typically be found with the path C:\Users\<user>\

krb5cc_<user>. As soon as you have verified that the ticket cache was created, you must delete the ticket cache file to prevent future problems.

5 Configure Kerberos for Java:

Open the file krb5.conf located in the directory <installation dir>\jdk\jre\lib\security (Windows) or <installation dir>/jdk/jre/lib/security (Unix) and edit the following values to reflect your environment:

 MYDOMAIN: The name of the Kerberos realm, usually the same as the name of the Windows Domain, written in upper case

 mydomain: The name of the Windows Domain, written in lower case

 mydc: The name of the domain controller, written in lower case

Note: The arguments are case-sensitive. It is critical to use the correct case for these values!

For more information, See “krb5.conf” on page 177.

Example: Configuring Kerberos for Java in the research.example.com domain, with the two domain controllers dc01.research.example.com and dc02.research.example.com:

===============

6 Select Kerberos as the Spotfire login method:

Use the Configuration Tool or

 Use the config‐kerberos‐auth command (page 213) to configure the Kerberos authentication method. The command takes the following two parameters:

 Keytab file: The fully qualified path to the spotfire.keytab file. If the keytab file is named spotfire.keytab and has been copied to the recommended directory, the default path ${java.home}/lib/security/spotfire.keytab is already correct. The shorthand ${java.home} refers to the directory <installation dir>\

jdk\jre (Windows) or the <installation dir>/jdk/jre (Unix)

 Service Principal Name: Specify the same Service Principal Name that was used when creating the keytab file. Example: HTTP/

spotfireserver.research.example.com

 Use the set‐auth‐mode command (page 273) to activate the Kerberos SSO authentication method.

 Import the configuration and restart the server for the changes to have effect.

7 Disable user name and Password fields in client login dialog:

Since the Kerberos authentication method provides single sign-on capabilities, there is no need to prompt an end user for user name and password in the Spotfire client login dialog. In fact, any entered user name and password is unlikely to work, even if the credentials are fully valid.

Use the Configuration Tool or the following config‐login‐dialog command to disable the user name and password fields in the Spotfire client login dialog:

>  config  config‐login‐dialog  ‐‐allow‐user‐provided‐credentials=false

(For more information about the config-login-dialog command, go to page 220.) Note: If you are using the Configuration Tool, select Never display login dialog for the Login dialog option.

Then, import the new configuration and restart the server.