MicroStrategy ONE

Single Sign-On with SAML Authentication for JSP Web and Mobile

You can configure MicroStrategy Web and MicroStrategy Mobile to work with SAML‑compliant single sign‑on (SSO). To complete the set up in this document, a basic understanding of SAML workflows is required.

Though the following prerequisites and procedures refer to MicroStrategy Web, the same information applies to MicroStrategy Mobile, except where noted.

Before you begin configuring MicroStrategy Web to support single sign-on, make sure you have done the following:

  • Deployed a SAML‑enabled identity provider (IdP) infrastructure
  • Verified that MicroStrategy Web is run on a JSP server.

  • Deployed MicroStrategy Web on this Web application server. Deploy the MicroStrategy Web WAR file on the Web application server in accordance with your Web application server documentation.

The following procedures describe how to configure and integrate SAML support for MicroStrategy Web to implement single sign‑on.

Generate and Manage SAML Configuration Files

MicroStrategy SAML support relies on several configuration files. MicroStrategy provides a web page that automatically generates the necessary files based on the provided information. SAML metadata is used to share configuration information between the Identity Provider (IdP) and the Service Provider (SP). Metadata for the IdP and the SP is defined in the XML files.

To launch the page that generates the configuration files, open a browser and enter the following URL:

Copy 
<web application_path>/saml/config/open

To access, you are prompted for the application server's admin credentials.

If you deployed MicroStrategy Web under the name MicroStrategyWeb and you are launching the configuration page from the machine where you deployed MicroStrategy Web, the URL is:

Copy 
http://<FQDN>:<port>/MicroStrategyWeb/saml/config/open

If you deployed MicroStrategy Mobile under the name MicroStrategyMobile and you are launching the configuration page from the machine where you deployed MicroStrategy Mobile, the URL is:

Copy 
http://<FQDN>:<port>/MicroStrategyMobile/saml/config/open

Existing SAML Configuration Files

In MicroStrategy 2021 Update 3, you can download the existing SAML configuration file without manually connecting to the Web server machine.

If you have already configured SAML, you can download the following SAML configuration files and verify the content.

  • IDPMetadata.xml

  • SPMetadata.xml

  • SamlKeystore.jks

Upload IDPMetadata

In MicroStrategy 2021 Update 3, you can upload the IDPMetadata.xml configuration file without manually connecting to the Web server machine.

You can upload or change the existing IDPMetadata.xml file with the metadata file generated by the Identity Provider.

SAML Configuration Generation

The SAML configuration files are generated by submitting the following details:

  • General

    • Entity ID: This the unique identifier of the web application to be recognized by the IdP.

      Some IdPs may require Entity ID to be the web application URL. SAML standards state it can be any string as long as a unique match can be found among the IdP's registered entity IDs. Follow the requirements for your specific IdP.

    • Entity base URL: This is the URL the IdP will send and receive SAML requests and responses. The field will be automatically generated when you load the configuration page, but it should always be double checked.

      If you deployed MicroStrategy Web under the name MicroStrategyWeb, the URL is:

      http://<FQDN>:<port>/MicroStrategyWeb

      If you deployed MicroStrategy Mobile under the name MicroStrategyMobile, the URL is:

      http://<FQDN>:<port>/MicroStrategyMobile

      If the web application is set up behind reverse proxy or load balancer, use FQDN of the proxy or loadbalancer in this URL.

      • Do not use "localhost" for the Entity base URL.
      • Do not use a trailing / at the end of the URL.
      • Once configured, remember to always use this URL to access MicroStrategy Web – using any alternative host name to visit would end up failing the SAML authentication.

    • Behind the proxy: Using a reverse proxy or load balancer can alter the HTTP headers of the messages sent to the application server. These HTTP headers are checked against the destination specified in the SAML response to make sure it is sent to the correct destination. A mismatch between the two values can cause the message delivery to fail. To prevent this, select Yes if MicroStrategy Library runs behind a reverse proxy or load balancer. The base URL field is set to the front-end URL. Select No if you are not using a reverse proxy or load balancer.

  • Encryption

    • Signature algorithm: The default is to use the industry standard "SHA256 with RSA" encryption algorithm. Set this value in accordance with the requirements of your specific IdP.

    • Generate Encryption Key: Set to No by default. Setting to Yes will generate an encryption key and store it in the MicroStrategy Library metadata XML file.

      If setting Generate Encryption Key to Yes: SAML authentication will not work unless you have the proper Java encryption strength policy and correct setup on IdP side.

  • Assertion Attribute mapping

    These options control how user attributes received from the SAML responses are processed. If the SAML attribute names are configurable on IdP side, you may leave all options as default. If your IdP sends over SAML attributes in fixed names the values must be changed on the web application side to match.

    • You can also change attribute names in MstrSamlConfig.xml even after the configuration is done.

    • Display Name Attribute: User display name attribute
    • Email Attribute: User email address attribute
    • Distinguished Name Attribute: User distinguished name attribute
    • Group Attribute: User group attribute
    • Group format
      • Simple: The default option takes a user's group information as plain group names. When using this option, make sure values sent over by IdP in the "Groups" attribute are group names and nothing else.
      • DistinguishedName: DistinguishedName means that values sent over in the "Groups" attribute are the LDAP DistinguishedName of the user's groups. The option is only used to utilize LDAP integration or when the IdP only sends group information as DistinguishedNames.

  • Admin Groups: Defines groups that can access Administrator page.

    • To define multiple groups, use comma to separate them. Do not add space in front of or behind comma.

    For example, group information is passed in the SAML response as:

    Copy 
    <saml2:Attribute Name="Groups" NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:unspecified">
       <saml2:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema- instance" xsi:type="xs:string">IdPGroupA </saml2:AttributeValue>
       <saml2:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">IdPGroupB </saml2:AttributeValue>
    </saml2:Attribute>

    To allow IdPGroupA and IdPGroupB users to access Administrator page, the configuration is:

    • Group Attribute:Groups
    • Admin Groups:IdPGroupA,IdPGroupB

