ExternalSecurity Interface

To customize MicroStrategy Web authentication, you must create a custom Java class that implements the ExternalSecurity interface. The ExternalSecurity interface and classes derived from it contain all the methods that are used to provide authentication and authorization functionality. To help you in this process, MicroStrategy Web provides an abstract base class— AbstractExternalSecurity— that mimics the standard authentication process of MicroStrategy Web.

In default MicroStrategy Web authentication, the DefaultExternalSecurity class is used. This class extends the AbstractExternalSecurity class (without any changes), which in turn implements the ExternalSecurity interface.

The diagrams below illustrate the three methods that are entry points to the External Security Module (ESM) and show where each of the other methods fits in the workflow. The only method that is not pictured is getFailureURL(), which is called in various places whenever there is an error.

The ExternalSecurity interface includes the following methods:

• handlesAuthenticationRequest()

  Called automatically whenever a request is made to the application that requires a session and no valid session can be found.
  Returns a value indicating the action that should take place next - opening the standard MicroStrategy log-in page, getting the URL for a custom log-in page, or delegating to the ESM the creation of the WebIServerSession object. 

• processMSTRLoginForm()

  Called only when handlesAuthenticationRequest() returns USE_MSTR_DEFAULT_LOGIN and the user has entered credentials on the default MicroStrategy Web log-in page or credentials have been passed in the URL.
  Returns a boolean value indicating whether the data supplied in the log-in form was successfully used to construct a WebIServerSession object.  

• getCustomLoginURL()

  Called only when handlesAuthenticationRequest() returns USE_CUSTOM_LOGIN_PAGE.
  Returns a string representing the URL of a custom page that handles the authentication request. It is the responsibility of the ESM to construct and return a URL that points to the appropriate custom log-in page. 

• getWebIServerSession()

  Called only when COLLECT_SESSION_NOW is returned by handlesAuthenticationRequest()during custom authentication and not when using the default MicroStrategy Web authentication process.
  Returns a WebIServerSession object that can be used to establish valid communication with the Intelligence Server. 

• canReconnectSession()

  Called immediately after a new valid session is created (during the workflow that follows when handlesAuthenticationRequest returns USE_MSTR_DEFAULT_LOGIN or COLLECT_SESSON_NOW) if the user preferences used to create this session do not match the user preferences stored in the metadata and this session includes the information necessary to reconnect.
  Returns a boolean value indicating whether to disconnect a valid session and attempt to reconnect using the user preferences stored in the metadata. 

• getFailureURL()

  Called when authentication or authorization fails.
  Returns a string representing a URL that points to a custom error page. If this method returns NULL, the MicroStrategy Web default error page is displayed. 

• isRequestAuthorized()

  Called automatically on every request.
  Returns a boolean value indicating whether the user making the request is authorized to perform the requested action. 

• closeSessionOnLogout()

  Called only when the user explicitly logs out from the system.
  Returns a boolean value indicating whether sessions should be closed during log-out.

Each of the following topics in this section describes one of the methods listed above, the conditions under which that particular method is invoked, and the manner in which MicroStrategy Web interprets the code returned by the method. Each topic also describes the conditions that must be met prior to invoking the method and the operations that take place following the method call, and provides the method signature.

The diagrams provided in the topics in this section represent the general processing flow and are not intended to be actual flow diagrams.