handlesAuthenticationRequest

The handlesAuthenticationRequest method gets called when a request comes in for a page that requires the user to be logged in and there is no valid session on MicroStrategy Intelligence Server. This method tells MicroStrategy Web how to handle the authentication request. This method is invoked during both the default and custom External Security workflow.

The conditions that cause this method to be invoked include:

• A user is logging in for the first time, and a valid session has not yet been established.  

• A user has logged in and logged out, and the existing session has been closed.  

• A user has logged in, but the existing session has timed out due to inactivity.  

• A user is logging in for the first time, and the login-first preference is set, indicating that a login-first template is needed.

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

• Method signature  

• Parameters  

• Return values  

• Pre-conditions  

• Post-operations

Method signature

public int handlesAuthenticationRequest(RequestKeys reqKeys, ContainerServices cntSvcs, int reason)

Parameters

The following parameters are passed into the handlesAuthenticationRequest method:

• reqKeys

  This parameter allows the ESM to inspect information present in the original request. This information represents a collection of cookie, URL, and FORM data key/value pairs, together with information from session variables.  

• cntSvcs

  This parameter provides a way for the ESM to directly interact with the container to do such things as inspecting or setting session variables and other data values not exposed through the RequestKeys object.  

• reason

  This parameter informs the ESM 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 no longer valid 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. A login-first session must exist or be created in order for the Welcome page to display the list of all available projects for a particular user. This is a special case, which applies only when login-first is enabled. A login-first session is not an actual session on Intelligence Server, but instead a template that will be used when an actual Intelligence Server session is created later in the authentication workflow. To create a login-first session, you need a valid set of credentials.

Return values

The following values can be returned by the handlesAuthenticationRequest method:

• USE_MSTR_DEFAULT_LOGIN  (default)

  Continues with MicroStrategy's default authentication process in one of the two following ways: if credentials have not yet been collected, redirects to the standard MicroStrategy Web log-in page for collecting user credentials; if credentials have already been collected, continues with processMSTRLoginForm.

• USE_CUSTOM_LOGIN_PAGE

  Indicates that credentials will be gathered by an external application and triggers a call to the getCustomLoginURL method, which returns the URL of the custom log-in page to which processing should be redirected.

• COLLECT_SESSION_NOW

  Delegates the creation of a session to the ESM, triggering a call to the getWebIServerSession method. It is the responsibility of the ESM to determine how to create the session.

Pre-conditions

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

• An Intelligence Server user session is required to access a specific resource, and such a session cannot be found. This happens during the initial request by a user.  

• An Intelligence Server user session exists, but it has expired. This happens during subsequent requests by a user.  

• A login-first session template is required to retrieve the list of available projects for a user, but it cannot be found. This happens during the initial request by a user.

Post-operations

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

• If this method returns USE_MSTR_DEFAULT_LOGIN, the application redirects to the MicroStrategy Web Login page. (default)  

• If this method returns USE_CUSTOM_LOGIN_PAGE, the application calls getCustomLoginURL.  

• If this method returns COLLECT_SESSION_NOW, the application calls getWebIServerSession.