processMSTRLoginForm

The processMSTRLoginForm method gets called if the implementation of the handlesAuthenticationRequest method returns USE_MSTR_DEFAULT_LOGIN (which is the default return value for this method) and user credentials are part of the request (that is, there is a log-in form to process). The processMSTRLoginForm method provides access to the form fields supplied in a default MicroStrategy Web log-in request and is essential if a custom ESM intends to use the default MicroStrategy Web log-in page and custom user mapping. This method is invoked during both the default and custom External Security workflow, although it performs no actions during the default workflow.

Two common scenarios in which this method is used in a custom implementation of the ESM are:

• Mapping the supplied credentials to another set of user credentials (that is, user mapping)

  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.  

• Monitoring the users that access MicroStrategy Web (that is, user monitoring)

  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.

The following information is provided to help you use this method when you create a custom External Security Module.

• Method signature  

• Parameters  

• Return values  

• Pre-conditions  

• Post-operations

Method signature

public boolean processMSTRLoginForm(RequestKeys reqKeys, ContainerServices cntSvcs, LoginForm loginForm, int reason)

Parameters

The following parameters are passed into theprocessMSTRLoginFormmethod:

• reqKeys

  This parameter gives the External Security Module access to the posted form data.  

• cntSvcs

  This parameter gives the External Security Module access to additional information related to the Web container and the originating request.  

• loginForm

  This parameter supplies the data collected from the form, which MicroStrategy Web uses to initialize a LoginForm object.

• reason

  This parameter informs the External Security Module why the authentication request is being made. It has one of the following values:
  

  • NO_SESSION_FOUND

    This reason is passed in if MicroStrategy Web is unable to find an existing session.  

  • SESSION_CLOSED

    This reason is passed in if the current session is not valid any more because it was closed, either explicitly or through an inactivity time-out. In this case, the ESM can attempt to correct the session problem by asking the user for a new set of credentials or taking some other action. This is a subsequent request, rather than the initial request by a user.  

  • LOGIN_FIRST

    This reason is passed in if a login-first session is needed. This applies only when login-first is enabled. In this case, a session template must exist or be created in order for the Welcome page to display the list of all available projects.

Return Values

The processMSTRLoginForm method returns a boolean value indicating whether the data supplied in the log-in form was valid and it can be used to construct a WebIServerSession object.

• true (default)

  The data provided is valid and it can be used to create a session on MicroStrategy Intelligence Server. The application continues to execute normally.

• false

  Authentication failed and no session is created for the user. The authentication failure sequence is executed.

External Security Modules that are not interested in the default MicroStrategy Web log-inform and its processing merely return 'true'.

Pre-conditions

This call is made only when both of the following conditions are true:

• The handlesAuthenticationRequest method returns USE_MSTR_DEFAULT_LOGIN and  

• The request includes the values for the fields on the default MicroStrategy Web log-in form.  

Post-operations

The following operations take place after the method call has finished, based on the return value:

• If this method returns 'false', the application calls the getFailureURL method, passing in authentication failure as the reason.  

• If this method returns 'true', the application calls the LoginForm.getWebIServerSession method and continues processing as indicated by the code in that method.