KB19110: How to configure MicroStrategy Intelligence Server for Integrated Authentication (Kerberos) on Unix / Linux

• Strategy

This article contains detailed steps for configuring Integrated Authentication (Kerberos) to MicroStrategy Intelligence Server 9.x and newer running on Unix / Linux, including check points and troubleshooting.

Introduction
Integrated Authentication to the Strategy Intelligence Server utilizes the Kerberos authentication protocol to provide a Single Sign-On capability for Strategy users connecting from Web or Developer from a Microsoft Active Directory environment. Several configuration steps are required inside Active Directory as well as on the Strategy Intelligence Server host machine and via Strategy Developer on a Windows machine.

Active Directory configuration

Prerequisites
Create the Intelligence Server SPN
Enable delegation for the Intelligence Server service (optional)

Intelligence Server machine configuration

Prerequisites
Check Point 1 - kinit as AD user
Check Point 2 - Get a ticket
Create the Intelligence Server service keytab
Store the configuration files
Set up the environment variables
Check Point 3 - Check the environment variables

Developer machine configuration

Prerequisites
Configure a test user
Configure the project source
Check Point 4 - Connect in Developer

Active Directory configuration:

Prerequisites:

A service account should exist that will be associated with the Intelligence Server SPN (Service Principal Name). In this article, an account named mstr-example will be used as an example.

Create the Intelligence Server SPN:
Once the user has been created, an SPN (Service Principal Name) for the Intelligence Server must be attached to the user using the setspn command. Typically the Active Directory administrator will perform this step. Prior to adding the SPN, use the setspn -L <user> command to verify that no Strategy-related SPNs already exist for the user. When adding the SPN, use the setspn -S <SPN> <user> command. The general format for an SPN is <servicename>/<hostname>@<realm>. For the Intelligence Server SPN, Strategy software expects that the service name will be MSTRSVRSvc, and that the Intelligence Server port number will be added to the end of the hostname. So, the format will be MSTRSVRSvc/<hostname>:<port>@<realm>. When running the setspn command, the realm does not need to be specified as it will automatically use the default realm of the Active Directory machine where the command is being run.


C:\Windows\system32>
C:\Windows\system32>setspn -L mstr-example
Registered ServicePrincipalNames for CN=mstr-example,CN=Users,DC=example,DC=com:

C:\Windows\system32>
C:\Windows\system32>setspn -S MSTRSVRSvc/exampleserver.example.com:34952 mstr-example
Registering ServicePrincipalNames for CN=mstr-example,CN=Users,DC=example,DC=com
        MSTRSVRSvc/exampleserver.example.com:34952
Updated object

If any errors occurred when running the setspn command, stop here and consult the Active Directory administrator to resolve the error before continuing.
Enable delegation for the Intelligence Server service (optional step if warehouse pass-through / single sign-on to warehouse database will be used):
If single-sign on authentication to a warehouse database is required, an additional configuration step must be performed on the Active Directory machine. Kerberos delegation will be required for the Intelligence Server to authenticate the end user to the database server. After creating the SPN, edit the associated user and select the Trust this user for delegation to any service (Kerberos only) option on the Delegation tab:

NOTE: Beginning in Strategy version 10.11, the Trust this user for delegation to specified services only option (also known as Constrained Delegation) may be used. See KB440503: New in MicroStrategy 10.11: Kerberos Constrained Delegation for more information on how to configure this option.
This concludes the configuration required on the Active Directory.

Strategy Intelligence Server host machine configuration:

Prerequisites:

Kerberos libraries must be installed in order to configure Integrated Authentication. In most cases, these libraries will be pre-installed by the operating system. If the libraries are not installed already, users should refer to Kerberos documentation for their operating system for details on how to do so.
A krb5.conf file is required by the Kerberos libraries to contain the Kerberos environment configuration information. By default, this configuration file will typically be located at /etc/krb5.conf, but it is possible if desired to create a separate file which will be used only by the Intelligence Server rather than using the default system copy (the location of this file will be indicated to the Intelligence Server using an environment variable KRB5_CONFIG). The content of the krb5.conf file should be populated by the system administrator as it will be dependent on the Kerberos environment. An example krb5.conf containing the minimum configuration required by the Intelligence Server is below:


