MicroStrategy ONE

This page applies to MicroStrategy 2021 Update 4 and newer versions.

SAML Upgrade Guidance for MicroStrategy Web and Mobile

Use the procedures below to upgrade your non-customized (out-of-the-box) or customized SAML infrastructure. You can determine whether you environment is non-customized or customized by looking for manual changes in the SpringSAMLConfig.xml file. You can find this configuration file in the following locations:

  • MicroStrategy Web: /<TOMCAT_HOME>/webapps/MicroStrategy/WEB-INF/classes/resources/SAML/SpringSAMLConfig.xml

  • MicroStrategy Mobile: /<TOMCAT_HOME>/webapps/MicroStrategyMobile/WEB-INF/classes/resources/SAML/SpringSAMLConfig.xml

Upgrade a Non-customized SAML System

  1. Back up the following files in <TOMCAT_HOME>\webapps\MicroStrategy\WEB-INF\classes\resources\SAML\:

    Do not back up SpringSamlConfig.xml.

    • IDPMetadata.xml

    • SPMetadata.xml

    • SamlKeystore.jks

    • MstrSamlConfig.xml

  2. Restore the files listed above to the same location after upgrading.

  3. Change or add the following values in <TOMCAT_HOME>\webapps\MicroStrategy\WEB-INF\xml\sys_defaults.properties:

    Copy 
    defaultloginmode=1048576
    enableloginmode=1048576
    springAdminAuthMethod=2

Upgrade a Customized SAML System

The following is a list of common SAML customization cases for upgrade guidance. If your customization is not in the following list, see SAML Customization for MicroStrategy Web and Mobile for more information.

  1. Remove the spring-security-saml2-core framework.

    If you leverage classes in this framework for customizations, you must remove them using the provided parity classes or the ones in the new framework. The following table contains some useful parity classes for your upgrade. If you are using them, directly change their class name to the new one.

    Parity Class Transfers
    Old New Description
    org.springframework.security.saml.SAMLCredential com.microstrategy.auth.saml.response.SAMLCredential This class is exactly the same as the previous one.
    org.springframework.security.saml.SAMLCredential com.microstrategy.auth.saml.SAMLUserDetailsService An extra loadSAMLProperties method is added. This method is called in SAMLRelyingPartyRegistration's constructor when the app is launched. Subclasses should take advantage of the SAMLConfig instance and set internal properties.
    org.springframework.security.providers.ExpiringUsernameAuthenticationToken com.microstrategy.auth.saml.response.SAMLAuthentication This class is a replacement of the previous authentication token which has the same properties as the old one.

  2. Upgrade the org.opensaml framework to v4.1.0.

    If you are using utility classes in v2.6.7, you must transfer them to parities in v4.1.0.

  3. If your web server is behind a proxy, remove all previous proxy-related customizations.

    In the SAML configuration generation page, located at {ContextPath}/saml/config/open, select Yes from the Behind the proxy drop-down. No additional customization is necessary.

    Starting in MicroStrategy 2021 Update 4, customized proxies cannot be added back. Otherwise, the app cannot start.

  4. If you have customized a SAML response handling process, such as SAMLProcessingFilterWrapper, or leveraged classes in the old framework, such as SAMLProcessingFilter, see SAML Customization for MicroStrategy Web and Mobile to learn how to achieve the same behavior in the new version.

  5. If you have customized the maxAuthenticationAge and responseSkew properties, they are relocated to com.microstrategy.auth.saml.response.SAMLAssertionValidator.

    Add the following code to the new version:

    Copy 
    <bean id="samlAssertionValidator" class="com.microstrategy.auth.saml.response.SAMLAssertionValidator">
          <property name="maxAuthenticationAge" value="2592000"/><!-- 30 days -->
          <property name="responseSkew" value="300"/>
    </bean>

    See SAML Customization for MicroStrategy Web and Mobile for details.

  6. The new framework performs minimal validation on SAML 2.0 assertions. After verifying the signature, it:

    • Validates the <AudienceRestriction> and <DelegationRestrictions> conditions

    • Validates <SubjectConfirmation>s, except for any IP address information

    To perform additional validation, configure your own assertion validator. See SAML Customization for MicroStrategy Web and Mobile for details.

  7. Customizations that are performed on the logout process must be removed since the single logout process is not supported in the new framework. This can be added back later.

    Starting in MicroStrategy 2021 Update 4, customized global logout cannot be added back. Otherwise, the app cannot start.