Creating a Custom External Security Module (ESM)

The External Security Module (ESM) is the mechanism used for MicroStrategy Web authentication. An ESM is always invoked during page execution when a MicroStrategy session is required for a request and there is no session available. The specific ESM that is invoked is determined by the value of the externalSecurityClass parameter specified in the microstrategy.xml configuration file. To use a custom ESM, you must create a class that implements the ExternalSecurity interface and specify that MicroStrategy Web should use the custom ESM, rather than the default ESM shipped with MicroStrategy Web.


The logic in a custom implementation of the ESM can perform one or more of the following actions:



An ESM is a Java class that implements the ExternalSecurity interface. A custom ESM uses the methods in this interface to perform the actions listed above. The specific methods used and the values passed in to and returned by each method vary, depending on exactly what actions the custom ExternalSecurity class intends to perform. Refer to Common ESM Customizations for other examples of how these interfaces and methods can be used to perform common customizations.


The two most common reasons that users customize MicroStrategy authentication are:


Single Sign-on

The most common reason to customize authentication is to provide single sign-on (SSO) functionality. SSO allows enterprise network users to access MicroStrategy Web content and functionality seamlessly on the basis of a single authentication that is performed when they initially access the network or the application controlling enterprise authentication. Single sign-on enables smooth integration of MicroStrategy Web with portal applications, identity management systems, and other Web and third-party applications.

MicroStrategy Web has built-in SSO support for Windows NT and Integrated (Kerberos) authentication, as well as several portal server applications and identity management systems. Refer to the
Enterprise Portal Integration Help online product manual for more information about SSO in supported portal server applications.


Supported portal server applications include:



Supported identity management systems include:



You can use a custom ESM to create your own trusted authentication mechanism for identity management systems that are not supported and to add additional authorization criteria to both supported and unsupported systems.

User Mapping

Another common reason for custom authentication is user mapping. In this process a user enters a set of log-in credentials for a known system, and these credentials are automatically mapped to MicroStrategy credentials. This is useful for situations when you want a user to connect to MicroStrategy Web with a different user ID from the one by which he or she is recognized in your external user repository. With user mapping, users can log into MicroStrategy Web using the log-in credentials for a known system and, transparently to them, the correct MicroStrategy user ID associated with these credentials is used to obtain access to MicroStratgey Web. This allows businesses to use their traditional user credentials, while still providing a seamless SSO experience for users using MicroStrategy Web. It can also be used to shield users from specific knowledge of their MicroStrategy log-in credentials.

As an example of user mapping, assume that you have a user whose name is John Armstrong. His user ID in your external user repository is "JohnA", but his user profile (along with its related privileges) needed to access MicroStrategy Web is "JArmstrong". This type of situation can occur when MicroStrategy has been in place for some time before an external user repository is established. To resolve this difference, a mapping must occur between the user ID provided when the user logs into the system, and the different user ID required by MicroStrategy Web. This mapped relationship between the two user IDs can be saved in an external database, or it can be programmatically calculated based on your business requirements. In this example, the user logs in to your system as '"JohnA", and the user profile "JohnA" is passed on to MicroStrategy Web when the user requests access to it. The mapping takes place, the correct credentials are provided to MicroStrategy Web, the user is authenticated, and processing continues without the user being asked for MicroStrategy credentials.