MicroStrategy ONE
Enabling Integrated Authentication
Integrated authentication enables a Windows user to log in once to their Windows machine. The user does not need to log in again separately to Developer or MicroStrategy Web. This type of authentication uses Kerberos to validate a user's credentials.
In addition to authenticating users to Developer and MicroStrategy Web, integrated authentication also passes user credentials down to the database server. This allows each user's credentials to be used to return data from the database.
For single sign-on with integrated authentication to work, users must have user names and passwords that are printable, US-ASCII characters. This limitation is expected behavior in Kerberos. This limitation is important to keep in mind when creating a multilingual environment in MicroStrategy.
Required Machine Configurations for Integrated Authentication
To support this type of authentication, you must properly configure MicroStrategy, as well as some third-party tools and options. The table below lists the configurations required, and on which machine the configurations must be performed.
The third-party products discussed in the table and sections below are manufactured by vendors independent of MicroStrategy, and the information provided is subject to change. Refer to the appropriate third-party vendor documentation for details on supporting integrated authentication.
Machine |
Required Configurations |
Machine hosting the domain controller |
Configure a Windows domain controller with Microsoft Active Directory: To allow users created in a domain to use integrated authentication in MicroStrategy, you must clear the Account is sensitive and cannot be delegated authentication option for each user. For information on this configuration, see Configuring a Domain Controller and Users. If Intelligence Server is run as an application with a particular user account, you must create a user in the domain with the Account is trusted for delegation authentication option selected. This user account can then be used to run Intelligence Server as an application. For information on this configuration, see Trusting Intelligence Server for Delegation. If Intelligence Server is run as a service, define the Intelligence Server machine to be trusted for delegation. You can do this by selecting the Trust computer for delegation authentication option for the host machine. For information on this configuration, see Trusting Intelligence Server for Delegation. Define the web server for MicroStrategy Web host machine to be trusted for delegation. To do this, select the Trust computer for delegation authentication option for the host machine. For information on this configuration, see Trusting the MicroStrategy Web and Mobile Server Host for Delegation. |
Linux machine hosting Intelligence Server |
If you use Intelligence Server hosted on a Linux machine, you must install and configure Kerberos 5 on your Linux machine. For information on this configuration, see Configuring Intelligence Server on Linux for Integrated Authentication. |
Machine hosting Internet Information Services (IIS) or other MicroStrategy Web application server |
Enable integrated authentication for IIS, as described in Enabling Integrated Authentication for IIS. |
To enable single sign-on authentication to MicroStrategy Web, MicroStrategy Mobile, or MicroStrategy Web Services from a Microsoft Windows machine, you must modify a Windows registry setting ( |
|
If you use Intelligence Server or MicroStrategy Web Services hosted on a Windows machine, you must configure the krb5.ini file. For information on this configuration, see Configuring the krb5.ini File |
|
Machine hosting a J2EE-compliant application server |
If you use a J2EE-compliant application server to deploy MicroStrategy Web, MicroStrategy Mobile Server, or MicroStrategy Web Services, you must perform various configurations to enable integrated authentication, as described in Enabling Integrated Authentication for J2EE-Compliant Application Servers. If you are using integrated authentication for MicroStrategy Mobile, your J2EE-compliant application server must use JDK 1.8 or higher. |
MicroStrategy Web user's machine |
If a MicroStrategy Web user plans to use single sign-on to log in to MicroStrategy Web, the user must configure their browser to enable integrated authentication. For instructions, see Configuring a Browser for Single Sign-On to MicroStrategy Web. |
Any machine with the required software for the task |
In Developer, link a MicroStrategy user to the domain user. For information on this configuration, see Linking a Domain User to a MicroStrategy User. |
In Developer, configure a project source to use integrated authentication. For information on this configuration, see Using Integrated Authentication for a Project Source. |
|
In MicroStrategy Web Administrator, configure MicroStrategy Web to include integrated authentication as an authentication option. For information on this configuration, see Enabling Integrated Authentication Login Mode for MicroStrategy Web. |
|
In MicroStrategy Mobile Administrator, create a Mobile configuration to allow your iOS and Android users to log into MicroStrategy Mobile using integrated authentication. For steps to create a Mobile configuration, see the Mobile Server Help. |
|
In addition to authenticating users to Developer and MicroStrategy Web, integrated authentication can also be extended to pass user credentials down to the database server. To support this optional configuration, see Enabling Integrated Authentication to Data Sources. |
Linking Integrated Authentication Users to LDAP Users
When users log in to MicroStrategy using their integrated authentication credentials, their LDAP group memberships can be imported and synchronized.
By default, users' integrated authentication information is stored in the userPrincipalName
LDAP attribute. If your system stores integrated authentication information in a different LDAP attribute, you can specify the attribute when you configure the import.
The LDAP server has been configured, as described in Setting up LDAP Authentication in MicroStrategy Web, Library, and Mobile.
You have configured the settings for importing users from your LDAP directory, as described in Manage LDAP Authentication.
To Import LDAP User and Group Information for Integrated Authentication Users
- In Developer, log in to a project source. You must log in as a user with administrative privileges.
- From the Administration menu, go to Server > Configure MicroStrategy Intelligence Server > LDAP > Import and select Options.
- Select the Synchronize user/group information with LDAP during Windows authentication and import Windows link during Batch Import check box.
- Select the Batch import Integrated Authentication/Trusted Authentication unique ID check box.
- By default, users' integrated authentication IDs are stored in the
userPrincipalName
LDAP attribute. If your system stores integrated authentication information in a different LDAP attribute, click Other, and type the LDAP attribute that contains users' IDs. - Click OK.
Configuring a Domain Controller and Users
To enable users to be authenticated in MicroStrategy using their Windows login credentials, you must configure a Microsoft Active Directory domain controller to apply user authentication and delegation policies. High-level steps to configure Active Directory to work with integrated authentication in MicroStrategy are provided below. Refer to your Microsoft documentation for detailed information on configuring Active Directory.
For users to be authenticated in MicroStrategy using their Windows login, their Windows user accounts must be created in an Active Directory domain and defined to be delegated. This requires that once the account is created, you must clear the Account is sensitive and cannot be delegated account option for a user.
Trusting Intelligence Server for Delegation
For Intelligence Server to pass login credentials to enable integrated authentication in MicroStrategy, it must be trusted for delegation.
To trust Intelligence Server for delegation, you must perform the following tasks:
- You must create a Service Principal Name (SPN) for Intelligence Server, and map it to the domain user that Intelligence Server runs as. The SPN identifies Intelligence Server as a service that uses Kerberos. For instructions on creating an SPN, refer to the Kerberos documentation.
If you are running Intelligence Server as a service, the SPN should be in the following format:
CopyMSTRSVRSvc/[IS_MachineName]:[ISport]
If you are running Intelligence Server as an application, the SPN should be in the following format:
CopyMSTRSVRSvc/[IS_MachineName]:[ISport]@[DOMAIN_REALM]
The formats are explained below:
MSTRSVRSvc
: The Service Class for the Intelligence Server.This must be entered exactly as above, with matching case.
IS_MachineName
: The fully qualified host name for the machine which is running Intelligence Server.ISPort
: The port where Intelligence Server is hosted.DOMAIN_REALM
: The domain realm of the Intelligence Server, which must be entered in uppercase. It is usually of the formEXAMPLE.COM
.The domain realm is required if you are running Intelligence Server as an application. If you are running Intelligence Server as a service, the domain realm is optional.
- In your Active Directory, you must configure the Intelligence Server's domain user to be trusted for delegation, and map the user to this SPN. For example, if the Intelligence Server runs as the user
mstr-iserver
, you must enable the Account is trusted for delegation option for the user, and map the user to the SPN.
- Trust Intelligence Server for delegation. For the user account that Intelligence Server runs under, enable the Account is trusted for delegation authentication option.
If you are running Intelligence Server as a service, you must also enable the Trust this computer for delegation to any service (Kerberos only) option for the Intelligence Server machine.
- Map the Intelligence Server user account to the SPN you created above.
If you are running Intelligence Server on Linux, you must perform additional steps on the Intelligence Server machine, as described in Configuring Intelligence Server on Linux for Integrated Authentication.
Trusting the MicroStrategy Web and Mobile Server Host for Delegation
The web server hosts for MicroStrategy Web and MicroStrategy Mobile must be trusted for delegation so that it can pass login credentials to enable integrated authentication in MicroStrategy. You can configure this delegation for the MicroStrategy Web and Mobile server machines in your domain controller. You must select the Trust this computer for delegation to any service (Kerberos only) option for the MicroStrategy Web and MicroStrategy Mobile server machines.
Depending on your network, this setting may require a few minutes to take effect.
Configuring Intelligence Server on Linux for Integrated Authentication
If you use Intelligence Server hosted on a Linux machine, you must install and configure Kerberos 5 on your Linux machine. Configuring Kerberos on your Linux machine hosting Intelligence Server enables secure communications to your Windows domain controller.
The configurations listed below are required to configure Intelligence Server with your Windows domain controller and Kerberos security:
- Install Kerberos 5
- Ensure that the Environment Variables are Set
- Configure the krb5.keytab File for the Intelligence Server
- Configure the krb5.conf File for the Intelligence Server
Kerberos only supports US-ASCII characters. Do not use any special characters when installing or configuring Kerberos.
Ensure that you have created a Service Principal Name (SPN) for your Intelligence Server, and configured your domain controller to trust Intelligence Server, as described in Trusting Intelligence Server for Delegation.
Ensure that the system clock of the Intelligence Server machine is in sync with the clock on your domain controller.
Install Kerberos 5
You must have Kerberos 5 installed on your Linux machine that hosts Intelligence Server. Your Linux operating system may come with Kerberos 5 installed. If Kerberos 5 is not installed on your Linux machine, refer to the Kerberos documentation for steps to install it.
Ensure that the Environment Variables are Set
Once you have installed Kerberos 5, you must ensure that the following environment variables have been created:
Variable |
Description |
Default |
Required/Optional |
${KRB5_HOME} |
Location of all Kerberos configuration files |
/etc/krb5 |
Optional |
${KRB5_CONFIG} |
Location of the default Kerberos configuration file |
/etc/krb5/krb5.conf |
Required |
${KRB5CCNAME} |
Location of the Kerberos credential cache |
/etc/krb5/krb5_ccache |
Optional |
${KRB5_KTNAME} |
Location of the Kerberos keytab file |
/etc/krb5/krb5.keytab |
Required |
Configure the krb5.keytab File for the Intelligence Server
You must create and configure the krb5.keytab
file. The steps to configure this file on your Linux machine are provided in the procedure below.
The procedure below requires a few variables to be entered for various commands. This includes information you can gather before you begin the procedure. The required variables in the following procedure are described below:
ISMachineName
: The name of the Intelligence Server machine.
ISPort
: The port number for Intelligence Server.
KeyVersionNumber
: The key version number, retrieved as part of this procedure.
EncryptionType
: The encryption type used.
It is recommended that you use rc4-hmac
as the encryption type. Other encryption types may cause compatibility issues with the Windows Active Directory.
DOMAIN_REALM
: The domain realm for your Intelligence Server, which must be entered in uppercase.
To Create a krb5.keytab File
- Log in to your Linux machine.
-
Retrieve the key version number for your Intelligence Server service principal name, using the following command:
Copykvno MSTRSVRSvc/[ISMachineName]:[ISPort]@[DOMAIN_REALM]
The key version number is displayed on the command line.
-
In the command line, enter the following commands:
Copyktutil
addent -password -p MSTRSVRSvc/[ISMachineName]:[ISPort]@[DOMAIN_REALM] -k [KeyVersionNumber] -e [EncryptionType]
wkt /etc/krb5/krb5.keytab
exit -
To verify the keytab file, enter the following command:
Copykinit -k -t /etc/krb5/krb5.keytab MSTRSVRSvc/[ISMachineName]:[ISPort]@[DOMAIN_REALM]
The command should run without prompting you for a username and password.
Configure the krb5.conf File for the Intelligence Server
You must create and configure a file named krb5.conf
. This file is stored in the /etc/krb5/
directory by default.
If you create a krb5.conf
file in a directory other than the default, you must update the KRB5_CONFIG
environment variable with the new location. Refer to your Kerberos documentation for steps to modify the KRB5_CONFIG
environment variable.
The contents of the krb5.conf
should be as shown below:
[libdefaults]
default_realm = DOMAIN_REALM
default_keytab_name = FILE:/etc/krb5/krb5.keytab
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 formEXAMPLE.COM
, and must be entered in uppercase.domain.com
andsubdomain.domain.com
: Use this for all domains and subdomains whose 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 asDC_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 asDC_Address
.
Enabling Integrated Authentication for IIS
Integrated authentication in MicroStrategy requires communication between your Kerberos security system, IIS, and your database.
If you use a J2EE-compliant application server other than IIS to deploy MicroStrategy Web, MicroStrategy Mobile Server, or MicroStrategy Web Services, see Enabling Integrated Authentication for J2EE-Compliant Application Servers.
You must configure IIS to enable integrated authentication to:
-
The MicroStrategy virtual directory to support integrated authentication to MicroStrategy Web, or MicroStrategy Web Services to support MicroStrategy Office. The steps to perform this configuration are provided in the procedure below, which may vary depending on your version of IIS. The following URLs may provide additional information to configure IIS, depending on the version you are using.
This information applies to the legacy MicroStrategy Office add-in, the add‑in for Microsoft Office applications which is no longer actively developed.
It was substituted with a new add‑in, MicroStrategy for Office, which supports Office 365 applications. The initial version does not yet have all the functionalities of the previous add‑in.
If you are using MicroStrategy 2021 Update 2 or a later version, the legacy MicroStrategy Office add-in cannot be installed from Web.;
For more information, see the MicroStrategy for Office page in the Readme and the MicroStrategy for Office Help.
- IIS 7: https://learn.microsoft.com/en-us/previous-versions/windows/it-pro/windows-server-2008-R2-and-2008/cc754628(v=ws.10)
- IIS 6: https://learn.microsoft.com/en-us/previous-versions/windows/it-pro/windows-server-2003/cc780160(v=ws.10)
- Optionally, the data warehouse. For instructions to enable integrated authentication for the data warehouse, refer to Enabling Integrated Authentication to Data Sources.
If you are using Microsoft Analysis Services, to support report subscriptions, you must use connection mapping to pass users' credentials to Analysis Services. For steps to enable connection mapping, see Connection Maps: Standard Authentication, Connection Maps, and Partitioned Fact Tables.
To Configure IIS to Enable Integrated Authentication to the MicroStrategy Virtual Directory
- On the MicroStrategy Web server machine, access the IIS Internet Service Manager.
- Browse to and right-click the MicroStrategy virtual folder and select Properties.
- Select the Directory Security tab, and then under Anonymous access and authentication control, click Edit.
- Clear the Enable anonymous access check box.
- Select the Integrated Windows authentication check box.
- Click OK twice.
- If you want to enable integrated authentication for MicroStrategy Mobile, repeat the above procedure for the MicroStrategyMobile virtual folder.
- If you want to enable integrated authentication for MicroStrategy Web Services, repeat the above procedure for the MicroStrategyWS virtual folder.
- Restart IIS for the changes to take effect.
Creating a Service Principal Name for IIS
It is recommended that you create a Service Principal Name (SPN) for IIS, 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, refer to the Kerberos documentation.
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 formmachine-name.example.com
.
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 IIS runs as the user iis
, you must enable the Account is trusted for delegation option for the user, and map the user to the SPN. You must also enable the Trust this computer for delegation to any service (Kerberos only) option for the machine where IIS is hosted.
Enabling Session Keys for Kerberos Security
To enable single sign-on authentication to MicroStrategy Web from a Microsoft Windows machine, you must modify a Windows registry setting on the machine hosting IIS.
Modification of the allowtgtsessionkey
registry setting is required by Microsoft to work with Kerberos security. For information on the implications of modifying the registry setting and steps to modify the registry setting, see the following Microsoft documentation:
The documentation below is produced by a third-party vendor and thus is subject to change. MicroStrategy makes no guarantee on the availability or accuracy of third-party documentation.
- For Microsoft Windows 2003 http://support.microsoft.com/kb/837361
Configuring the krb5.ini File
If your Intelligence Server is hosted on a Windows machine, you must configure the krb5.ini
file. This file is included with an installation of MicroStrategy Web, and can be found in the following directory:
C:\Program Files (x86)\Common Files\MicroStrategy\
The path listed above assumes you have installed MicroStrategy in the C:\Program Files (x86)
directory.
Kerberos only supports US-ASCII characters. Do not use any special characters when installing or configuring Kerberos.
Once you locate the krb5.ini
file, open it in a text editor. The content within the file is shown below:
[libdefaults]
default_realm = <DOMAIN NAME>
default_keytab_name = <path to keytab file>
forwardable = true
no_addresses = true
[realms]
<REALM_NAME> = {
kdc = <IP address of KDC>:88
admin_server = <IP address of KDC admin>:749
}
[domain_realm]
.domain.com = <DOMAIN NAME>
domain.com = <DOMAIN NAME>
.subdomain.domain.com = <DOMAIN NAME>
subdomain.domain.com = <DOMAIN NAME>
You must configure the krb5.ini
file to support your environment by replacing the entries enclosed in <>
, which are described below:
<DOMAIN NAME>
and<REALM_NAME>
: The domain realm used for authentication purposes. A domain realm is commonly of the formEXAMPLE.COM
, and must be entered in uppercase.<IP address of KDC>
: The IP address or host name of the Windows machine that hosts your Active Directory domain controller. This can be the same address as<IP address of KDC admin>
.<IP address of KDC admin>
: 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<IP address of KDC>
.domain.com
andsubdomain.domain.com
: Use this for all domains and subdomains whose users must be authenticated using the default Kerberos realm.
Enabling Integrated Authentication for J2EE-Compliant Application Servers
If you use a J2EE-compliant application server to deploy MicroStrategy Web, MicroStrategy Mobile Server, or to deploy MicroStrategy Web Services to support MicroStrategy Office, you can support integrated authentication.
This information applies to the legacy MicroStrategy Office add-in, the add‑in for Microsoft Office applications which is no longer actively developed.
It was substituted with a new add‑in, MicroStrategy for Office, which supports Office 365 applications. The initial version does not yet have all the functionalities of the previous add‑in.
If you are using MicroStrategy 2021 Update 2 or a later version, the legacy MicroStrategy Office add-in cannot be installed from Web.;
For more information, see the MicroStrategy for Office page in the Readme and the MicroStrategy for Office Help.
To enable integrated authentication, you must set up a Service Principal Name (SPN) for the application server, and configure the Kerberos keytab and configuration files. The following is an overview of the tasks you need to perform.
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, refer to the Kerberos documentation.
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 formmachine-name.example.com
.
In your Active Directory, you must configure the application server's domain user to be trusted for delegation, and map the user to this SPN. For example, if your application server runs as the user j2ee-http
, you must enable the Account is trusted for delegation option for the user, and map the user to the SPN. You must 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.
The steps to configure this file on your Linux machine are provided in To Create a krb5.keytab File in Linux.
The steps to configure this file on a Windows machine are provided in To Create a krb5.keytab File in Windows.
The procedure below requires a few variables to be entered for various commands. This includes information you can gather before you begin the procedure. The required variables in the following procedure are described below:
ASMachineName
: The name of the machine that the application server is installed on.
KeyVersionNumber
: The key version number, retrieved as part of this procedure.
DOMAIN_REALM
: The domain realm for the application server. It is of the form EXAMPLE.COM
, and must be entered in uppercase.
EncryptionType
: The encryption type used.
It is recommended that you use rc4-hmac
as the encryption type. Other encryption types may cause compatibility issues with the Windows Active Directory.
Keytab_Path
: For J2EE application servers under Windows, this specifies the location of the krb5.keytab file. It is of the form C:\temp\example.keytab
.
ASUser
and ASUserPassword
: The user account under which the application server runs, and the password for the account.
To Create a krb5.keytab File in Linux
If your application server and Intelligence Server are hosted on the same machine, it is required that you use separate keytab and configuration files for each. For example, if you are using krb5.keytab
and krb5.conf
for the Intelligence Server, use krb5-http.keytab
and krb5-http.conf
for the application server.
- Log in to your Linux machine.
-
Retrieve the key version number for your application server service principal name, using the command shown below:
Copykvno HTTP/[ASMachineName]@[DOMAIN_REALM]
The variables are described in the prerequisites above.
The key version number is displayed on the command line.
- In the command line, type the following commands:
If your application server is installed on the same machine as the Intelligence Server, replace
krb5.keytab
below with a different file name than the one used for the Intelligence Server, such askrb5-http.keytab
.Copyktutil
addent -password -p HTTP/[ASMachineName]@[DOMAIN_NAME] -k [KeyVersionNumber] -e [EncryptionType]
wkt /etc/krb5/krb5.keytab
exit -
To verify the keytab file, type the following command:
Copykinit -k -t /etc/krb5/krb5.keytab HTTP/
The command should run without prompting you for a password.
To Create a krb5.keytab File in Windows
- Log in to your Windows machine.
-
From a command prompt, type the following command:
Copyktpass -out [Keytab_Path]
-princ HTTP/[ASMachine]@[DOMAIN_REALM]
-mapUser [ASUser]
-mapOp set
-pass [ASUserPassword]
-crypto [Encryption_Type]
-pType KRB5_NT_PRINCIPAL
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 Configure the krb5.keytab File for the Application Server, 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 formEXAMPLE.COM
, and must be entered in uppercaseKeytab_Path
: The location of yourkrb5.keytab
file. In Linux, it is of the form/etc/krb5/krb5.keytab
. In Windows, it is of the formC:\temp\krb5.keytab
.domain.com
andsubdomain.domain.com
: Use this for all domains and subdomains whose 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 asDC_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 asDC_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.
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 used:
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 formEXAMPLE.COM
, and must be entered in uppercase.
The parameters are entered in the .accept
section of the jaas.conf
file.
Sample jaas.conf for Sun JDK 1.5
com.sun.security.jgss.accept { com.sun.security.auth.module.Krb5LoginModule required
principal="HTTP/[ASMachineName]@[DOMAIN_REALM]"
useKeyTab=true
doNotPrompt=true
storeKey=true
debug=true;
};
Sample jaas.conf for Sun JDK 1.6
com.sun.security.jgss.krb5.accept { com.sun.security.auth.module.Krb5LoginModule required
principal="HTTP/[ASMachineName]@[DOMAIN_REALM]"
useKeyTab=true
doNotPrompt=true
storeKey=true
debug=true;
};
Sample jaas.conf for IBM JDK
com.ibm.security.jgss.accept {
com.ibm.security.auth.module.Krb5LoginModule required
useDefaultKeytab=trueprincipal="HTTP/[ASMachineName]@[DOMAIN_REALM]"
credsType=acceptor
forwardable=true
debug=true
storeKey=true;
};
Save the jaas.conf
file to the same location as your krb5.conf
file.
Configure the JVM Startup Parameters
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 thejaas.conf
file. In Linux, it is of the form/etc/krb5/jaas.conf
. In Windows, it is of the formC:\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 formC:\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
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 the above settings to take effect.
Configuring a Browser for Single Sign-On to MicroStrategy Web
If a MicroStrategy Web user plans to use single sign-on to log in to MicroStrategy Web, the user must configure their browser to enable integrated authentication. The process to enable integrated authentication is different depending on the browser you use:
- For Internet Explorer, you must enable integrated authentication for the browser, as well as add the MicroStrategy Web server URL as a trusted site.
Depending on your security policy, integrated authentication may be enabled by default for Internet Explorer.
- For Firefox, you must add the MicroStrategy Web server URL as a trusted site. The URL must be listed in the
about:config
page, in the settingsnetwork.negotiate-auth.trusted-uris
andnetwork.negotiate-auth.delegation-uris
.
Linking a Domain User to a MicroStrategy User
To apply security and privileges to a user in MicroStrategy, you must link the domain user to a MicroStrategy user. This also enables the domain user to be logged into MicroStrategy projects they have access to without having to type their login credentials again.
A domain user included in a domain to support integrated authentication. For information on configuring a user in a domain, see Configuring a Domain Controller and Users.
A MicroStrategy user (object) to link to a domain user.
A MicroStrategy user with administrative privileges to make the required user modifications.
To Link a Domain User to a MicroStrategy User
- In Developer, log in to a project source using an account with administrative privileges.
- From the Folder List, expand a project source, go to Administration > User Manager.
- Browse to the MicroStrategy user you want to link a Windows user to. Right-click the MicroStrategy user and select Edit.
- Expand Authentication, then select Metadata.
-
In the Trusted Authenticated Request area, type the domain user in the User ID field. Valid syntax is shown below:
DomainUserName
@
DOMAIN_REALM
For example, to link User1 who is in the
example.com
domain realm, you must typeUser1@EXAMPLE.COM
. The domain realm name must be in uppercase. - Click OK.
Using Integrated Authentication for a Project Source
To enable users to log in to a project source in MicroStrategy with integrated authentication, you must define the project source to use integrated authentication. The procedure below describes the steps to define a project source to use integrated authentication.
A MicroStrategy user with administrative privileges to make the required user modifications.
To Use Integrated Authentication for a Project Source
- In Developer, log in to a project source using an account with administrative privileges.
- Right-click a project source, and then click Modify Project Source.
- On the Connection tab, under Server Name, type the server name exactly as it appears is the Service Principal Name created in Trusting Intelligence Server for Delegation. For example, if the SPN is
MSTRSVRSvc\server.example.com:1234
, the Server Name for the project source should beserver.example.com
. - On the Advanced tab, select the Use Integrated Authentication option.
Enabling Integrated Authentication Login Mode for MicroStrategy Web
For MicroStrategy Web users to be able to use their Windows credentials to log in to MicroStrategy Web, you must enable integrated authentication as an available login mode. The procedure below describes the required steps for this configuration.
To Enable Integrated Authentication Login Mode for MicroStrategy Web
- From the Windows Start menu, go to All Programs > MicroStrategy Tools > Web Administrator.
- On the left, select Default Properties.
- In the Login area, for Integrated Authentication, select the Enabled check box.
If you want integrated authentication to be the default login mode for MicroStrategy Web, for Integrated Authentication, select the Default option.
- Click Save.
Enabling Integrated Authentication for MicroStrategy Mobile
To allow your MicroStrategy Mobile users to use their Windows credentials to log into MicroStrategy, you create a Mobile configuration, and select Integrated Authentication as the authentication method.
Enabling Integrated Authentication to Data Sources
Through the use of integrated authentication, you can allow each user's credentials to be passed to your database server. You must enable this option at the project level.
If your reports or documents use subscriptions, using integrated authentication for your data sources prevents the subscriptions from running.
The steps to configure this optional support are described below.
Your database server must be configured to allow integrated authentication for all MicroStrategy users that use it as a data warehouse. Refer to your third-party database server documentation for instructions on enabling this support.
To Enable Integrated Authentication to Data Sources
- In Developer, log in to the project whose data sources you want to configure.
- In the Administration menu, go to Projects > Project Configuration > Database instances
- Expand Authentication, and select Warehouse.
- Enable the For selected database instances radio button.
- From the Metadata authentication type drop-down list, choose Kerberos.
- In the Database Instance pane, enable the check boxes for all the database instances for which you want to use integrated authentication, as shown below.
If you are connecting to a Microsoft SQL Server, Teradata, or TM1 data source, use this setting only if your Intelligence Server is running on Windows.
- Click OK.
Enabling Integrated Authentication for the MicroStrategy Hadoop Gateway
The MicroStrategy Hadoop Gateway is a data processing engine that you install in your Hadoop® environment. The Hadoop Gateway lets you analyze unstructured data in Hadoop, and provides high-speed parallel data transfer between the Hadoop Distributed File System (HDFS) and your MicroStrategy Intelligence Server.
Before enabling integrated authentication for your Hadoop cluster, ensure that you have met the following prerequisites. To enable integrated authentication for your Hadoop cluster, refer to your third-party documentation.
You have installed the Hadoop Gateway in your Hadoop cluster. For steps to install the Hadoop Gateway, see the Installation and Configuration Help.
You have enabled integrated authentication for Intelligence Server and Web, as described in Enable Integrated Authentication for IIS or Enabling Integrated Authentication for J2EE-Compliant Application Servers, depending on your platform.
In your Hadoop cluster, you have set up a user account that has permissions to create new users.
Your Hadoop cluster can access your Kerberos domain controller.
For specific steps to enable integrated authentication for your Hadoop cluster, refer to the documentation for your Hadoop cluster distribution.