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.

• Mapping the user-supplied credentials to credentials in an external user repository 

• Providing different login pages for different projects 

• Customizing the "look and feel" and/or functionality of the login page 

• Presenting a different start page for users in different user groups 

• Implementing single sign-on 

• Applying additional authorization criteria 

• Monitoring the users that access MicroStrategy Web 

• Keeping track of individual requests in order to perform usage analysis or other type of statistics 

• Optimizing session creation by reusing sessions

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. 

• Mapping the user-supplied credentials to credentials in an external user repository

  The credentials entered on the log-in page are replaced with other credentials, either by mapping them to the IDs of different users or doing some extra processing to retrieve them from a different database. For example, the user name and password entered on the log-in form can be treated as an employee account and mapped to a MicroStrategy Intelligence Server user name and password. In this case, the session object is modified. The default MicroStrategy log-in page and the default session creation mechanism are used, but additional custom code is used to map one set of user credentials to another.:

  Methods overridden:  processMSTRLoginForm:

  Scenario:  See Mapping Credentials using an External Repository.:

  Code explanation:  See Code Explanation for Mapping Credentials Scenario.

• Providing different login pages for different projects:

  Methods overridden:  handlesAuthenticationRequest:

  Scenario:  See Displaying Different Login Pages based on Project.

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

• Customizing the "look and feel" and/or functionality of the login page:

  This use case describes the situation when you want the log-in page to have a distinct "look and feel" that reflects your specific business requirements or environment or when you need greater flexibility—for what information is gathered, what operations take place, how sessions are handled, and how log-in credentials are used for authentication.:

  Methods overridden:  handlesAuthenticationRequest:

  getCustomLoginURL:

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

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

• Presenting a different start page for users in different user groups:

  Methods overridden:  handlesAuthenticationRequest:

  getCustomLoginURL

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

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

• Implementing single sign-on:

  This use case describes the situation when another application, such as a portal or an identity management system, supplies the log-in page and the logic to process the user credentials, create a session on Intelligence Server, and return to MicroStrategy Web. This allows you to provide users with a single sign-on experience.:

  The handlesAuthenticationRequest method returns COLLECT_SESSION_NOW, instead of a default or custom login page, and the getWebIServerSession method has full control over how and when the session is created.:

  Methods overridden:  handlesAuthenticationRequest:

  getWebIServerSession

  Scenario:  See Setting Up and Using the 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.

• Applying additional authorization criteria

  Methods overridden:  isRequestAuthorized  

  • Scenario:  See Restricting Access during Certain Times.:

    Code explanation:  See Code Explanation for Restricting  Access Scenario.
    

  • Scenario:  See Restricting the Number of Open User Sessions.:

    Code explanation:  See Code Explanation for Restricting User Sessions Scenario.

• Monitoring the users that access MicroStrategy Web

  The credentials entered on the login page can be parsed to know who logged in and to determine whether the user is permitted access to the application. For example, a company can enable access only during work hours and restrict it at all other times. In this case, the session object is not modified, but information is captured.:

  Methods overridden:  processMSTRLoginForm

• Keeping track of individual requests in order to perform usage analysis or other type of statistics:

  Methods overridden:  isRequestAuthorized 

• Optimizing session creation by reusing sessions:

  When one user releases a session by logging out, this same session ID is provided to another user. In this case, the method returns a false value, which causes the session object to be deleted from the current user, but the connection with the project and Intelligence Server to be kept alive. This is useful when the custom application is built to reuse the same pool of sessions. This can helpful, for example, when a technical support person uses an existing session to trouble-shoot problems. By reusing the same session, the working set remains the same and there is no need to provide credentials again.:

  Methods overridden:  closeSessionOnLogout   

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.