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

SAML Customization for MicroStrategy Web and Mobile

Starting in MicroStrategy 2021 Update 4, the SAML framework spring-security-saml2-service-provider v5.3.3 and OpenSAML v4.1.0 technologies are used. This page illustrates the SAML workflow and beans you may leverage for customization.

SAML Login Workflow

The diagrams and workflows below illustrate how authentication-related requests are handled with different authentication configurations. The following are true for these workflow diagrams:

Double-line arrows represent HTTP requests and responses. Single-line arrows represent Java calls.
The object names correspond to the bean IDs in the configuration XML files. You must view the configuration files to identify which Java classes define those beans.
Only beans involved in request authentication are included. Filters that simply pass the request along the filter chain or perform actions not directly involved in request authentication are not included. As described in the Spring Security architecture, each request passes through multiple Spring Security filters.

Process to Generate <saml2:AuthnRequest>

An unauthenticated user accesses a protected endpoint, such as /servlet/mstrWeb, and is intercepted by the springSecurityFilterChain bean.
The springSecurityFilterChain bean delegates to the mstrSamlEntryPoint bean, which performs a redirection to /saml/authentication by default.

This redirection is designed to support a multi-tenants scenario. If you've configured more than one asserting party, you can first redirect the user to a picker or in most cases, leave it as is.
The browser is redirected and sends a GET: {BasePath}/saml/authenticate request, which is intercepted by the mstrSamlAuthnRequestFilter bean.
The mstrSamlAuthnRequestFilter bean is <saml2:AuthnRequest>, which generates an endpoint that creates, signs, serializes, and encodes a <saml2:AuthnRequest> and redirects to the SSO login endpoint.

Bean Description

Bean ID	Java Class	Description
`mstrSamlEntryPoint`	`com.microstrategy.auth.saml.authnrequest.SAMLEntryPointWrapper`	A subclass of `LoginUrlAuthenticationEntryPoint` that performs a redirect to where it is set in the constructor by the `String redirectFilterUrl` parameter
`mstrSamlAuthnRequestFilter`	`org.springframework.security.saml2.provider.service.servlet.filter.Saml2WebSsoAuthenticationRequestFilter`	By default, this filter responds to the `/saml/authenticate/**` endpoint and the result is a redirect that includes a `SAMLRequest` parameter containing the signed, deflated, and encoded `<saml2:AuthnRequest>`

Customization

Before AuthnRequest is sent, you can leverage the mstrSamlEntryPoint bean according to the time you want your code to be executed, create a subclass, and override the corresponding method with your own logic.

Prior to redirection to /saml/authenticate

If you want to customize before the redirection to /saml/authenticate:

Create a MySAMLEntryPoint class that extends com.microstrategy.auth.saml.authnrequest.SAMLEntryPointWrapper and overrides the commence method.

Execute your code before calling super.commence:

Copy

public class MySAMLEntryPoint extends SAMLEntryPointWrapper {
                        MySAMLEntryPoint(String redirectFilterUrl){
                        super(redirectFilterUrl);
                        }
                        @Override
                        public void commence(HttpServletRequest request, HttpServletResponse response, AuthenticationException e) throws IOException, ServletException {
                        //>>> Your logic here
                        super.commence(request, response, e);
                        }
                    }

Configure your customized bean (Fully Qualified Class Name) in SAMLConfig.xml under the classes/resources/SAML/custom folder with the bean ID "mstSamlEntryPoint" to replace the original one, as shown below.

The constructor argument must be exactly the same as the original if it is not customized.

Copy

<!--  Entry point for SAML authentication mode -->
                        <bean id="mstrSamlEntryPoint" class="com.microstrategy.custom.MySAMLEntryPoint">
                        <constructor-arg value="/saml/authenticate"/>
                    </bean>

Prior to SSO IDP Redirection

If you want to customize before the redirection to SSO IDP:

Create a MySAMLAuthenticationRequestFilter class that extends org.springframework.security.saml2.provider.service.servlet.filter.Saml2WebSsoAuthenticationRequestFilterand overrides the doFilterInternal method.

Execute your code before calling super.doFilterInternal.

Copy

public class MySAMLAuthenticationRequestFilter extends Saml2WebSsoAuthenticationRequestFilter {

    public MySAMLAuthenticationRequestFilter(Saml2AuthenticationRequestContextResolver authenticationRequestContextResolver, Saml2AuthenticationRequestFactory authenticationRequestFactory) {
        super(authenticationRequestContextResolver, authenticationRequestFactory);
    }

