KB485522: SAML Upgrade Guidance for MicroStrategy

SAML Upgrade Guidance for Strategy Web/Mobile

Pre-Upgrade – Back up configuration files

1. Back up the following SAML configuration files under <Strategy>/WEB-INF/classes/resources/SAML/:

• IDPMetadata.xml
• SPMetadata.xml
• SamlKeystore.jks
• MstrSamlConfig.xml

 
Note: back up SpringSamlConfig.xml if you make any customization to the file for future reference, but please do not restore it to the target environment directly.

1. Back up sys_defaults.properties. The properties file contains the authentication mode setting of Strategy Web and it can be found under <Strategy>/WEB-INF/xml/.
2. Back up web.xml under <Strategy>/WEB-INF/.
3. Back up the .token file(s) under <Strategy>/WEB-INF/xml/.
4. Back up the files used to configure the SameSite flag for Strategy deployments.
   Refer to this KB article about how to set SameSite to None with the associated cookie marked as “Secure”.

• context.xml which can be found at <Strategy>/META-INF/
• sys_defaults.xml which defines the value of "alwaysSecureCookie"

Post Upgrade:

1. Restore the SAML configuration files to <Strategy>/WEB-INF/classes/resources/SAML/.

• IDPMetadata.xml
• SPMetadata.xml
• SamlKeystore.jks
• MstrSamlConfig.xml

Note:

• Do not restore the SpringSamlConfig.xml file directly as the file varies among different Strategy versions/update. Instead, use the out-of-the-box SpringSamlConfig.xml file shipped with the new version. Any modification should be based on the new version of the xml file.
• From Strategy 2021 Update 4, org.opensaml has been upgraded from v2.6.7 to v4.1.0. The spring-security-saml2-core framework, whose end of life is October 6, 2021, has also been replaced with a newer, more secure spring-security-saml2-service-provider v5.5.3.
  If you made any customization to SpringSamlConfig.xml and attempt to upgrade Strategy to version 2021 Update 4 or later, please refer to this documentation on how to upgrade the customized SAML.

1. Restore sys_defaults.properties to <Strategy>/WEB-INF/xml/.
   
   Note: from 2021 Update 2, it's supported to change authentication mode between basic and SAML for the Strategy Web admin page. The admin page 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.

1. Compare the backup of web.xml with the one shipped with the new version. Make changes based on the out of the box xml file in the target environment.
   Note: please do not restore the xml file directly to the target environment as the contents of the files vary among different versions/updates of Strategy Web.
    
2. Restore the token file(s) to <Strategy>/WEB-INF/xml/.
3. Restore context.xml to <Strategy>/META-INF/.
   For sys_defaults.xml, please don’t restore it directly as the contents of the files vary among different versions/updates of Strategy. Instead, set “alwaysSecureCookie” to 1 as suggested in this KB article. Make sure SameSite is set to None with the associated cookie marked as “Secure” after restoring the settings.

Restart the web application server after changing the above.

SAML Upgrade Guidance for Strategy Library

Pre-Upgrade – Back up configuration files

1. Back up the following SAML configuration files under <StrategyLibrary>/WEB-INF/classes/auth/SAML/:

• IDPMetadata.xml
• SPMetadata.xml
• SamlKeystore.jks
• MstrSamlConfig.xml

1. Back up SAMLConfig.xml under <StrategyLibrary>/WEB-INF/classes/auth/custom/
2. Back up configOverride.propeties. The properties file contains the authentication mode setting of Strategy Library and the trust token info. It can be found under <StrategyLibrary>/WEB-INF/classes/config/
3. Back up the files used to configure the SameSite flag for Strategy Library deployments.
4. Refer to this KB article about how to set SameSite to None with the associated cookie marked as “Secure”.

• context.xml which can be found at <StrategyLibrary>/META-INF/
• web.xml which can be found at <StrategyLibrary>/WEB-INF/

Post Upgrade:

1. Restore the SAML configuration files to <StrategyLibrary>/WEB-INF/classes/auth/SAML/.

• IDPMetadata.xml
• SPMetadata.xml
• SamlKeystore.jks
• MstrSamlConfig.xml
  
  From Strategy Library 2021 Update 1, the <roleMap/> tag is required in MstrSamlConfig.xml. To upgrade Strategy Library to version 2021 Update 1 or a newer version, please refer to KB485023 to add the <roleMap/> tag manually if your MstrSamlConfig.xml was copied from Strategy Library 2020 Update 4 or earlier environment. 

1. Check the backup of SAMLConfig.xml which contains your SAML customizations. Add these customizations to SAMLConfig.xml shipped with the new version of Strategy Library.
   
    From Strategy 2021 Update 4, org.opensaml has been upgraded from v2.6.7 to v4.1.0. The spring-security-saml2-core framework, whose end of life is October 6, 2021, has also been replaced with a newer, more secure spring-security-saml2-service-provider v5.5.3. To upgrade Strategy Library to version 2021 Update 4 or later, please refer to this documentation on how to upgrade a customized SAML system.
    
2. Restore configOverride.propeties to <StrategyLibrary>/WEB-INF/classes/config/
3. Authentication mode change for Strategy Library admin pages.

• In Strategy Library 2021 Update 1, Strategy Library admin pages can be protected by either Basic or SAML authentication. Please refer to KB485016 for details.
   
• From Strategy Library 2021 Update 2, the Strategy Library admin page authentication is governed by the auth.admin.authMethod parameter in the WEB-INF/classes/config/configOverride.properties file. You can add the parameter manually to the file based on your requirement.
  
  There are two possible values for the auth.admin.authMethod parameter:
  
  auth.admin.authMethod = 1 (Default)
  The default value of the auth.admin.authMethod parameter is 1. This means the Library admin pages are protected by basic authentication.
  
  auth.admin.authMethod = 2
  The Library admin pages are protected by the SAML admin groups. 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.
  
  The administrator can change the parameter value as per the requirements. A Web application server restart is required for the changes to take effect.

1. Restore context.xml to <StrategyLibrary>/META-INF/.
   For web.xml, please don’t restore it directly as the contents of the files vary among different versions/updates of Strategy Library. Instead, compare the settings between the backup of web.xml and the one shipped with the new version. Add back the changes based on the new version of web.xml.

Refer to this KB article for details on how to set SameSite to None with the associated cookie marked as “Secure”.
Restart the web application server after changing the above.
Refer to the following KB articles if you encounter issues after migrating the SAML configurations to a newer version:

• KB485377: “Error in login” appears using SAML authentication with assertion encryption enabled with MicroStrategy Web after upgrading to m2021 Update 4
• Use Signed Authn Requests for SAML in MicroStrategy 2021 Update 4
• KB484169: MicroStrategy Web fails to initialize when SAML is configured after upgrading to MicroStrategy 2020, resulting in a 404 error
• KB485023: Error when upgrading a MicroStrategy 2020 SAML authentication environment to 2021 Update 1