MicroStrategy ONE

Session Creation and Management

In a MicroStrategy Web environment, the existence of a valid user session on MicroStrategy Intelligence Server is synonymous with authentication. In the standard authentication workflow, MicroStrategy Web is responsible for creating a user session on Intelligence Server, but when you customize authentication, you are generally responsible for session creation. To successfully accomplish this, you need to understand how a MicroStrategy user session is created and managed, as well as how MicroStrategy Web connects to Intelligence Server to create and validate a session.

Creating, managing, and validating a MicroStrategy session for custom authentication includes passing the necessary information to Intelligence Server, authenticating the user, determining if the user is authorized to perform the requested operation, managing the session, closing the session, and passing the appropriate information— such as the session state or ID— back to MicroStrategy Web. Custom authentication also allows you to perform actions such as mapping one set of credentials to another, monitoring application usage, or applying additional authorization criteria.

When you create a session, you must set all of the required preferences on the session, such as working set size and search working set size. Failure to do so may result in error messages or unexpected behavior. Refer to Customizing Authentication for a more detailed explanation of how to create a session using a custom External Security Module.

Session creation

The MicroStrategy platform is designed to centralize all authentication at the Intelligence Server layer. This makes the authentication behavior uniform across all clients, whether they come from MicroStrategy Web, Desktop, Narrowcast Server, or from a custom application. Intelligence Server, rather than MicroStrategy Web, performs authentication, and if it is successful, a user session is created on Intelligence Server. This gives the user access to MicroStrategy Web functionality and interaction with the metadata and warehouse data.

 A session is the context of an active user within the MicroStrategy system and is used to verify the user’s permissions and privileges. An open session consumes and remains in memory on Intelligence Server until the user exits the system by logging out or until the session times out due to inactivity.

Every open session in Intelligence Server is uniquely identified by a GUID, referred to as the session ID. When a user successfully logs in to Intelligence Server from MicroStrategy Web, Intelligence Server creates and stores the session and its identifying session ID and returns the session state to the Web client. While the session ID is used by the back-end every time a connection is needed, the session state is passed between the Web client and the Web server. This allows Intelligence Server to remain aware that the user has already been authenticated so that MicroStrategy Web does not have to re-authenticate the user as it continues to receive requests from the same user. For example, when an authenticated user attempts to execute a report, among the parameters passed as part of the request are the report ID and the user's session state. The session ID provides Intelligence Server with all of the information it needs to determine the user's privileges, permissions, and object access rights.

In a custom application or when a custom authentication procedure is used instead of the default MicroStrategy Web authentication process, the custom implementation must manage the request for and the persistence of a valid MicroStrategy session state, 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 or sharing of MicroStrategy sessions when a user logs out so that session resources are released or provided to another user. By default, MicroStrategy Web uses session variables to store the session, but in custom authentication, you can store the session elsewhere, such as in cookies.

Sample code for creating a session is provided for you under samples/java/SessionManagementSample.java in the MicroStrategy SDK installation directory.

Session management

The Intelligence Server session ID signifies that a user has been authenticated to use MicroStrategy Web functions and content. A layered structure of Web API objects (in the Web Objects layer) act as wrappers to this session ID and provide access to different aspects of Intelligence Server session information.

When a user logs into Intelligence Server, it creates a session identified by a session ID and returns the session state, which can then be used in subsequent requests to prove to Intelligence Server that the user has been authenticated. Based on the session state, Intelligence Server is aware of every aspect of this user’s session— that is, who the user is, the project to which he is logged in, and so on.

You cannot directly access most of this project information from the Web XML API through the session ID. For example, you cannot give the Web XML API a session ID and retrieve the name of the project that is associated with that session ID. Instead, you use the following two interfaces, which were created to store a session ID and provide access to session properties directly from the Web application.

  • WebSessionInfo

    Exposes generic properties, such as the session ID that forms the core of this definition, as well as the associated user name and password. For details on this object, refer to the API Reference.  

  • WebIServerSession

    Exposes Intelligence Server-specific properties, such as the MicroStrategy Intelligence Server name and port used to connect, as well as the project name. For details on this object, refer to the API Reference.

Technically, the WebSessionInfo and WebServerSession are not two separate wrapper classes since they are both interfaces of the same class implementation.

Connecting to Intelligence Server

The MicroStrategy Web XML API communicates with Intelligence Server using TCP/IP-based socket connections. A pool of socket connections is created upon connecting to an Intelligence Server (via either autoconnect or the MicroStrategy Web Administration GUI) and that pool is used for all requests to that specific Intelligence Server. Connections in the pool are used as needed, and the pool can grow if demand exceeds the available supply of connections, assuming that the limit on the maximum number of connections has not been reached. There is no socket-to-session relationship, so a session can use various sockets in the pool for different requests.

When a user tries to connect to a project in Intelligence Server, MicroStrategy Web attempts to reserve a connection from the Web server to Intelligence Server for that particular request. If a connection already exists and it is idle, that connection is used. If a connection does not exist or all existing connections are busy, a new connection is created and used, provided that the maximum number of connections allowed is not exceeded.

While the request is being processed, the connection is in a busy state and is not available for other requests. Once the request is completed, the connection is returned to an idle state, indicating that it is waiting to be used by a request from the MicroStrategy Web XML API. Keeping the connection open in an idle state, rather than destroying it, improves performance.

The maximum number of connections that may be made to an Intelligence Server (per web server) is configurable through the MicroStrategy Web Administration GUI.