    @Override
    protected void doFilterInternal(HttpServletRequest request, HttpServletResponse response, FilterChain filterChain) throws ServletException, IOException {
        //>>> Your logic here
        super.doFilterInternal(request, response, filterChain);
    }
}

Configure your customized bean (Fully Qualified Class Name) in SAMLConfig.xml under the classes/resourcesSAML/custom folder with a "mstSamlAuthnRequestFilter" bean ID to replace the original one, as shown below.

The two constructor arguments and property must be exactly the same as the original if you don't do any customizations to them.

Copy

<bean id="mstrSamlAuthnRequestFilter" class="MySAMLAuthenticationRequestFilter">
                        <constructor-arg ref="samlAuthenticationRequestContextResolver"/>
                        <constructor-arg ref="samlAuthenticationRequestFactory"/>
                        <property name="redirectMatcher" ref="samlRedirectMatcher"/>
                    </bean>

Process to Generate <saml2:Response>

SSO redirects the user to the MicroStrategy Library application. The redirected request contains a SAML assertion describing the authenticated user.
The mstrSamlProcessingFilter SAML processing filter bean extracts the SAML assertion from the request and passes it to the samlAuthenticationProvider authentication provider bean.
The samlAuthenticationProvider bean verifies the assertion and then calls the Intelligence server credentials provider to build an Intelligence server credentials object from the SAML assertion information.
The samlAuthenticationFilter bean saves the authentication object into the HTTP session.
The SAML processing filter calls the login success handler, which redirects the browser to the original request.

Bean Description

Bean ID	Java Class	Description
`mstrSamlProcessingFilter`	`com.microstrategy.auth.saml.response.SAMLProcessingFilter`	This is the core filter that is responsible for handling the SAML login response (SAML assertion) that comes from the IDP server.
`samlAuthenticationProvider`	`com.microstrategy.auth.saml.response.SAMLAuthenticationProviderWrapper`	This bean is responsible for authenticating a user based on information extracted from SAML assertion.
userDetails	`com.microstrategy.auth.saml.SAMLUserDetailsServiceImpl`	This bean is responsible for creating and populating a `IServerCredentials` instance, defining the credentials for creating Intelligence server sessions. The `IServerCredentials` object is saved to the HTTP session, which is used to create the Intelligence server session for future requests.

Customization

For better description, the following content uses the real class name, instead of the bean name. You can find the bean name in SAMLConfig.xml.

You can do the following customizations:

Retrieve more information from SAMLResponse
Customize the login process
Customize SAMLAssertion validation

Retrieve more information from SAMLResponse

The mstrSAMLProcessingFilter bean, also the com.microstrategy.auth.saml.response.SAMLProcessingFilter Java class, is the first layer that directly accesses the SAML response. It accepts the raw HttpServletRequest, which contains the samlResponse, and produces SAMLAuthenticationToken. This is then passed to SAMLAuthenticationProviderWrapper to perform authentication validation in further steps.

If you need to extract more information from HttpServletRequest, perform the following steps:

It is highly recommended that you create a MySAMLConverter class that extends the SAMLAuthenticationTokenConverter class .
Override the convert method and call super.convert, which can get Saml2AuthenticationToken, a subclass of SAMLAuthenticationToken.

Extract the information from the raw request in line 11 and return an instance that is a subclass of Saml2AuthenticationToken:

The following classes are under the com.microstrategy.auth.saml.response package:

SAMLAuthenticationTokenConverter

Saml2AuthenticationToken

Copy

public class MySAMLConverter extends SAMLAuthenticationTokenConverter {
    public MySAMLConverter(Saml2AuthenticationTokenConverter delegate) {
        super(delegate);
    }
    @Override
    public Saml2AuthenticationToken convert(HttpServletRequest request) {
        Saml2AuthenticationToken samlAuthenticationToken =  super.convert(request);
        // >>> Extract info from request that you are interested in
        return samlAuthenticationToken;
    }
}

Configure your customized bean (Fully Qualified Class Name) in SAMLConfig.xml under the classes/resources/SAML/custom folder with a "mstSamlAuthenticationConverter" bean ID and keep the original constructor argument if you don't perform additional customizations:

Copy

<bean id="samlAuthenticationConverter" class="com.microstrategy.custom.MySAMLConverter">
                            <constructor-arg ref="saml2AuthenticationConverter"/>
                        </bean>