[libdefaults]
 default_realm = EXAMPLE.COM
 forwardable = true

[realms]
 EXAMPLE.COM = {
  kdc = kdc.example.com
  admin_server = kdc.example.com
 }

[domain_realm]
 .example.com = EXAMPLE.COM
 example.com = EXAMPLE.COM

In this example, EXAMPLE.COM should be replaced with the actual Kerberos realm to use, and kdc.example.com in the [realms] section should be replaced with the actual hostnames of the KDC and Admin server for the Kerberos realm. example.com and .example.com should be replaced with the actual domain names that correspond to the Kerberos realm. Although this example is provided for reference, the correct values for these parameters in an actual environment are entirely environment dependent and Strategy Support will be unable to assist with setup of the krb5.conf file.
Once the krb5.conf file has been successfully configured, it should be possible to authenticate into the Kerberos environment using the kinit <principal> command.

CHECK POINT 1 - kinit as AD user:

Verify that it is possible to kinit with the principal for the Intelligence Server's service account in Active Directory. After running the kinit command and entering the password for the Active directory user, run the klist command to verify that a ticket was created for the krbtgt service (this is actually the ticket that entitles the user to get other tickets in the realm after authenticating).


[mstr@exampleserver Strategy]# kinit mstr-example
Password for mstr-example@EXAMPLE.COM:
[mstr@exampleserver Strategy]#
[mstr@exampleserver Strategy]# klist
Ticket cache: FILE:/tmp/krb5cc_0
Default principal: mstr-example@EXAMPLE.COM

Valid starting     Expires            Service principal
07/13/17 11:09:42  07/13/17 21:09:54  krbtgt/EXAMPLE.COM@EXAMPLE.COM
        renew until 07/20/17 11:09:42
[mstr@exampleserver Strategy]#

If an error occurred when running either the kinit or klist commands, this means that the krb5.conf configuration or some other system-level configuration (network, etc.) is incorrect. Stop here and consult the system administrator or Kerberos administrator to resolve this issue before continuing.

CHECK POINT 2 - Get a ticket:

Verify that it is possible to manually obtain a ticket for the Intelligence Server SPN. Assuming that the mstr-example user is still authenticated on the Intelligence Server machine, use the kvno <SPN> command to obtain a ticket. After running the kvno command, run the klist command to verify that a ticket was created. This ticket should match the SPN that was configured for the Intelligence Server service on Active Directory. Make a note of the key version number returned (in this case kvno = 2) and the ticket cache location (in this case /tmp/krb5cc_0) as these will be needed for a later configuration step.


[mstr@exampleserver Strategy]#
[mstr@exampleserver Strategy]# kvno MSTRSVRSvc/exampleserver.example.com:34952@EXAMPLE.COM
MSTRSVRSvc/exampleserver.example.com:34952@EXAMPLE.COM: kvno = 2
[mstr@exampleserver Strategy]#
[mstr@exampleserver Strategy]# klist
Ticket cache: FILE:/tmp/krb5cc_0
Default principal: mstr-example@EXAMPLE.COM

Valid starting     Expires            Service principal
07/13/17 11:09:42  07/13/17 21:09:54  krbtgt/EXAMPLE.COM@EXAMPLE.COM
        renew until 07/20/17 11:09:42
07/13/17 12:40:57  07/13/17 21:09:54  MSTRSVRSvc/exampleserver.example.com:34952@EXAMPLE.COM
        renew until 07/20/17 11:09:42
[mstr@exampleserver Strategy]#

If an error occurred when running the kvno command, this means that the Intelligence Server SPN was not created correctly in the Active Directory (or was not correctly specified in the command). Stop here and consult the Active Directory administrator or Kerberos administrator to resolve this issue before continuing.
Create the Intelligence Server keytab file:
Use the ktutil command to enter the keytab utility. From inside the utility, use the addent command to add the MSTRSVRSvc principal, and then use the wkt command to write the keytab file.


