Spring Security SAML Customization for MicroStrategy Web and Mobile

MicroStrategy ONE (June 2024) includes a Spring Security SAML provider upgrade to 6.2. This major upgrade includes deprecated classes and methods. The following topic illustrates the SAML workflow and beans you can leverage for customization.

SAML Login Workflow

The diagrams and workflows below illustrate how authentication-related requests are handled with different authentication configurations. The following points should be considered when using these workflow diagrams:

Double-line arrows represent HTTP requests and responses and single-line arrows represent Java cells.
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 action not directly involved in request authentication are not included. Each request passes through multiple Spring Security filter, as described in Configuration files and bean classes.

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 redirects to /saml/authenticate by default.

The redirect is designed to support a multi-tenants sceanrio. 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 Descriptions

Bean ID	Java Class	Description
`mstrEntryPoint`	`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.web.Saml2WebSsoAuthenticationRequestFilter`	By default, this filter responds to the `/saml/authenticate/**` endpoint and the result is a redirect that includes a `SAMLRequest` parameter that contains the signed, deflated, and encoded `<saml2:AuthnRequest>`

Customization

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

Prior to /saml/authenticate Redirect

To customize before /saml/authenticate/ redirect:

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 a mstrEntryPoint bean ID to replace the existing bean:

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

<bean id="mstrEntryPoint" class="com.microstrategy.custom.MySAMLEntryPoint">
    <constructor-arg value="/saml/authenticate"/>
</bean>
```

Prior to SSO IDP Redirect

To customize before the SSO IDP redirect:

Create a MySAMLAuthenticationRequestFilter class that extends org.springframework.security.saml2.provider.service.web.Saml2WebSsoAuthenticationRequestFilter and override the doFilterInternal method.

Execute your code before calling super.doFilterInternal:

Copy

public class MySAMLAuthenticationRequestFilter extends Saml2WebSsoAuthenticationRequestFilter {
    @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/resources/SAML/custom folder with a mstrSamlAuthnRequestFilter bean ID to replace the existing bean:

The constructor argument must be exactly the same as the original, if it is not customized.
Copy
```
<bean id="mstrSamlAuthnRequestFilter" class="MySAMLAuthenticationRequestFilter">
    <constructor-arg ref="samlAuthenticationRequestContextResolver"/>
</bean>
```

Customize the AuthnRequest Object

The AuthnRequest object is constructed by mstrSamlAuthnRequestFilter as a part of the SAML request. If you want to customize the AuthnRequest object before it is sent to SSO IDP, you can extend SAMLAuthenticationAuthnRequestCustomizer:

In previous releases, AuthnRequest customization is performed by extending SAMLAuthenticationRequestContextConverter, which is deprecated and removed in MicroStrategy ONE (June 2024) in favor of SAMLAuthenticationAuthnRequestCustomizer.

Create a MyAuthnRequestCustomizer class that extends com.microstrategy.auth.saml.authnreques.SAMLAuthenticationAuthnRequestCustomizer and override the extent method:

Copy

package com.microstrategy.custom.auth;
import ...;
public class MyAuthnRequestCustomizer extends SAMLAuthenticationAuthnRequestCustomizer {
    @Override
    public void accept(OpenSaml4AuthenticationRequestResolver.AuthnRequestContext authnRequestContext) {
        super.accept(authnRequestContext);
        AuthnRequest authnRequest = authnRequestContext.getAuthnRequest();
        // Add your AuthnRequest customization here...
    }
}

Configure your customized bean (Fully Qualified Class Name) in SAMLConfig.xml under the classes/auth/custom folder with an authnRequestCustomizer bean ID to replace the existing bean:
Copy
```
<bean id="authnRequestCustomizer" class="com.microstrategy.custom.auth.MyAuthnRequestCustomizer"/>
```

Generate <saml2:Response>

SSO redirects the user to the MicroStrategy Web application. The redirect request contains a SAML assertion that describes 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 then calls the Intelligence server credentials provider to build an Intelligence server credentials object from the SAML assertion information.
The mstrSamlProcessingFilter bean saves the authentication object in the HTTP session.
The SAML processing filter calls the login success handler, which redirects the browser to the original request.

Bean Descriptions

Bean ID	Java Class	Description
`mstrSamlProcessingFilter`	`com.microstrategy.auth.saml.response.SAMLProcessingFilterWrapper`	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 the SAML assertion.
`userDetails`	`com.microstrategy.auth.saml.SAMLUserDetailsServiceImpl`	This bean is responsible for creating and populating an `IServerCredentials` instance that defines 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

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

You can perform the following customizations:

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

Retrieve More Information from SAMLResponse

The mstrSamlProcessingFilter bean is the first layer that directly accesses the SAML response. The bean accepts the raw HttpServletRequest, which contains the samlResponse, and produces SAMLAuthenticationToken. It is then passed to SAMLAuthenticationProviderWrapper to perform authentication validation in later steps.

To extract more information from HttpServletRequest:

MicroStrategy recommends that you create a MySAMLConverter class that extends the com.microstrategy.auth.saml.response.SAMLAuthenticationTokenConverter class.
Override the convert method and call super.convert, which can get com.microstrategy.auth.saml.response.SAMLAuthenticationToken, a subclass of Saml2AuthenticationToken.

Extract the information from the raw request, then return an instance that is a subclass of 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 samlAuthenticationConverter bean ID.

The constructor argument must be exactly the same as the original, if it is not customized.
Copy
```
<bean id="samlAuthenticationConverter" class="com.microstrategy.custom.MySAMLConverter">
    <constructor-arg ref="saml2AuthenticationConverter"/>
