Common External Security Module Customizations

The ExternalSecurity interface can be implemented in a number of ways to create a custom External Security Module (ESM). The recommended approach is to extend the AbstractExternalSecurity class, which contains default implementations, so that you need to write code only for the methods that you are overriding.


The ExternalSecurity interface has eight methods, which can be overridden with custom code to provide a variety of customizations. The most common ESM customizations are listed below.



A brief explanation of the general use case and the specific customization for each of these common ESM customizations is provided below, together with a list of the methods that must be overridden, a link to a scenario that walks you through the high-level steps of making the customization, and another link to a topic that provides a detailed explanation of the code needed to create the custom ESM and any other custom file that is required, such as a custom login page.



Code explanation: See Code Explanation for Different Login Pages Scenario.




Scenario:  See Creating a Session from a Custom Login Page.

Code explanation:  See Code Explanation for Custom Session Creation Scenario.




Scenario:  See Displaying Different Start Pages based on User Group.

Code explanation: See Code Explanation for Different Start Pages Scenario.



Methods overridden:  handlesAuthenticationRequest



Scenario:  See Single Sign-on Sample.


Code explanation:  See Single Sign-on Sample.

Related topics:  See Retrieving and validating a token and Retrieving and mapping a UserID to a MicroStrategy user.



Methods overridden:  isRequestAuthorized 









General guidelines for ESM customization

A custom External Security Module that handles MicroStrategy Web authentication and session creation is responsible for providing a valid session to MicroStrategy Web and redirecting to the appropriate page (custom login page or error page) when a session cannot be created.

You can use an external application— such as a portal server, identity management system, or other third-party application— to validate and create sessions. You must have MicroStrategy runtime libraries as part of the external application if it handles session creation. When you create a session, you are using the MicroStrategy API to make a TCP/IP call directly to Intelligence Server to create the session. When you make this call to Intelligence Server, the password is automatically encrypted.


If you create custom URL parameters, be sure they are named and defined intuitively and that the same names are used within the ESM code that handles the requests. You can add parameter definitions to the code itself as comments, or keep definitions in a separate file. Be sure that your naming convention does not use reserved terms, such as uid, that are already used by MicroStrategy Web.