[mstr@exampleserver Strategy]#
[mstr@exampleserver Strategy]# ktutil
ktutil:  addent -password -p MSTRSVRSvc/exampleserver.example.com:34952@EXAMPLE.COM -k 2 -e arcfour-hmac
Password for MSTRSVRSvc/exampleserver.example.com:34952@EXAMPLE.COM:
ktutil:  wkt MSTRSVRSvc.keytab
ktutil:  quit
[mstr@exampleserver Strategy]#

The syntax for the addent command is as follows: addent -password -p <principal> -k <key version> -e <encryption type>. In this case, the principal is the Intelligence Server SPN, the key version was noted above in Check Point 2 (kvno = 2) and the encryption type depends on the Kerberos environment. For maximum compatibility, Strategy recommends using arcfour-hmac, but check with the Kerberos and / or Active Directory administrators to see if the environment has other requirements.
Store the created files in a dedicated location:
At this point a krb5.conf, a MSTRSVRSvc.keytab, and a credentials cache file (in the above example, /tmp/krb5cc_0) have been created. These files need to be placed in a dedicated location where the Intelligence Server can always access them. It might be desired to create a krb5 subdirectory in the Strategy home folder to store these in, or something similar.
Set up the environment variables for the Intelligence Server to access the configuration files:
The Intelligence Server will check three Kerberos-related environment variables at startup time and use the files that are defined in them (if they exist):
KRB5_CONFIG (the krb5.conf configuration file)
KRB5_KTNAME (the Intelligence Server keytab file)
KRB5CCNAME (a Kerberos credentials cache file. If this variable is not set, the default location will be used for the cache, typically /tmp/krb5cc_<UID>)
The variables must be set when the Intelligence Server starts in order to take effect. In order to accomplish this, they can be manually set in the terminal where the Intelligence Server is started, or the system administrator could add them to the service account's user profile, or they could be added to Strategy's env/Principal.sh or env/Kerberos.sh scripts. The Kerberos.sh script is designed explicitly for this purpose but some additional modifications will be required (contact Technical Support for assistance).
For the purpose of this knowledge base article, assume that the variables will be defined in the terminal window prior to starting the Intelligence Server process. Assuming that a krb5 subdirectory was made in the Strategy home folder to store the files, set the variables using the export command. Make adjustments for the actual path or file names as necessary.


export KRB5_CONFIG=/var/opt/Strategy/krb5/krb5.conf
export KRB5_KTNAME=/var/opt/Strategy/krb5/MSTRSVRSvc.keytab
export KRB5CCNAME=/var/opt/Strategy/krb5/krb5cc_0

Then, start (or restart) the Intelligence Server.

CHECK POINT 3 - Check the environment variables:

After the Intelligence Server startup has completed, check to make sure the environment variables were correctly set up. Find the process ID for the Intelligence Server process using ps -ef | grep MSTRSvr:


[mstr@exampleserver Strategy]# ps -ef | grep MSTRSvr
mstr     11592     1  0 12:10 ?        08:30:24 /opt/Strategy/IntelligenceServer/bin/MSTRSvr -w /var/opt/Strategy/IntelligenceServer -t status-iserver.xml /opt/Strategy/lib/libMSTRSvr2.so -n CastorServer
[mstr@exampleserver Strategy]#

Use the strings -a /proc/<PID>/environ | grep KRB command to find the Kerberos related environment variables that are defined on the Intelligence Server process:


[mstr@exampleserver Strategy]# strings -a /proc/31239/environ | grep KRB
KRB5_CONFIG=/var/opt/Strategy/krb5/krb5.conf
KRB5_KTNAME=/var/opt/Strategy/krb5/MSTRSVRSvc.keytab
KRB5CCNAME=/var/opt/Strategy/krb5/krb5cc_0
[mstr@exampleserver Strategy]#