</bean>
```

Customize the Login Process

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

You can customize this login process at the following three time points:

Point 1: 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/resouces/SAML/custom folder with a samlAuthenticationProvider bean ID and keep the existing bean:

The two constructor arguments must be exactly the same as the original, if it is not customized.

Copy

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

Point 2: When Customizing the Logic of User Authentication

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 auth =  super.authenticate(authentication);
        // >>>> Do something after assertion validation while before iserver login ---> Point ② in the above diagram
        return new CustomAuthentication(authResult);
    }
}

Configure your customized bean (Fully Qualified Class Name) in SAMLConfig.xml under the classes/resources/SAML/custom folder with a samlAuthenticationProvider bean ID and keep the existing bean:

The two constructor arguments must be exactly the same as the original, if it is not customized.

Copy

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

Point 3: Doing Work Before or After Saving the Authentication Result in 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;
    }
}

Configure your customized bean (Fully Qualified Class Name) in SAMLConfig.xml under the classes/resources/SAML/custom folder with an mstrSamlProcessingFilter bean ID and keep the existing bean:

The constructor argument and properties 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" />
    <property name="requiresAuthenticationRequestMatcher" ref="samlSsoMatcher" />
</bean>

Customize SAMLAssertion Validation

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

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 common for your web and IDP servers to have system clocks that are not perfectly synchronized. You can configure the default SAMLAssertionValidator assertion validator with some tolerance.

Open the SAMLConfig.xml file under the classes/auth/custom folder.

Set the responseSkew property to your custom 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 of time and you may need to change the default value.

Open the SAMLConfig.xml file under the classes/auth/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, the spring SAML framework:

Validates the <AudienceRestriction> and <DelegationRestriction> conditions.
Validate <SubjectConfirmation>, expect for any IP address information

MicroStrategy recommends to call super.convert(). You can skip this call if you don't need it to check the <AudienceRestriction> or <SubjectConfirmation> since you are checking 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/auth/custom folder with the samlAssertionValidator bean ID to replace the existing one:

Copy

<bean id="samlAssertionValidator" class="com.microstrategy.custom.MySAMLAssertionValidator">
        <property name="maxAuthenticationAge" value="2592000"/><!-- 30 days -->
        <property name="responseSkew" value="300"/>
</bean>

To set properties, see Set a Clock Skew for Timestamp Validation or Set an Authentication Age for Timestamp Validation.

Customize Intelligence Server Credentials Object with the SAML Assertion Information

You can overwrite SAMLUserDetailsService to customize Intelligence server credentials.

To make adjustments on Intelligence server credentials that you created, extend com.microstrategy.auth.saml.SAMLUserDetailsServiceImpl:

Create MySAMLUserDetailsService by extending the SAMLUserDetailsServiceImpl interface and implement methods:

Copy

package com.microstrategy.custom.auth;
import ...;
public class MySAMLUserDetailsService extends SAMLUserDetailsServiceImpl {
    @Override
    public Object loadUserBySAML(SAMLCredential samlCredential) throws UsernameNotFoundException {
        SAMLIServerCredentials iServerCredentials = (SAMLIServerCredentials) super.loadUserBySAML(samlCredential);

        // customize iserver credentials object with saml credential object and other config properties

        return iServerCredentials;
    }
}

Configure your customized bean (Fully Qualified Class Name) in SAMLConfig.xml under classes/resources/SAML/custom folder with the userDetails bean ID and keep the existing bean:

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

Copy

<bean id="userDetails" class="com.microstrategy.custom.auth.MySAMLUserDetailsService">
    <!-- SAML Attribute mapping -->
    <property name="displayNameAttributeName" value="DisplayName" />
    <property name="dnAttributeName" value="DistinguishedName" />
    <property name="emailAttributeName" value="EMail" />
    <property name="groupAttributeName" value="Groups" />

    <!-- Parser for user group information -->
    <property name="groupParser" ref="groupParser" />
    <!-- Bean responsible for mapping user groups to roles -->
    <property name="roleBuilder" ref="roleBuilder"/>
</bean>

To construct Intelligence server credentials on your own, directly implement com.microstrategy.auth.saml.SAMLUserDetailsService:

Create MySAMLUserDetailsService by implementing SAMLUserDetailsService interface and implement methods:

Copy

package com.microstrategy.custom.auth;
import ...;
public class MySAMLUserDetailsService implements SAMLUserDetailsService {
    @Override
    public Object loadUserBySAML(SAMLCredential samlCredential) throws UsernameNotFoundException {
        SAMLIServerCredentials iServerCredentials = new SAMLIServerCredentials();

        // customize iserver credentials object with saml credential object and other config properties
        iServerCredentials.setUsername(samlCredential.getNameID().getValue());

        return iServerCredentials;
    }

    @Override
    public void loadSAMLProperties(SAMLConfig samlConfig) {
        // load attributes from MstrSamlConfig.xml from start up, so that it could be utilized by `loadUserBySAML(...)`
    }
}

Configure your customized bean (Fully Qualified Class Name) in SAMLConfig.xml under the classes/resources/SAML/custom folder with the userDetails bean ID and keep the existing bean:
Copy
```
<bean id="userDetails" class="com.microstrategy.custom.auth.MySAMLUserDetailsService">
```