Click Generate config to generate three configuration files in the WEB-INF/classes/resources/SAML folder of the MicroStrategy Web installation directory:

  • MstrSamlConfig.xml Contains run-time SAML support configuration parameters
  • SPMetadata.xml Contains metadata describing your web application to SSO
  • SamlKeystore.jks Contains necessary cryptographic material

Do not rename any of the generated files.

Register MicroStrategy Web with Your Identity Provider

To register MicroStrategy Web with your IdP, you need to do the following:

  • Register MicroStrategy Web with your IdP using the SPMetadata.xml file you generated in the previous step.
  • Configure the SAML Assertion attributes

Each SAML-compliant IdP has a different way to perform these steps. The sections below provide a general overview of the process.

  1. Register the web application with SSO:

    Use the SPMetadata.xml file you generated in the previous step to register the MicroStrategy Web application with the IdP.

    If uploading a metadata file is not supported by your IdP, manual configuration is necessary.

    The SPMetadata.xml file contains all of the information needed for manual configuration.

    • The entityID= parameter is the same EntityID you provided in the SAML config page
    • AssertionConsumerService Location= this URL is located near the end of the file.

      Be aware that there are multiple URLs in this file. The AssertionConsumerService Location will contain the binding statement HTTP-POST at the end.

    • If the signing certificate is required:
      1. Copy the text between <ds:X509Certificate> and </ds:X509Certificate> tags.
      2. Paste the contents into a text editor.
      3. Save the file as file_name.cer and upload to IdP.
  2. Configure SAML Assertion attributes:

    MicroStrategy Web uses information about users from the SAML Response to create Intelligence Server sessions. The settings are how SAML users are mapped or imported to MicroStrategy.

    The user properties that MicroStrategy uses for mapping are:

    Required attributes

    • Name ID: Maps to Trusted Authenticated Request User ID of the MicroStrategy user as defined in MicroStrategy Developer.

    Optional attributes

    • DisplayName: Used to populate or link to a MicroStrategy user's Full name
    • EMail: User email
    • DistinguishedName: Used to extract additional user information from the LDAP server
    • Groups: List of groups user belongs to

    Attribute names are case sensitive. Make sure any SAML attribute name configured here is an exact match to the web application configuration.

    In the case where IdP does not allow customization of SAML attribute names and provides fixed names instead, you may modify the corresponding attribute names in MstrSamlConfig.xml generated previously.

    For more information on mapping users between a SAML IdP and MicroStrategy, see Mapping SAML Users to MicroStrategy

    When configuring assertion attributes, make sure you set up users who belong to a group (for example admin) with the same group name as defined when generating configuration files in MicroStrategy Web (step 2 in Generate and Manage SAML Configuration Files). Otherwise, no user will be able to access the web administrator page after the web.xml file has been modified and the Web server restarted. Use Groups as SAML Attribute Name.

  3. Download the IdP metadata:

    Consult the SSO documentation for instructions on how to export or download the IdP metadata. The IdP metadata file must be named IDPMetadata.xml. This file can either be uploaded using the Upload IDPMetadata functionality mentioned inGenerate and Manage SAML Configuration Files or directly placed in the WEB-INF/classes/resources/SAML folder. Ensure that the EntityID value in the IDPMetadata.xml file is different from the EntityID value in the SPMetadata.xml file to avoid web application errors.

    MicroStrategy does not automatically update the IDPMetadata.xml file. If for any reason the metadata changes on the IdP side, you will need to download and replace IDPMetadata.xml manually.

Configure the Intelligence Server and Enable SAML Authentication

