Validating the Session during Page Execution

At this point in page execution, if it is necessary, the application retrieves the current session. Most of the pages in the application require that a valid session is established with MicroStrategy Intelligence Server before they can be displayed, and many settings, such as browser settings, preferences, and features, depend on the current session. The session is established when the user logs into the application.

When a user submits a request and is authenticated, an instance of a session object is created in MicroStrategy Intelligence Server memory and an ID referring to that session object is passed back to the application via the  Web API. This ID, called the session ID, is simply a security token. The application stores the session ID for the remainder of the session so that the user may use it in subsequent operations. The location of the session ID is based on security settings, and it can be stored in such places as the URL, cookies, or the session variables. Each time the same user makes another request, the session ID is passed with the request to identify the user’s session object. The session ID expires when the user logs out or a time-out is exceeded.

Click on any box in the diagram to see a detailed explanation of that step in page execution. Click here to return to the Overview of Page Execution.

In addition to the default session creation behavior, you can use the External Security Module to customize how sessions are created, persisted, and reused by MicroStrategy Web products. The module is a plug-in that integrates your security mechanism and policies into the application without forcing you to modify any of the original source code. After the application retrieves the user's login credentials, it sends the credentials to the External Security Module, which then performs authentication according to the rules that you have written. These rules may rely on having non-MicroStrategy credentials mapped to MicroStrategy credentials. Once the credentials are validated, the External Security Module returns a valid MicroStrategy login to the application, which passes the value to the Web API.

In a portal environment, you must create a factory object, read the session properties from the portlet properties/credentials vault, retrieve the Intelligence Server session, and retrieve the saved session from the portlet properties.

Customization

Customizing whether a page requires a valid session requires only a simple change to an XML parameter file, while modifying the actual creation of the session and authentication of the user requires Java programming.  

To customize whether a page requires a valid session, you simply change the login-required attribute for the page in the Page Configuration file, pageConfig.xml.

<page default="true"login-required="true" name="-1" persist-mode="8" track="false">

However, when you customize the authentication process, you must create a custom External Security Module (ESM). The Java code in the ESM retrieves the user's credentials, MicroStrategy project, and MicroStrategy Intelligence Server information from the URL, your external user repository, or some other information storage container. In addition, you must have MicroStrategy runtime libraries because you will be using the Web API to make a TCP/IP call directly to Intelligence Server. (When you make the TCP/IP call to MicroStrategy Intelligence Server, the password is automatically encrypted.)

In a portal environment, your custom implementation must manage the request for and the persistence of a valid MicroStrategy session ID, whether the persistence is accomplished using HTML form parameters, cookies, or through the Web server's session variables. The custom implementation must also manage the closing of MicroStrategy sessions when the user logs out so that session resources are released.

Problem solving at this step in page execution

Problems at this stage in page execution are generally the result of the user not being logged in or the session having timed out, both of which mean that a valid session does not currently exist. In certain circumstances when a valid session does not exist (for example, when the desktop has been idle too long and the session has timed out), the application is able to reestablish a session, and execution can continue normally. In general, however, if a session does not exist and cannot be recreated, the application throws an exception and redirects execution to the Login page. (All errors that can originate from an invalid session are defined in errors.xml with "login" as their target page.) Sometimes, the application writes information to the error log and includes the stack trace of the error as a comment in the HTML source for the Login page.  

The process for validating the session and handling errors related to missing or invalid session IDs is the same, regardless of whether the application or a custom External Security Module is responsible for authenticating the user. At any point in session validation where a session needs to be created, the application will query the module to find out what to do. For example, the module might specify that it should create the session, or it might specify that the default session creation behavior should be used.

The application asks the following questions and, based on the answers, proceeds as indicated in the table below.

You can use the error information generated by the application to help resolve problems that arise when you customize session creation and user authentication. Logging information can be viewed in the log file. See Error Handling for a more detailed discussion of error handling in MicroStrategy Web products, and see Logging Architecture for more information about error logging.

t is a good practice to validate XML configuration and layout definition files before starting MicroStrategy Web. Eclipse and other IDEs provide a way to validate these files.

Next step in page execution

After the target page has been selected, the next step in page execution is creating and initializing instances of the beans on the page.

See also

• Adding Extra Arguments to All Links