4.17 Spotfire Database using Kerberos Authentication
4.17.1 Workflow Overview
1 Create a Windows domain account for the Spotfire database 2 Create the Spotfire database
3 Oracle: Connect the Spotfire database account to the Windows domain account 4 Install the Spotfire Server
5 Install the database vendor's JDBC driver 6 Configure Kerberos for Java
7 Optional: Create a Kerberos keytab file for the Spotfire database account
8 Create a JAAS application configuration for the Spotfire database connection pool 9 Register the JAAS application configuration file with the JDK
10 Bootstrap the Spotfire Server
4.17.2 Detailed Instructions
To create a Windows domain account for the Spotfire database:
You must be 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 Comput‐
ers MMC snap-in and create a normal user account with the following properties:
Use the same identifier in the Full name, User logon 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.
Check the Password never expires option.
Clear the User must change password at next logon option.
Recommended: Check the Account is sensitive and cannot be delegated option.
To create the Spotfire database:
Create the Spotfire database as described in the section “Prepare the Database” on page 14.
Oracle: Edit and run the create_databases.bat script. This will create a normal Oracle database account that authenticates with username and password.
Microsoft SQL Server: Edit and run the create_databases_ia.bat script. This will create a SQL Server database account and connect it to the previously created Windows domain account.
Oracle: To connect the Spotfire database account to the Windows domain account:
1 Log into the Oracle database instance using an account with the SYSDBA role.
Example: Connecting to a database with connection identifier ORCL as sysdba
> sqlplus sys@ORCL as sysdba
2 Alter the Spotfire database account so that it is identified externally by running the follow command:
SQL> alter user <SERVERDB_USER> identified externally as '<SERVERDB_USER>@
<REALM>';
Replace <SERVERDB_USER> and <REALM> with the Spotfire database account name and the Kerberos realm. Make sure to use upper case when specifying the Kerberos realm.
Example:
SQL> alter user spotuser450 identified externally as 'spotuser450@
RESEARCH.EXAMPLE.COM';
3 Test the Kerberos-enabled Spotfire database account by launching a command prompt running as the created Windows domain account. It should now be possible to connect to the database using the following command, assuming the connection identifier is ORCL:
> sqlplus /@ORCL
To install the Spotfire Server:
Install the Spotfire Server following the instructions in the section “Install Spotfire Server” on page 21.
To install a vendor database driver:
Install a vendor database driver as described in the section “Install Database Drivers”
on page 24.
To configure Kerberos for Java:
Follow the instructions in “To configure Kerberos for Java:” on page 57.
Optional: To create a keytab file for the Kerberos service account:
Option 1: Using the ktpass.exe command included with the Microsoft Support Tools On a computer with the Microsoft Support Tools installed (there is no need to be logged in as a privileged user), execute the following command:
> ktpass /princ <database account name>@<realm> /ptype krb5_nt_principal / crypto rc4‐hmac‐nt /out spotfire‐database.keytab /pass *
Replace the <database account name> and <realm> with the appropriate values. Note: All values are case sensitive.
service account name: The user login name of the Spotfire database account (written in lower case)
realm: The name of the Kerberos realm, which is the DNS domain name written in upper case
The tool will prompt for the password of the service account. Enter the same password as when creating the Spotfire database account.
It is not critical to use the name spotfire‐database.keytab for the keytab file. The fol-lowing instructions will nevertheless assume that this is the case.
Note: If you ever change the password of the Kerberos service account in the future, you must re-create the keytab file again.
Example: Creating a keytab file for the spotuser450 Spotfire database account in the research.example.com domain:
> ktpass /princ [email protected] /ptype krb5_nt_principal / crypto rc4‐hmac‐nt /out spotfire‐database.keytab /pass *
Finally, copy the spotfire‐database.keytab file to the directory <installation dir>\jdk\jre\
lib\security (Windows) or <installation dir>/jdk/jre/lib/security (Unix) on the Spotfire Server.
Note: Since this file contains sensitive information it must be handled with care. The file must under any circumstances not be readable for unauthorized users.
Option 2: Using the ktab.exe command included with the bundled JDK
On the computer where the Spotfire Server is installed, execute the following com-mand:
> ktab ‐k spotfire‐database.keytab ‐a <database account name>
Replace the <database account name> as described in Option 1 above.
It is not critical to use the name spotfire‐database.keytab for the keytab file. However, the remaining following instructions will assume that this is the case.
The tool will prompt for the password of the service account. Enter the same password as when creating the Spotfire database account.
Note: If you ever change the password of the Kerberos service account in the future, you must re-create the keytab file again.
Verify the created keytab by running the klist and kinit utilities:
> klist ‐k <installation dir> spotfire‐database.keytab
Example: Creating and verifying a keytab file for the spotuser450 Spotfire database account in the research.example.com domain:
> ktab ‐k spotfire‐database.keytab ‐a spotuser450
> klist ‐k spotfire‐database.keytab
> kinit ‐k ‐t spotfire‐database.keytab [email protected]
Finally, copy the spotfire‐database.keytab file to the directory <installation dir>\jdk\jre\
lib\security (Windows) or <installation dir>/jdk/jre/lib/security (Unix) on the Spotfire Server.
Note: Since this file contains sensitive information it must be handled with care. The file must under any circumstances not be readable for unauthorized users.
To create a JAAS application configuration for the Spotfire database connection pool:
Create the file <installation dir>\jdk\jre\lib\security\spotfire‐database.login (Windows) or <installation dir>/jdk/jre/lib/security/spotfire‐database.login (Unix) and populate it with one of the options shown below.
1 To create a JAAS application configuration for a keytab file:
Replace <service account name> and <realm> with the name of the Spotfire database account and the Kerberos realm. Make sure to use lowercase letters for the account name and uppercase for the realm name.
DatabaseKerberos {
com.sun.security.auth.module.Krb5LoginModule required
debug=true storeKey=true useKeyTab=true
keyTab="${java.home}/lib/security/spotfire-database.keytab"
principal="<SERVERDB_USER>@<REALM>";
};
2 To create a JAAS application configuration for username and password:
Replace <service account name> and <password> with the name and the password of the Spotfire database account.
DatabaseKerberos {
com.sun.security.auth.module.Krb5LoginModule required
debug=true storeKey=true useKeyTab=false doNotPrompt=false;
};
3 To create a JAAS application configuration for the native Ticket Cache:
To make it possible to login to the Spotfire database as the user currently running the server, the connection pool must be able to acquire the initial Ticket-Granting-Ticket (TGT) from the Spotfire Server’s host’s native Ticket Cache.
On modern Windows operating systems, the TGT session key cannot be exported unless the following registry key is modified:
[HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Lsa\Kerberos\
Parameters]"allowtgtsessionkey"=dword:00000001 DatabaseKerberos
{
com.sun.security.auth.module.Krb5LoginModule required
debug=true storeKey=true
useTicketCache=true doNotPrompt=false;
};
To register the JAAS application configuration file with the JDK:
Open the file <installation dir>/jdk/jre/lib/security/java.security in a text editor and add the following lines at the end of the file:
# Register Java Authentication & Authorization Services (JAAS) configurations
login.config.url.1=file:${java.home}/lib/security/
spotfire-database.login
To bootstrap the Spotfire Server, execute the bootstrap command:
Execute the bootstrap command (page 148). If the bootstrap command below executes successfully, the database connection is correctly established after using Kerberos authentication.
Oracle
To bootstrap the Spotfire Server, execute the bootstrap command:
> config bootstrap ‐‐test ‐‐driver‐class =oracle.jdbc.OracleDriver ‐‐database‐url=
<database url> ‐‐kerberos‐login‐context=DatabaseKerberos
‐Coracle.net.authentication_services=(KERBEROS5)
Replace <database url> with the JDBC connection URL. When using a JAAS applica-tion configuraapplica-tion for username and password, make sure to also specify the ‐user‐
name and ‐password arguments.
Example: A JDBC URL
jdbc:oracle:thin:@oden.engr‐ad.spotfire.com:1521:orcl Microsoft SQL Server
To bootstrap the Spotfire Server, execute the bootstrap command:
> config bootstrap ‐‐test ‐‐driver‐class=com.microsoft.sqlserver.jdbc.SQLServerDriver
‐‐database‐url=<database url> ‐‐kerberos‐login‐context=DatabaseKerberos
Replace <database url> with the JDBC connection URL. This URL must include ;inte‐
gratedSecurity=true;authenticationScheme=JavaKerberos options. When using a JAAS application configuration for username and password, make sure to also specify the -username and -password arguments.
Example: A JDBC URL
jdbc:sqlserver://db.research.example.com:1433;DatabaseName=
spotfire_server450;integratedSecurity=true;authenticationScheme=JavaKerberos
Note: It makes no sense to configure a configuration tool password for the boot‐
strap.xml file when using a connection pool that logs in to Kerberos using a keytab file or retrieving the Ticket-Granting Ticket (TGT) from the native ticket cache. However, it does have a function in the scenario with a connection pool that logs in to Kerberos using a username and password.