To use SAML authentication, you need to configure the trusted relationship between the Web server and the Intelligence Server and enable SAML authentication. This is done through the Administrator Page. Open the admin page for your web application. Then, connect to the Intelligence Server you want to use.

  • Establish trust between the server and Intelligence Server:
    1. Open the Server properties editor.
    2. Next to Trust relationship between MicroStrategy Web Server and MicroStrategy Intelligence Server, click Setup.

    3. Enter the Intelligence Server administrator credentials.
    4. Click Create Trust relationship.
  • Enable SAML authentication for 2021 Update 2 or later:

    1. In the Default Properties section of the Web Administrator page, enable SAML authentication and click Save.

    2. Restart the Web server.

  • Enable SAML authentication for 2021 Update 1:

    1. In the Default Properties section of the Web Administrator page, enable SAML authentication and click Save.

    2. Locate the web.xml file located in the WEB-INF folder of the MicroStrategy Web installation directory and open it in a text editor.

    3. Comment out the two security constraints as shown below to disable basic authentication for the Administrator page. Surround the constraints with <!-- and --> tags. Make sure that there are no sub comments in the text, as this may cause an error. If you decide to change to another authentication mode besides SAML in the future, you must reverse the changes done in this step.

  • Enable SAML authentication for the 2021 platform release or older versions:

    In MicroStrategy Web, the Default properties screen is used for configuring default login mode, but the default properties do not apply to SAML for 2021 or older versions. When SAML authentication is configured in web.xml, this screen displays SAML settings regardless of the default property values and all the login fields on the page are disabled. SAML is chosen unconditionally for trusted mode.

    If you decide to configure SAML authentication in web.xml, you must first enable Trusted Authentication Request.

    To enable SAML in the Web application for 2021 or older versions, modify the web.xml file located in the WEB-INF folder of the MicroStrategy Web installation directory.

    1. Stop the MicroStrategy Web application server.

    2. Delete the first and last line of the web.xml fragment shown below to enable SAML authentication.

      Copy 
      <!-- Delete fragment below to enable SAML Authentication mode 
          <context-param> 
              <param-name>contextConfigLocation</param-name> 
              <param-value>classpath:resources/SAML/SpringSAMLConfig.xml</param-value> 
          </context-param> 

          <context-param> 
              <param-name>contextInitializerClasses</param-name> 
              <param-value>com.microstrategy.auth.saml.config.ConfigApplicationContextInitializer</param-value> 
          </context-param> 

          <filter> 
              <filter-name>springSecurityFilterChain</filter-name> 
              <filter-class>org.springframework.web.filter.DelegatingFilterProxy</filter-class> 
          </filter> 
          <filter-mapping> 
              <filter-name>springSecurityFilterChain</filter-name> 
              <url-pattern>/servlet/*</url-pattern> 
          </filter-mapping> 
          <filter-mapping> 
              <filter-name>springSecurityFilterChain</filter-name> 
              <url-pattern>/saml/*</url-pattern> 
          </filter-mapping> 

          <listener> 
              <listener-class>org.springframework.web.context.ContextLoaderListener</listener-class> 
          </listener> 
          --> 

    3. Save the web.xml file.

    4. Restart the Web server.

    To disable SAML in a Web application for the 2021 platform release and older versions, modify the web.xml file located in the WEB-INF folder of the MicroStrategy Web installation directory.

    1. Replace the web.xml file of the Web application with the original file that you saved.

    2. Open the Web Administrator page.
    3. Change the Login mode to the desired mode.
    4. Remove the trust relationship between the Web server and Intelligence Server.
    5. Restart the Web server.

Configure Logging

  1. Locate the log4j2.properties file in the WEB-INF/classes folder.
  2. Modify the property.filename property to point to the folder where you want the SAML logs stored.

    It is not recommended to leave the file as is, since the relative file path is very unreliable and can end up anywhere. The file can almost always cannot be found in the Web application folder. Use full file paths to fully control the log location.

    In a Windows environment, the file path must be in Java format. This means you either need to change each backslash ("\") to a slash ("/"), or you need to escape the backslash with another one ("\\"). There is also a way to shorten the path by referring to the Tomcat base folder as a variable, for example:

    Copy
    ${catalina.home}/webapps/MicroStrategy/WEB-INF/log/SAML/SAML.log

    For troubleshooting purposes it is recommended to first change the level of org.opensaml, that is the logger.d.level property, to debug and leave everything else as the default. This generates a clean log with all SAML messages, along with any errors or exceptions.

  3. Restart the Web application server to apply all changes.

    If you have a problem accessing the MicroStrategy Web Administrator page, close and reopen your web browser to clear the old browser cache.

Change the Authentication Mode for the Admin Web Pages

In 2021 Update 2 or later, the Web admin pages support SAML and basic authentication when SAML authentication is enabled. The admin pages authentication is governed by the springAdminAuthMethod parameter located in the WEB-INF/xml/sys_defaults.properties file.

There are two possible values for the springAdminAuthMethod parameter:

  • springAdminAuthMethod = 2

    The default value of the springAdminAuthMethod parameter is 2. This means the Web admin pages are protected by the SAML admin groups mentioned in the saml/config/open form. These admin groups are linked to the groups on the Identity Provider (IDP) side. The members who belong to the IDP admin groups can only access the admin pages. Users that do not belong to the admin group receive a 403 Forbidden error.

  • springAdminAuthMethod = 1

    Admin pages are protected with basic authentication.

The administrator can change the parameter value as per the requirements. A Web server restart is required for the changes to take effect.