MicroStrategy ONE

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

SAML Upgrade Guidance for MicroStrategy Library

Use the procedures below to upgrade your non-customized or customized SAML infrastructure. Any customizations you have made to your SAML workflows require manual changes to the SAML configuration file located at: /<TOMCAT_HOME>/webapps/MicroStrategyLibrary/WEB-INF/classes/auth/custom/SAMLConfig.xml.

Upgrade a Non-Customized SAML System

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

    • IDPMetadata.xml

    • SPMetadata.xml

    • SamlKeystore.jks

    • MstrSamlConfig.xml

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

  3. Change or add the following values in <TOMCAT_HOME>\webapps\MicroStrategyLibrary\WEB-INF\classes\config\configOverride.properties:

    Copy 
    auth.modes.available=1048576
    auth.modes.default=1048576
    auth.admin.authMethod=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 Library 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, older customized proxies must be removed. 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 Library 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 Library 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 for details.

  7. Customizations 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.