Customize the login process

To verify SAML 2.0 responses, SAMLProcessingFilterWrapper delegates authentication work to SAMLAuthenticationProvider. It authenticates a user based on information extracted from SAML assertion and returns a fully populated com.microstrategy.auth.saml.response.SAMLAuthentication object, including granted authorities, if successful. Then, SAMLProcessingFilterWrapper saves the authentication result into the HTTP session.

You can customize this login process at the following three specific time points, as illustrated in the diagram above:

Point ①: When pre-processing the assertion before validating the SAML response

Create a MySAMLAuthenticationProviderWrapper class that extends com.microstrategy.auth.saml.response.SAMLAuthenticationProvider and overrides the authenticate method.

Copy

public class MySAMLAuthenticationProviderWrapper extends SAMLAuthenticationProvider {
    @Override
    public Authentication authenticate(Authentication authentication) throws AuthenticationException {
        // >>>> Do your own work before saml assertion validation ---> Point ① in the above diagram
        Authentication auth =  super.authenticate(authentication);
        return auth;
    }
}

Configure your customized bean (Fully Qualified Class Name) in SAMLConfig.xml under the classes/resources/SAML/custom folder with the bean ID "samlAuthenticationProvider" and keep the original one, as shown below.

The two constructor arguments must be exactly the same as the original if you don't customize them.

Copy

<bean id="samlAuthenticationProvider" class="com.microstrategy.custom.MySAMLAuthenticationProviderWrapper">
        <property name="assertionValidator" ref="samlAssertionValidator"/>
        <property name="responseAuthenticationConverter" ref="samlResponseAuthenticationConverter"/>
</bean>

Point ②: When customizing the logic of authenticating the user

Create a MySAMLAuthenticationProviderWrapper class that extends com.microstrategy.auth.saml.response.SAMLAuthenticationProvider and overrides the authenticate method.

Copy

public class MySAMLAuthenticationProviderWrapper extends SAMLAuthenticationProvider {
    @Override
    public Authentication authenticate(Authentication authentication) throws AuthenticationException {
    
        Authentication authResult =  super.authenticate(authentication);
        
        // >>>> Do something after assertion validation while before iserver login ---> Point ② in the above diagram
        
        return new CustomAuthentication(authResult);
    }
}

The two constructor arguments must be exactly the same as the original if you don't customize them.

Copy

<bean id="samlAuthenticationProvider" class="com.microstrategy.custom.MySAMLAuthenticationProviderWrapper">
        <property name="assertionValidator" ref="samlAssertionValidator"/>
        <property name="responseAuthenticationConverter" ref="samlResponseAuthenticationConverter"/>
</bean>

Point ③: Doing some work before or after saving the authentication result into the HTTP session

Create a MySAMLProcessingFilterWrapper class that extends com.microstrategy.auth.saml.response.SAMLProcessingFilterWrapper and overrides the attemptAuthentication method.

Copy

public class MySAMLProcessingFilterWrapper extends SAMLProcessingFilterWrapper {
    @Override
    public Authentication attemptAuthentication(HttpServletRequest request, HttpServletResponse response) throws AuthenticationException {
        Authentication authResult = super.attemptAuthentication(request, response);
        // >>>> Do something after the user login ---> Point ③ in the above diagram
        return authResult;
    }
}

The two constructor arguments must be exactly the same as the original if you don't customize them.

Copy

<bean id="mstrSamlProcessingFilter" class="com.microstrategy.custom.MySAMLProcessingFilterWrapper">
    <constructor-arg ref="samlAuthenticationConverter" />
    <property name="authenticationManager" ref="authenticationManager" />
    <property name="authenticationSuccessHandler" ref="successRedirectHandler" />
    <property name="authenticationFailureHandler" ref="failureRedirectHandler" />
</bean>

Customize SAMLAssertion validation

To verify SAML 2.0 responses, SAMLProcessingFilter delegates authentication work to the samlAuthenticationProvider bean which is com.microstrategy.auth.saml.response.SAMLAuthenticationProviderWrapper.

You can configure this in the following ways:

Set a clock skew or authentication age for timestamp validation
Perform additional validation
Coordinate with UserDetailsService

Set a clock skew for timestamp validation

It is not uncommon for your web and IDP servers to have system clocks that are not perfectly synchronized. For that reason, you can configure the default SAMLAssertionValidator assertion validator with some tolerance.

