KB279117: How to set up Kerberos Integrated Authentication for JBoss EAP 6.x

Jboss EAP 6.x / AS 7.x require specific steps to enable Kerberos Integrated Authentication which differ from general J2EE Web Server configuration. This technical note describes how to set up Kerberos Integrated Authentication with Jboss EAP 6.x / AS 7.x to allow users authenticating against Strategy Web 10 and above.
 
Prerequisites:
Due to JBoss 6.x specific Kerberos integrated authentication configuration, this technical note complements steps and prerequisites outlined in KB33276: How to set up Integrated Authentication in Tomcat running on Linux and having MicroStrategy Web Universal 9.0.1 to 9.2.1 . 
 
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, ie. Jboss. This technical note is meant as a guide only and does not imply that Strategy Technical Support is an expert on integrating Kerberos with Jboss Application Server.
Note: The steps below outline a basic working environment to authenticate specified users against Strategy Web. For advanced user <> role mapping configuration, refer to Red Hat JBoss 6 documentation or contact Red Hat support for assistance.
 
First steps:
Create krb5.conf and krb5.keytab files as per KB33276: How to set up Integrated Authentication in Tomcat running on Linux and having MicroStrategy Web Universal 9.0.1 to 9.2.1  (Section 1.1 and 1.4)
Configuring Strategy.war file for JBoss Kerberos authentication:

1. Add a file named jboss-deployment-structure.xml to Strategy.war\META-INF\, with the following file content:
   

   
   <jboss-deployment-structure>
           <deployment>
                  <dependencies>
                          <module name="org.jboss.security.negotiation" />
                  </dependencies>
           </deployment>
   </jboss-deployment-structure>

   
   
2. Add a file named jboss-web.xml to Strategy.war\WEB-INF\, with the following file content:
   

   
   <jboss-web>
           <security-domain>SPNEGO</security-domain>
           <valve>
                  <class-name>org.jboss.security.negotiation.NegotiationAuthenticator</class-name>
           </valve>
   </jboss-web>

   
   
3. Configure Strategy.war\WEB-INF\web.xml to enable SPNEGO authenticaton. Replace the SPNEGO filter with SpnegoJbossfilter as below:
   

   
   <filter>      
       <display-name>SpnegoJbossFilter</display-name>
       <filter-name>SpnegoJbossFilter</filter-name>
       <filter-class>com.Strategy.web.filter.SpnegoJbossFilter</filter-class> 
   </filter>
   <filter-mapping>
       <filter-name>SpnegoJbossFilter</filter-name>
   <servlet-name>mstrWeb</servlet-name>
   <servlet-name>MobileServlet</servlet-name>       
       <servlet-name>TaskProcessorServlet</servlet-name>
   </filter-mapping>  

   
   
4. Declare a new security role user in Strategy.war\WEB-INF\web.xml. The security role value should be consistent with the role assignment in JBOSS, note that the syntax is case sensitive.
    
   

   
   <security-role>
       <role-name>user</role-name>
   </security-role>

   
   
5. In Strategy.war\WEB-INF\web.xml define a security constraint to authorize user roles to access Strategy Web. Both admin and user roles can access Strategy Web and only users with the "admin" role can access to Strategy Web Administrator.

