Authentication Workflow in MicroStrategy Web

Authentication takes place after a user submits a request to view a MicroStrategy Web page that requires a session and before the request is handled by the page. There are two default authentication workflows— one that requires a user to log in first before seeing the list of projects available to that user and another that shows the list of all available projects first and then requires the user to log in once a project has been selected. For both workflows, the user enters the appropriate user credentials on the default login page and specifies the authentication mode to be used (if the administrator has enabled more than one authentication mode), but the sequence of pages displayed and when and how the methods in the ESM are invoked differ for each workflow.

Both workflows are illustrated and described below. Each assumes that a user is accessing MicroStrategy Web for the first time and that MicroStrategy Web is using the default implementation of the External Security Module (ESM). it is important to understand the default workflows before you customize them.

Authentication Workflow with Project List First

The diagram below illustrates the sequence of pages in the default authentication workflow when the user is allowed to view the list of all projects, including projects to which the user does not have access, before logging in. This is the default option and can be set on the MicroStrategy Web Administrator page by first choosing Intelligence Servers -> Default properties on the left side of the screen and then, in the Login section on the right side of the screen, selecting "Show all the projects connected to the Web Server before the user logs in" from the Project list drop-down list.

The following steps take place during this "show projects first" workflow. The handlesAuthenticationRequest method of the ESM is invoked two times, using the same reason.

A user opens MicroStrategy Web, submitting a request for a MicroStrategy Web page. Because the administrator has set the option to allow users to view all of the available projects before logging in (the "show projects first" option), there is no project filtering based on the actual user and thus there is no requirement for a login-first session at this point. As a result, the request does not trigger a call to the handlesAuthenticationRequest method of the ESM. The WELCOME page opens, displaying all of the available projects.
Once the user selects a specific project on the WELCOME page, the application must determine whether the user has access to the selected project. Since the user must be authenticated to do this and no session has been established yet, MicroStrategy Web makes a call to the handlesAuthenticationRequest method, using NO_SESSION_FOUND as the reason. The ESM returns USE_MSTR_DEFAULT_LOGIN, and since there are no credentials in the request, the user is redirected to the LOGIN page

No page in MicroStrategy Web explicitly redirects a user to the LOGIN page. This page is displayed only because the session manager is unable to access a valid session for the user.
The LOGIN page opens. Because the LOGIN page does not require an active session in order to be accessed, there is no call to the ESM at this point. The user enters his or her credentials and submits them to the Web server.
At this point, a second call is made to the handlesAuthenticationRequest method, again using NO_SESSION_FOUND as the reason. The ESM returns USE_MSTR_DEFAULT_LOGIN and now, since there are credentials in the request, the application attempts to validate them. If validation is successful, the credentials are used to create a new session.
Once the user session is created on Intelligence Server, the user is redirected to the specified starting page in MicroStrategy Web. By default, the DESKTOP page is displayed (that is, the DESKTOP page is specified as the default starting page). Because a session has already been created at this point, there are no calls to the handlesAuthenticationRequest method.
After a user session has been created on Intelligence Server, a user can browse to any page and there are no additional calls to the handleAuthenticationRequest method unless the session expires because of inactivity or is explicitly closed. If this happens, MicroStrategy Web again calls the handlesAuthenticationRequest method, using SESSION_CLOSED as the reason.

Authentication Workflow with Login First

The diagram below illustrates the sequence of pages in the default authentication workflow when the user must login before being able to see the list of projects to which he or she has access. This option must be set on the MicroStrategy Web Administrator page by first choosing Intelligence Servers -> Default properties on the left side of the screen and then, in the Login section on the right side of the screen, selecting "Login, then show the projects accessible by the supplied login" from the Project list drop-down list.

The following steps take place during this "login first" workflow. The HandlesAuthenticationRequest method of the ESM is invoked three times, using two different reasons.

A user opens MicroStrategy Web, submitting a request for a MicroStrategy Web page. Because the administrator has set the option to require users to login before viewing the list of projects to which they have access (the "login first" option), a call is made to the handlesAuthenticationRequest method, using LOGIN_FIRST as the reason. The ESM returns USE_MSTR_DEFAULT_LOGIN, and since there are no credentials in the request, the user is redirected to the LOGIN page.

No page in MicroStrategy Web explicitly redirects a user to the LOGIN page. This page is displayed only because the session manager is unable to access a valid session for the user.
The LOGIN page opens. Because the LOGIN page does not require an active session in order to be accessed, there is no call to the ESM at this point. The user enters his or her credentials and submits them to the Web server.
At this point, a second call is made to the handlesAuthenticationRequest method, again using LOGIN_FIRST as the reason. This time, however, the request includes credentials so the application attempts to validate them. If validation is successful, the credentials are used to populate a login-first session object, a special type of session object that is used as a template for credentials and is not connected to any particular project. At this point, an actual user session has not yet been established with Intelligence Server.
The WELCOME page opens, displaying only those projects to which the user has access. Since the WELCOME page requires only valid credentials to fetch those projects that are associated to a user, the application can use the values in the login-first session object and does not need to make a call to the ESM. This is a special case.
When the user selects a project on the WELCOME page, MicroStrategy Web requires a user session for that project. Since a session has not been created yet, the application makes a third call to the handlesAuthenticationRequest method, this time using NO_SESSION_FOUND as the reason. At this point, an actual user session is created on Intelligence Server by the main servlet, and the user is redirected to the specified starting page in MicroStrategy Web. By default, the DESKTOP page is displayed (that is, the DESKTOP page is specified as the default starting page).
After a user session has been created on Intelligence Server, a user can browse to any page and there are no additional calls to the handleAuthenticationRequest method unless the session expires because of inactivity or is explicitly closed. If this happens, MicroStrategy Web again calls the handlesAuthenticationRequest method, using SESSION_CLOSED or NO_SESSION_FOUND as the reason respectively.

The authentication workflow takes place during the Selecting the Page and Validating the Session steps of page execution.