KB33276: How to set up Kerberos authentication in Tomcat 9.x for MicroStrategy Web.

PREREQUISITES

1. Before completing the steps in this technical note, make sure that the Strategy Intelligence Server is configured correctly to use Integrated Authentication using technical note KB19110 .
   
   Note: The MicroStrategy Product Manuals - System Administration Guide  (PDF) - Chapter 3 IDENTIFYING USERS: AUTHENTICATION - Enabling single sign-on authentication - Enabling integrated authentication contains all the information necessary to implement integrated authentication in the context of Strategy.

1. Create a user for the Strategy Web Server service following technical note KB33289.

Warning: The integration of Kerberos is done at the server level. When configuring Strategy Developer for Kerberos the server that integrates with Kerberos is the Strategy Intelligence server. However, when configuring Strategy Web, the integration with Kerberos, at the server level, is with the 3rd party application server, eg. Tomcat, Websphere, Weblogic. This technical note is meant as a guide only and does not imply that Strategy Technical Support is an expert on integrating Kerberos with 3rd party tools.
 

INTRODUCTION

This technical note contains the following sections:

1. Configuring the Web Application Server (3rd party software)
   
1. Create krb5.conf
2. Create jaas.conf
3. JVM startup arguments
4. Generate krb5.keytab
2. Configuring the Strategy Web Universal application
   
1. Enable the spnego filter
2. Select Integrated Authentication

ACTION

1. Configuring the Web Application Server (3rd party software)
   To enable integrated authentication in the third party application server, perform the following configurations:

1. Create the krb5.conf file

The krb5.conf or Kerberos configuration file, is a text file which controls the Kerberos configuration. It can be manually created anywhere in the system, although for ease of maintenance all configuration files should be created under the same folder.
 
By default, the contents of the krb5.conf are the following:

[logging]
default = /var/log/krb5libs.log
kdc = /var/log/krb5kdc.log
admin_server = /var/log/kadmind.log

[libdefaults]
default_realm = DOMAIN.REALM.COM
default_keytab_name = /opt/kerberos/default_keytab_name.keytab
default_tkt_enctypes = aes256-cts arcfour-hmac-md5 aes128-cts rc4-hmac des3-cbc-sha1 des-cbc-md5 des-cbc-crc arcfour-hmac
default_tgs_enctypes = aes256-cts arcfour-hmac-md5 aes128-cts rc4-hmac des3-cbc-sha1 des-cbc-md5 des-cbc-crc arcfour-hmac
forwardable  = true
no_addresses = true

[realms]
DOMAIN.REALM.COM = {
   kdc = domain.realm.com:88
   admin_server = domain.realm.com:749
}

[domain_realm]
.domain.realm.com = DOMAIN.REALM.COM
domain.realm.com = DOMAIN.REALM.COM

com.sun.security.jgss.krb5.accept {
        com.sun.security.auth.module.Krb5LoginModule required
        principal="user_principal_name@DOMAIN.REALM.COM"
        useKeyTab=true
        keyTab="/path/to/keytab/default_keytab_name.keytab"
        doNotPrompt=true
        storeKey=true
        debug=true;
};

com.ibm.security.jgss.krb5.initiate{
              com.ibm.security.auth.module.Krb5LoginModule required
              principal="user_principal_name@DOMAIN.REALM.COM"
              useDefaultKeyTab=true
              storeKey=true
              credsType=acceptor
              forwardable=true
              debug=true;
};

1. JVM startup arguments
   For J2EE compliant application servers, add the following JVM startup arguments:
   

   
   -Djava.security.auth.login.config

   
   Include the absolute path to the jaas.conf file
   

   
   -Djava.security.krb5.conf 

   
   Include the absolute path to the krb5.conf file
   

   
   -Djavax.security.auth.useSubjectCredsOnly 

   
   Define this parameter as false.

 
As an example, this can be set in a separate setenv.sh/setenv.bat file saving it to the bin folder of the tomcat installation. When installed on Linux OS, example of entry:

export JAVA_OPTS="$JAVA_OPTS -Djava.security.auth.login.config=/opt/kerberos/jaas.conf -Djava.security.krb5.conf=/opt/kerberos/krb5.conf -Djavax.security.auth.useSubjectCredsOnly=false"

set JAVA_OPTS=-Djava.security.auth.login.config=/opt/kerberos/jaas.conf -Djava.security.krb5.conf=/opt/kerberos/krb5.conf -Djavax.security.auth.useSubjectCredsOnly=false

1. Generate the keytab

Follow the steps outlined in https://kb.iu.edu/d/aumh to create the keytab. Note that the UPN, not the SPN, should be specified as "username" in the command below:
 

addent -password -p username@ADS.IU.EDU -k 1 -e rc4-hmac

ktpass -out krb5.keytab -princ UPN@DOMAIN -pass <password for UPN> -kvno 2 -ptype KRB5_NT_PRINCIPAL -crypto All

Further, please then adjust krb5.conf and jaas.conf with the correct location and name of the generated keytab file.
 

1. Configuring Strategy Web Universal Application - There are only two steps to configure the Strategy Web application to integrate with Kerberos.

1.  Enable the spnego filter.

After deploying the Strategy Web Universal WAR file, the web.xml file must be modified to support integrated authentication. Locate the file at:

/%tomcat_home%/webapps/MicroStrategy/WEB-INF/web.xml

<filter>
	<display-name>SpnegoFilter</display-name>
       	<filter-name>SpnegoFilter</filter-name>
       	<filter-class>com.Strategy.web.filter.SpnegoFilter</filter-class>
</filter>
<filter-mapping>
       	<filter-name>SpnegoFilter</filter-name>
       	<servlet-name>mstrWeb</servlet-name>
</filter-mapping>

• Select Integrated Authentication.
  For Strategy Web users log in using Kerberos, select Integrated Authentication as an available login mode in the Strategy Web Admin page > Default Properties > Login, as shown below:
  
  

• Click save at the bottom of the page. 

After successfully configuring Strategy Web and Kerberos, users will be able to log in to Strategy Web using Integrated Authentication either by clicking on the "Integrated Authentication" link or automatically, if Integrated Authentication was set as the default authentication method. 
Third Party Software Installation WARNING:
The third-party product(s) discussed in this technical note is manufactured by vendors independent of Strategy. Strategy makes no warranty, express, implied or otherwise, regarding this product, including its performance or reliability.