6. 
   <security-constraint>
       <web-resource-collection>
           <web-resource-name>Web</web-resource-name>
           <url-pattern>/servlet/mstrWeb</url-pattern>
           <url-pattern>/servlet/mstrWeb/*</url-pattern>
       </web-resource-collection>
       <auth-constraint>
           <role-name>admin</role-name>
           <role-name>user</role-name>
       </auth-constraint>
   </security-constraint>

   
   At this point, Strategy.war archive structure should contain the following files:

Strategy.war
        +----- META-INF
        |         +----- jboss-deployment-structure.xml
        |         +----- MANIFEST.MF
        |
        +----- WEB-INF
                  +----- jboss-web.xml
                  +----- web.xml

 
JBoss EAP / AS configuration for Kerberos authentication

1.  Add Kerberos related system properties to $JBOSS_HOME/standalone/configuration/standalone.xml. Ensure to specify the correct path to krb5.conf
   

   
   <system-properties>
           <property name="java.security.krb5.conf" value="/path/to/krb5.conf"/>
           <property name="jboss.security.disable.secdomain.option" value="true"/>
           <property name="javax.security.auth.useSubjectCredsOnly" value="false"/>
       </system-properties>

   
   
2. Add SPNEGO security domain to use the SPNEGOLoginModule JAAS login module and map the user to role. Please note that the role value is case sensitive and should correspond to the role assigned in web.xml. The SPNEGO security domain references the host security domain which is used for JBoss AS server authentication in Kerberos.
   

   
                   <security-domain name="SPNEGO" cache-type="default">
                       <authentication>
                           <login-module code="SPNEGO" flag="required">
                               <module-option name="password-stacking" value="useFirstPass"/>
                               <module-option name="serverSecurityDomain" value="host"/>
                           </login-module>
                       </authentication>
                       <mapping>
                           <mapping-module code="SimpleRoles" type="role">
                               <module-option name="mstradmin@TECHSUPP.Strategy.COM" value="admin"/>
                               <module-option name="user1@TECHSUPP.Strategy.COM" value="user"/>
                               <module-option name="user2@TECHSUPP.Strategy.COM" value="user"/>
                           </mapping-module>
                       </mapping>
                   </security-domain>
   

   
   An alternative approach is to use the following UsersRoles login module in order to specify users and roles in files:
   

   
   <security-domain name="SPNEGO" cache-type="default">
   	<authentication>
   		<login-module code="SPNEGO" flag="required">
   			<module-option name="password-stacking" value="useFirstPass"/>
   			<module-option name="serverSecurityDomain" value="host"/>
   		</login-module>
   		<login-module code="UsersRoles" flag="required">
   			<module-option name="password-stacking" value="useFirstPass" />
   			<module-option name="usersProperties" value="/path/to/spnego-users.properties" />
   			<module-option name="rolesProperties" value="/path/to/spnego-roles.properties" />
   		</login-module>
   	</authentication>
   </security-domain>
   

   
   Create the following two files under $JBOSS/standalone/configuration:
   - spnego-roles.properties
   - spnego-users.properties
   
   Add users and roles to spnego-roles.properties as follows:
   

   
   mstradmin@TECHSUPP.Strategy.COM=admin
   user1@TECHSUPP.Strategy.COM=user
   user2@TECHSUPP.Strategy.COM=user
   

   
   spnego-users.properties is required but remains empty.
   
   Note: For advanced user role mapping (e.g. through LDAP or MS Active Directory), refer to JBoss documentation or contact JBoss support for assistance.
    
3. Add host security domain to use Krb5LoginModule login module.
   

   
   <security-domain name="host" cache-type="default">
                       <authentication>
                           <login-module code="Kerberos" flag="required">
                               <module-option name="debug" value="true"/>
                               <module-option name="useKeyTab" value="true"/>
                               <module-option name="keyTab" value="/path/to/krb5.keytab"/>
                               <module-option name="storeKey" value="true"/>
                               <module-option name="refreshKrb5Config" value="true"/>
                               <module-option name="doNotPrompt" value="true"/>
                               <module-option name="principal" value="SERVICE PRINCIPAL NAME"/>
                           </login-module>
                       </authentication>
                   </security-domain>
   

   
   

Final steps:

1. Add Strategy Intelligence Server using its Service Principal Name to the Strategy Web Administrator page.
2. Select Integrated Authentication as an available login mode in the Strategy Web Admin page > Default Properties > Login
3. Ensure the browser is enabled for Integrated authentication as per KB33291: How to configure Internet Explorer, Firefox, and Chrome for Integrated Authentication with Kerberos for MicroStrategy Web 9.x.

 
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.
KB279117