Version 2021

Integrating SAML Support with Azure AD

Create an Application

  1. Sign in to the Azure portal. If you have already launched Azure, under Manage, go to Azure Active Directory and select Enterprise applications.

  2. At the top, select New application > Create your own application.
  3. Provide a Name for the application, select the Non-gallery app option, and click Create.

Configure the Application

  1. In the Set up single sign-on tile, click Get Started and select SAML as the sign-on method.

  2. Click Upload metadata file and add SPMetadata.xml from your deployment folder.

    The default path of SPMetadata.xml for Library is:
    /opt/apache/tomcat/apache-tomcat-9.0.43/webapps/MicroStrategyLibrary/WEB-INF/classes/auth/SAML

    The default path of SPMetadata.xml for Web is:
    /opt/apache/tomcat/apache-tomcat-9.0.43/webapps/MicroStrategy/WEB-INF/classes/resources/SAML

  3. Click Save.
  4. Set the user attributes as defined in the configuration file. By default, the Unique User Identifier should be user.mail. Add the group attribute by choosing Edit > Add a group claim > All groups and save the defined group attribute.

  5. Download the Federation Metadata XML file and save it as IDPMetadata.xml in the SAML folder of your deployment.

Assertion Attributes

  1. View the Federation Metadata document downloaded in the previous section to obtain the URIs for required attributes such as displayName, emailaddress, and groups.

  2. Copy
    <auth:ClaimType Uri="http://schemas.microsoft.com/identity/claims/displayname" xmlns:auth="http://docs.oasis-open.org/wsfed/authorization/200706">
    <auth:DisplayName>Display Name</auth:DisplayName>
    <auth:Description>Display name of the user.</auth:Description>
    </auth:ClaimType>
    <auth:ClaimType Uri="http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress" xmlns:auth="http://docs.oasis-open.org/wsfed/authorization/200706">
    <auth:DisplayName>Email</auth:DisplayName>
    <auth:Description>Email address of the user.</auth:Description>
    </auth:ClaimType>
    <auth:ClaimType Uri="http://schemas.microsoft.com/ws/2008/06/identity/claims/groups" xmlns:auth="http://docs.oasis-open.org/wsfed/authorization/200706">
    <auth:DisplayName>Groups</auth:DisplayName>
    <auth:Description>Groups of the user.</auth:Description>
    </auth:ClaimType>
  3. Copy these values and paste them between the <userInfo> tags in MstrSamlConfig.xml, located in the deployment folder.

    Copy
    <userInfo>
    <groupAttributeName>http://schemas.microsoft.com/ws/2008/06/identity/claims/groups</groupAttributeName>
    <groupFormat>Simple</groupFormat>
    <dnAttributeName>DistinguishedName</dnAttributeName>
    <displayNameAttributeName>http://schemas.microsoft.com/identity/claims/displayname</displayNameAttributeName>
    <emailAttributeName>http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress</emailAttributeName>
    <adminGroups>2109318c-dee4-4658-8ca0-51623d97c611</adminGroups>
    <roleMap/>
    </userInfo>

    Azure AD only sends the IDs. For admin permissions, the Object ID must also be copied.

    Copy
    <adminGroups>36198b4e-7193-4378-xxx4-715e65edb580</adminGroups>
    <roleMap/>
    </userInfo>

Troubleshooting

After Making the Above Changes, the Web Deployment Fails to Start

Once web.xml has been changed to include SAML support, it refers to the metadata and configuration files in the resources/SAML folder. If the Web deployment fails to start, it is possible the generated files from the resources/SAML/stage folder were not copied over. Copy the required files to the SAML folder and restart the application.

Azure Returns a Log in Failure and Assertion is in Place

This is a result of bad metadata in IDPMetadata.xml. Ensure the correct metadata from the application is copied to the SAML folder.

Azure Returns the Error: Application with identifier “xxx” was not found in the directory “xxx”

The App ID URI does not match the entityID set in the SP metadata. Review the URIs and correct the names accordingly. Changes can be made in SPMetadata.xml, MstrSamlConfig.xml, and Azure. Restart the application after you finalize the changes.

Azure SAML group number limitation

If the number of groups the user is in, goes over a limit (150 for SAML), there will be a limitation on the group attributes carried in the SAML assertion and it won't work as expected. Please refer to Azure doc for more details.