MicroStrategy ONE

Customizing user mapping

This example demonstrates how to customize authentication if you use a third-party identity provider with SAML authentication and you need to set additional user properties. The MicroStrategy Intelligence Server uses the SAML assertion attributes configured in the identity provider for authentication. This information is passed from the SAML response and used to try to map the logged-in user to MicroStrategy users and groups stored in the metadata. When the Intelligence Server receives a login request from SAML, there are two possible scenarios:

  • The user already exists in the Intelligence Server metadata

    In this case, the Intelligence Server updates the existing user in the metadata with information from SAML.

  • The user does not exist in the Intelligence Server metadata

    In this case, the Intelligence Server creates a new user in the metadata based on information from SAML.

By default, the Intelligence Server creates users with the following properties: Name, Display Name, Distinguished Name, and Email.

Customizing user mapping requires some Java programming. You make changes to an XML configuration file, but you also make changes to a Java class file. You write custom Java code that sets additional user properties received in the SAML assertion. In this customization, you add the Full Name and Description properties for users.

To help you get started, we have provided a sample project that you can download. It contains the files used to perform this customization. You can use the code in the files as the basis for creating your own customization.

This customization can be used only with SAML authentication mode.

Prerequisites

  • MicroStrategy Library is deployed

  • MicroStrategy Library is configured to use SAML

  • MicroStrategy Intelligence Server is running
  • You use an external identity provider where the SAML Assertion attributes are configured
  • You have Java programming experience

Java and XML files used for the customization

  • SAMLUserMapper.java

  • SAMLConfig.xml

To see what the customization code looks like and try out the customization in MicroStrategy Library, follow the instructions below.

  1. Download the sample project and extract the contents.
  2. Generate the files that perform the customization.
    1. Open the sample project in Eclipse.

    2. Configure the project for your environment.

      1. Open Project Properties -> Java Build Path -> Libraries.

      2. In the Libraries pane, change the location for the following JAR files so that they point to those JARs in your environment.

        • javax.servlet-api-3.1.0.jar
        • restful-api-1.0-SNAPSHOT-jar-with-dependencies.jar

    3. Customize the code in the two files that perform the customization—the Java class for the custom bean and the XML configuration file. You can use the files in the sample as-is or you can do your own customization. For example, you can add different code to the Java class for the custom bean, and you can also change the name of the custom bean class and the out-of-the-box bean that it will override.

      • SAMLUserMapper.java is the Java class for the custom bean. It contains custom code that extends user mapping functionality. In this customization, you write custom Java code that sets the Full Name and Description properties for users—in addition to the default out-of-the-box properties—when users are created.

      • SAMLConfig.xml is the configuration file that injects the custom code into the application. It tells MicroStrategy Library to override a specified out-of-the-box bean with a specified custom bean at runtime. In the code sample below, SAMLUserMapper, the Java class you created above, overrides the out-of-the-box class, samlIServerCredentialsProvider.

        Copy 
        <?xml version="1.0" encoding="UTF-8"?>
        <beans xmlns="http://www.springframework.org/schema/beans"
               xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
               xmlns:context="http://www.springframework.org/schema/context"
               xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans-4.1.xsd
               http://www.springframework.org/schema/context http://www.springframework.org/schema/context/spring-context-4.1.xsd">
            <!-- Override IServer credentials provider with custom bean -->
          <bean id="samlIServerCredentialsProvider"class="com.microstrategy.custom.auth.sample.mapper.SAMLUserMapper" />
            <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="samlGroupParser" />
            <!-- Bean responsible for mapping user groups to roles -->
            <property name="roleBuilder" ref="samlRoleBuilder"/>
            <property name="fullNameAttribute" value="fullName"/>
            <property name="descriptionAttribute" value="description"/>
            <property name="adminUserName" value="administrator"/>
            <property name="adminPwd" value=""/>
          </bean>
        </beans>
    4. Build the project.
  3. Use the customization in MicroStrategy Library.
    1. Deploy your MicroStrategy Library application.
    2. Copy the customization files from the project you built to your Library installation directory:
      • Copy SAMLUserMapper.class to the WEB-INF\classes\com\microstrategy\custom\auth\trusted folder.
      • Copy SAMLConfig.xml to the WEB-INF\classes\auth\custom folder.

    3. Restart MicroStrategy Library.

      When new users are created, they will now include the Full Name and Description, in addition to Name, Display Name, Distinguished Name, and Email.