Open the SAMLConfig.xml file under the classes/resouces/SAML/custom folder.

Set the responseSkew property to your customized value. By default, it is 300 seconds.

Copy

<bean id="samlAssertionValidator" class="com.microstrategy.auth.saml.response.SAMLAssertionValidator">
      <property name="responseSkew" value="300"/>
</bean>

Set an authentication age for timestamp validation

By default, the system allows users to single sign on for up to 2,592,000 seconds since their initial authentication with the IDP (based on the AuthInstance value of the authentication statement). Some IDPs allow users to stay authenticated for longer periods than this and you may need to change the default value.

Open the SAMLConfig.xml file under the classes/resouces/SAML/custom folder.

Set the maxAuthenticationAge property in the default SAMLAssertionValidator assertion validator to your customized value.

Copy

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

Perform additional validation

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

Validates the <AudienceRestriction> and <DelegationRestriction> conditions
Validates <SubjectConfirmation> s, except for any IP address information

While recommended, it’s not necessary to call super.convert(). You may skip this if you don’t need it to check the <AudienceRestriction> or <SubjectConfirmation> since you are doing those yourself.

Configure your own assertion validator that extends com.microstrategy.auth.saml.response.SAMLAssertionValidator.

Perform your own validation. For example, you can use OpenSAML's OneTimeUseConditionValidator to also validate a <OneTimeUse> condition.

Copy

public class MySAMLAssertionValidator extends SAMLAssertionValidator {
    @Override
    public Saml2ResponseValidatorResult convert(OpenSaml4AuthenticationProvider.AssertionToken token) {
        Saml2ResponseValidatorResult result = super.convert(token);
        OneTimeUseConditionValidator validator = ...;
        Assertion assertion = token.getAssertion();
        OneTimeUse oneTimeUse = assertion.getConditions().getOneTimeUse();
        ValidationContext context = new ValidationContext();
        try {
            if (validator.validate(oneTimeUse, assertion, context) == ValidationResult.VALID) {
                return result;
            }
        } catch (Exception e) {
            return result.concat(new Saml2Error(INVALID_ASSERTION, e.getMessage()));
        }
        return result.concat(new Saml2Error(INVALID_ASSERTION, context.getValidationFailureMessage()));
    }
}

Configure your customized bean (Fully Qualified Class Name) in SAMLConfig.xml under the classes/resources/SAML/custom folder with the bean ID "samlAssertionValidator" to replace the original one, as shown below.
Copy
```
<bean id="samlAssertionValidator" class="com.microstrategy.custom.MySAMLAssertionValidator">
        <property name="maxAuthenticationAge" value="2592000"/>
        <property name="responseSkew" value="300"/>
</bean>
```
To set properties, see how to set a clock skew or authentication age for timestamp validation.

Coordinate with UserDetailsService

If you would like to include user details from a UserDetailsService legacy, use the response authentication converter.

You are not required to call super.convert. It returns SAMLAuthentication containing the extracted attributes from AttributeStatement, as well as the single ROLE_USER authority.

Create a class that extends com.microstrategy.auth.saml.response.SAMLResponseAuthenticationConverter.

Inject your UserDetailService legacy.

Copy

public class MyResponseAuthenticationConverter extends SAMLResponseAuthenticationConverter {
    @Autowired
    UserDetailsService userDetailsService;
    @Override
    public AbstractAuthenticationToken convert(OpenSaml4AuthenticationProvider.ResponseToken responseToken) {
        SAMLAuthentication authentication = (SAMLAuthentication)super.convert(responseToken); // >>> ①
        Assertion assertion = responseToken.getResponse().getAssertions().get(0);
        String username = assertion.getSubject().getNameID().getValue();
        UserDetails userDetails = this.userDetailsService.loadUserByUsername(username);// >>> ②
        return MySaml2Authentication(userDetails, authentication);// >>> ③
    }
}

Call super.convert, which extracts attributes and authorities from the response.
Call UserDetailService using the relevant information.
Return a custom authentication that includes the user details.
Configure your customized bean (Fully Qualified Class Name) in SAMLConfig.xml under the classes/resources/SAML/custom folder with the bean ID "samlResponseAuthenticationConverter" to replace the original one, as shown below.
Copy
```
<bean id="samlResponseAuthenticationConverter" class="com.microstrategy.custom.MyResponseAuthenticationConverter"/>
```