If the environment variables are not found by this command, stop here and consult the system administrator to ensure that the environment variables have been defined for the Intelligence Server process through some method.
This concludes the configuration on the Intelligence Server machine.

Final configuration steps in Strategy Developer:

Prerequisites:

A Windows machine connected to the Active Directory environment, with a user logged in who will have access to connect to Strategy

Configure the Kerberos user principal for a test user:
When authenticating to Strategy using Integrated Authentication, the user who is logged into Windows will be logged into Strategy. In order to establish the link between the Windows user / Kerberos user principal and the Strategy user, the Trusted Authentication Request User ID field must be populated on the Strategy user object using Developer. The contents of this field should be the Kerberos user principal for the desired Active Directory user. If this value is not known, consult the Active Directory administrator to obtain it. It is also possible to obtain this value for the user currently logged in to Windows by running klist in a command prompt window on the Windows machine and checking the client value.


Microsoft Windows [Version 10.0.14393]
(c) 2016 Microsoft Corporation. All rights reserved.

C:\Users\kerberosuser>klist

Current LogonId is 0:0x681ec

Cached Tickets: (1)

#0>     Client: kerberosuser @ EXAMPLE.COM
        Server: krbtgt/EXAMPLE.COM @ EXAMPLE.COM
        KerbTicket Encryption Type: AES-256-CTS-HMAC-SHA1-96
        Ticket Flags 0x40e00000 -> forwardable renewable initial pre_authent
        Start Time: 7/14/2017 8:11:37 (local)
        End Time:   7/14/2017 18:11:37 (local)
        Renew Time: 7/21/2017 8:11:37 (local)
        Session Key Type: AES-256-CTS-HMAC-SHA1-96
        Cache Flags: 0x1 -> PRIMARY
        Kdc Called: kdc.example.com

Configure the Project Source to connect to the Intelligence Server using Integrated Authentication:
In Developer, modify the relevant Project Source (or create a new one). Add the Intelligence Server hostname in the Server name field.
IMPORTANT: The hostname must match exactly the hostname that is specified in the Intelligence Server SPN. If the SPN uses the Fully Qualified Domain Name (FQDN), then the Project Source must also use the FQDN. If the SPN uses the short name, then the Project Source must also use the short name.
Add the Intelligence Server port number in the Port number field.
IMPORTANT: The port number must match exactly the port number that is specified in the Intelligence Server SPN.

When generating the Kerberos ticket request for connecting to the Intelligence Server service, Strategy Developer will format the SPN as MSTRSVRSvc/<contents of Server name field>:<contents of port number field>@<default kerberos realm for the Developer machine>, so it is required that these fields all match the SPN as defined in Active Directory.
Finally, set the Project Source to use Integrated Authentication.

This concludes the configuration in Strategy Developer.

CHECK POINT 4 - Connect in Developer:

Attempt to connect to the Intelligence Server with the Integrated Authentication project source. If the connection is successful, everything has been successfully configured. If the connection is not successful and a Login failure error appears, open a command prompt on the Windows machine and run the command klist to see what tickets have been cached locally. There will likely be several non-Strategy related tickets; check to see if a ticket for the Intelligence Server service was generated.
If the ticket was generated but login failed then there may be an encryption type mismatch. Check the listed encryption type in the klist output in Windows and see if it matches the encryption type that was set in the Intelligence Server keytab file. If these do not match then the correct encryption type will need to be added to the keytab file.
If the ticket was not generated and the other Check Point tests were all successful, the problem is either with the Kerberos configuration on the Windows machine or the project source fields were not filled out correctly. Double check the project source fields to ensure they match the values in the Intelligence Server SPN. Depending on the Windows version, the klist command may allow manual ticket generation using the syntax klist get <SPN>. If this manual ticket generation also fails, consult the Windows administrator to solve the Kerberos configuration issue on the Windows machine.

Comment

0 comments

Details

Knowledge Article

Published:

March 30, 2017

Last Updated:

February 26, 2024