MicroStrategy ONE

External Security Module

An External Security Module (ESM) is a stand-alone Java class, which is an integral part of the MicroStrategy Web architecture. During the authentication workflow, whenever a page is requested that requires the user to be logged in with Intelligence Server, MicroStrategy Web invokes an implementation of the ESM. The ESM is always invoked the first time that a user makes a request for a MicroStrategy Web page that requires a session, in order to authenticate the user and create a user session on Intelligence Server. By default, the application invokes DefaultExternalSecurity, but it can be configured to invoke a custom ExternalSecurity class. Using a custom ESM allows you to integrate existing external security mechanisms and policies into MicroStrategy Web without having to modify any of the original source code.

The default ESM, DefaultExternalSecurity, simply directs the MicroStrategy Web application to return the default MicroStrategy login page. The MicroStrategy Web application itself is responsible for using the information entered on that page to authenticate the user, determine whether the user is authorized to perform the requested operation, and— if authentication and authorization are successful— create and manage a user session on Intelligence Server. A custom ESM can mimic this process and add only minimal additional logic, or it can customize all of the work that is normally done by MicroStrategy Web application— including gathering information on a custom login page, providing the logic to use this information to perform authentication and authorization, and creating and managing a session on Intelligence Server— and perform other actions not normally done during default authentication— such as mapping user credentials and monitoring application usage.

Customizing the Authentication Workflow using a Custom ESM

The initial sequence of pages that are displayed to the user during the authentication workflow— for both "login first" and "show projects first" — is the same for both the default ESM and a custom ESM. The difference between the two begins after the handlesAuthenticationRequest method has been called. When you create a custom implementation of the ESM, you should use the information in the Authentication Workflow topic, as well as the diagrams and explanations in the individual topics in the Creating a Custom External Security Module book, as a reference.:

A custom implementation of the ESM can provide minimal or extensive customization of the authentication process. The logic in a custom ESM can be used to do the following:

  • Present a custom login page  

  • Authenticate a user with credentials passed in and create a session  

  • Validate a user with a token passed in— in conjunction with an external application— and create a session  

  • Authenticate a user with a session state passed in and restore a session  

  • Map one set of user credentials to another set of credentials:

    With an out-of-the-box MicroStrategy portlet, mapping of credentials is not performed by the ESM. Instead, it is performed by the portal using a user-level repository, such as a credentials vault or user mapping file, or by the portlet using a custom credentials mapper class. The custom ESM provided with the out-of-the-box MicroStrategy portlet is used only to ask the user to refresh the portlet if the session times out.  

  • Manage sessions in a non-standard way  

  • Apply additional authorization criteria, on top of the criteria that MicroStrategy uses by default:

    For example, a custom ESM can limit the amount of interaction a user can have in a single session based on the number of HTTP requests.  

  • Gather information about who is using MicroStrategy Web

See Customizing Authentication for a detailed explanation of the methods available to a custom ESM and Common External Security Module Customizations for specific examples of how to implement the actions listed above.