Version 2021

Generate SAML Configuration Files

The following steps generate the application metadata (SPMetadata.xml) and SAML configuration files (MstrSamlConfig.xml) for configuring SAML.

To access the configuration page, you need admin privileges.

  1. Open a browser and access the SAML configuration page by the following URL:

    http://<FQDN>:<port>/<MicroStrategyLibrary>/saml/config/open

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

  2. Fill in the following:
    • General:
      • Entity ID: This the unique identifier of the application to be recognized by the IdP.

        Some IdPs may require Entity ID to be the 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. It should be the application URL end users would use to access the application.

        If the application is set up behind reverse proxy/load balancer, the auto-populated URL here may not be correct. Ensure you are using the front-end URL.

        • Do not use "localhost" for the Entity base 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.

      • Logout mode: Select Local to prevent users from being logged out from all other applications controlled by SSO. Global logout is no longer supported starting in MicroStrategy 2021 Update 4.
    • Encryption:
      • Signature algorithm: The default is to use the industry standard "SHS256 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 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.
      • Distiguished 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 the Administrator page.

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

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

      <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 the Administrator page, the configuration is:

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

      When the admin pages are protected by the SAML Authentication then only the members who belong to the admin groups will be able to access it.

  3. Click Generate config.

    The following configuration files are generated in the WEB-INF/classes/auth/SAML folder of the MicroStrategy Library 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.