Enabling Integrated Authentication for J2EE-Compliant Application Servers

If you use a J2EE-compliant application server to deploy MicroStrategy Web, MicroStrategy Library, MicroStrategy Mobile Server, or to deploy MicroStrategy Web Services to support MicroStrategy Office, you can support integrated authentication. If you are configuring integrated authentication on your MicroStrategy Library server you do not need to perform the steps regarding generation and configuration of .jaas files.

Create a Service Principal Name for Your Application Server

You must create a Service Principal Name (SPN) for your J2EE application server, and map it to the domain user that the application server runs as. The SPN identifies your application server as a service that uses Kerberos. For instructions on creating an SPN, see Active Directory Account Configuration.

The SPN should be in the following format:

HTTP/ASMachineName

The format is described below:

• HTTP: This is the service class for the application server.
• ASMachineName: This is the fully qualified host name of the server where the application server is running. It is of the form machine-name.example.com. Integrated authentication will only function when accessing the application server using the ASMachineName used to register the SPN. If the fully qualified host name was registered as SPN, then using the machine name or IP address will not work. Should the application server be accessible through FQDN and machine name, additional SPNs will need to be registered to the AD service account.

In your Active Directory, configure the application server’s domain user to be trusted for delegation, and map the user to this SPN. For example, if you register the SPN to the Active Directory user j2ee-http, enable the Account is trusted for delegation option for the user. Also, enable the Trust this computer for delegation to any service (Kerberos only) option for the machine where your application server is hosted.

Configure the krb5.keytab File for the Application Server

You must create and configure a krb5.keytab file for the application server. In UNIX, you must use the kutil utility to create this file. In Windows, you must use the ktpass utility to create the keytab file.

Configure the krb5.conf File for the Application Server

You must create and configure a file named krb5.conf.

For Linux only: If your application server and Intelligence server are hosted on the same machine, it is required that you use a separate configuration file. For example, if you created krb5.conf for the Intelligence server, use krb5-http.conf for the application server.

If you have created a different keytab file in Enabling Integrated Authentication for J2EE-Compliant Application Servers, replace krb5.keytab below with your own keytab file.

The contents of the krb5.conf should be as shown below:

[libdefaults]
default_realm = DOMAIN_REALM
default_keytab_name = Keytab_Path
forwardable = true
no_addresses = true

[realms]
DOMAIN_REALM = {
    kdc = DC_Address:88
    admin_server = DC_Admin_Address:749
}

[domain_realm]
.domain.com = DOMAIN_REALM
domain.com = DOMAIN_REALM
.subdomain.domain.com = DOMAIN_REALM
subdomain.domain.com = DOMAIN_REALM

The variables in the syntax above are described below:

• DOMAIN_REALM: The domain realm used for authentication purposes. A domain realm is commonly of the form EXAMPLE.COM, and must be entered in uppercase.
• Keytab_Path: The location of your krb5.keytab file. In Linux, it is of the form /etc/krb5/krb5.keytab. In Windows, it is of the form C:\temp\krb5.keytab.
• domain.com and subdomain.domain.com: Use these for all domains and subdomains where users must be authenticated using the default Kerberos realm.
• DC_Address: The host name or IP address of the Windows machine that hosts your Active Directory domain controller. This can be the same address as DC_Admin_Address.
• DC_Admin_Address: The host name or IP address of the Windows machine that hosts your Active Directory domain controller administration server. This can be the same address as DC_Address.

Configure the jaas.conf File for the Application Server

You must configure the Java Authentication and Authorization Service (JAAS) configuration file for your application server.

This step is not required for MicroStrategy Library server.

Depending on the version of the Java Development Kit (JDK) used by your application server, the format of the jaas.conf file varies slightly. Refer to your JDK documentation for the appropriate format. Sample jaas.conf files for the Sun and IBM JDKs follow. The following variables are entered in the .accept section of the jaas.conf file.:

• ASMachineName: The name of the machine that the application server is installed on.
• DOMAIN_REALM: The domain realm used for authentication purposes. It is of the form EXAMPLE.COM, and must be entered in uppercase.

com.sun.security.jgss.krb5.accept {
    com.sun.security.auth.module.Krb5LoginModule required
    principal="ASUser@DOMAIN_REALM"
    useKeyTab=true
    doNotPrompt=true
    storeKey=true
    debug=true;
};

com.ibm.security.jgss.initiate {
    com.ibm.security.auth.module.Krb5LoginModule required
    useDefaultKeytab=true
    principal="ASUser@DOMAIN_REALM"
    credsType=both
    debug=true
    storeKey=true;
};

Save the jaas.conf file to the same location as your krb5.conf file.

Configure the JVM Startup Parameters

This step is not required for MicroStrategy Library server.

For your J2EE-compliant application server, you must set the appropriate JVM startup parameters. The variables used are described below:

• JAAS_Path: The path to the jaas.conf file. In Linux, it is of the form /etc/krb5/jaas.conf. In Windows, it is of the form C:\temp\jaas.conf.
• KRB5_Path: The path to the krb5.conf file. In Linux, it is of the form /etc/krb5/krb5.conf. In Windows, it is of the form C:\temp\krb5.conf.

You must modify the JVM startup parameters listed below:

-Djava.security.auth.login.config=JAAS_Path
-Djava.security.krb5.conf=KRB5_Path
-Djavax.security.auth.useSubjectCredsOnly=false

Enable the SPNEGO Mechanism

This step is not required for MicroStrategy Library server.

As part of a MicroStrategy Web or Mobile Server JSP deployment, you must modify the web.xml file for MicroStrategy Web or Mobile, to enable the Simple and Protected GSSAPI Negotiation Mechanism (SPNEGO). This is accomplished by removing the comments around the following information in the web.xml file:

For MicroStrategy Web:

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

For MicroStrategy Mobile Server:

<filter>
    <display-name>SpnegoFilter</display-name>
    <filter-name>SpnegoFilter</filter-name>
    <filter-class>com.microstrategy.mobile.filter.SpnegoFilter</filter-class>
</filter>
<filter-mapping>
    <filter-name>SpnegoFilter</filter-name>
    <servlet-name>mstrMobileAdmin</servlet-name>
</filter-mapping>

Restart your application server for all of the above settings to take effect.

How to Enable Integrated Authentication for the Library Server

1. Launch the Library Admin page by entering the following URL in your web browser

   http://<FQDN>:<port>/MicroStrategyLibrary/admin

   where <FQDN> is the Fully Qualified Domain Name of the machine hosting your MicroStrategy Library application and <port> is the assigned port number.

2. On the Library Web Server tab, select Integrated from the list of available Authentication Modes.
3. Click Save.
4. Restart your Web Server to apply the change.

Restart your application server for all the above settings to take effect.