Restricting the Number of Open User Sessions

This scenario illustrates how to create a custom External Security Module (ESM) that restricts user access based on the number of concurrent open user sessions. While the specific example used in this customization prevents users from having more than two sessions open concurrently, this setting is variable and can be set to whatever number is appropriate in a given environment. The code explanation for this example and the steps in this scenario can be used as a basis for applying any type of additional authorization criteria you choose. in each case, you simply include additional authorization criteria to the isRequestAuthorized method, which is called with every request.

For help in understanding how to perform this customization, the following information is provided for you:

Prerequisites for this authentication customization use case
Instructions for creating the custom External Security Module with the Web Customization Editor
Testing this authentication customization use case
Work-flow for this authentication customization use case

Prerequisites for this authentication customization use case

The work-flow for this custom authentication scenario assumes that there is no existing session for the user making the request and that you have done the following:

Created a custom error page, if desired, to be used if a failure occurs.
Created and compiled a custom ExternalSecurity java class that includes code to add additional authorization criteria— in this example, based on user group and system time.
Created a custom properties file— that specifies the maximum allowable number of concurrent open sessions per user— and saved it in the MicroStrategy Web installation directory, either under the WEB-INF/classes folder or under the plugins/<plugin name>/WEB-INF/classes folder.

Instructions for creating the custom External Security Module with the Web Customization Editor

This customization can be accomplished using either of the following methods:

Deploying the plug-in provided with MicroStrategy SDK
Using the Web Customization Editor to create a plug-in

Deploying the plug-in provided with MicroStrategy SDK

MicroStrategy SDK provides a plug-in (ZIP file) that can simply be extracted to the plugins folder to view the customization in MicroStrategy Web. The following steps guide you in locating the plug-in and deploying it.

Access the plug-in: JSP version.
Extract the plug-in to the plugins subfolder inside the MicroStrategy Web installation folder.
Launch MicroStrategy Web to view the customization.

Using the Web Customization Editor to create a plug-in

MicroStrategy SDK provides a Web Customization Editor that can be used to create a customization plug-in that performs your ESM customization. The following steps guide you in creating the plug-in and deploying it.

Launch the Web Customization Editor.
Create a new plug-in and give it a meaningful name, such as RestrictingOpenSessions.
Exit the Web Customization Editor.
Create a custom Java class that extends AbstractExternalSecurity, which implements the ExternalSecurity interface. Package it in com.microstrategy.sdk.samples.externalsecurity. This custom class must include code to import the necessary MicroStrategy runtime libraries and override the isRequestAuthorized method, as explained below.:
- Override the isRequestAuthorized method so that it checks the number of concurrent open user sessions, compares this to the maximum setting in the properties file, and grants or denies access to the application based on whether the currently requested session would exceed the maximum setting.
For this scenario, a sample java file— called RestrictOpenSessions.java is available in the plug-in provided by MicroStrategy SDK. You can use this sample class to see the results of this type of customization and as a model for how to create your own custom class. See Code Explanation for Restricting User Sessions Scenario for a detailed explanation of how to write the code required in the custom ESM class.

Compile and save RestrictOpenSessions.class in the appropriate package structure (in this example, com.microstrategy.sdk.samples.externalsecurity) under the plugins/RestrictingOpenSessions/WEB-INF/classes folder in the MicroStrategy Web installation directory.

If you used a different plug-in name from the one suggested in this scenario, the path referenced above should reflect your plug-in name.
Create a custom properties file called configSessionRestrictions.properties and save it in the MicroStrategy Web installation directory under the plugins/RestrictingOpenSessions/WEB-INF/classes folder. The properties file should contain one line that looks like this:
Copy
```
validSessionsPerUser=2
```
The line shown above sets the maximum number of concurrent open sessions that will be allowed for any named user. In this example, the maximum number is sets as "2", but it can be set to any value. The maximum value set here will be used to set the value of a variable in the RestrictOpenSessions ESM class.
If the Web Customization Editor is closed, launch it again and access your plug-in.
Click on MicroStrategy Web Configuration inside the Application Settings view to expand the hierarchical tree. The expanded list comprises the different settings that can be modified to perform customizations.
Expand Web Configuration Settings and double-click MicroStrategy Configuration Settings.
Click the Application Settings tab at the bottom of the page. For the entry in the External Security Class field under Application Settings, browse to the custom External Security class you saved in step 4 above.
Save your changes.
Launch MicroStrategy Web to view the customization.

The next time that you open MicroStrategy Web, the application uses your custom External Security class, instead of the default class.

For specific settings that affect whether customization changes are applied automatically or require a restart of the Web server, see Applying customization changes to the application.

Testing this authentication customization use case

Once you have met the prerequisites and performed the steps listed above, you are ready to test this customization.

Open MicroStrategy Web in a web browser and click the link for MicroStrategy Tutorial. The default log-in page should be displayed.
Log in with valid MicroStrategy credentials for either an administrator or a non-administrative user, and you should be granted access to the application.
Now, open another MicroStrategy Web session in a new web browser and again click the link for MicroStrategy Tutorial. The default log-in page should be displayed.
Log in with the same credentials that you used to log in the first time. Again, you should be granted access to the application.
Open a third MicroStrategy Web session in a third web browser and click the link for MicroStrategy Tutorial. The default log-in page should be displayed.
Log in with the same credentials that you used to log in the two previous times. This time you should be denied access to the application because you are allowed to have only two open sessions per user in this example.
ClickLogouton the first browser. This will close that session.
Now, go back to the third browser (the one you opened in step 5) and try again to log in. Log in with the same credentials that you used to log in all of the previous times. This time you will be granted access to the application since you have only one other session open.

Work-flow for this authentication customization use case

The steps below explain what is happening as the custom ESM attempts to determine whether the user is authorized to have access to the application.

A user makes a request for a MicroStrategy Web page from a Web client, and MicroStrategy Web determines that the page requires authentication and that a valid session does not exist for the user (that is, there is no session ID).
MicroStrategy Web creates an instance of the custom ExternalSecurity class specified in microstrategy.xml, calls the handlesAuthenticationRequest method on this class, and passes in NO_SESSION_FOUND to the method, which returns USE_MSTR_DEFAULT_LOGIN.
USE_MSTR_DEFAULT_LOGIN redirects processing to the default MicroStrategy Web log-in page.
The user enters the requested information on the default log-in page and submits it.
The information is passed to MicroStrategy Web, and it invokes the processMSTRLoginForm method, which authenticates the user.
MicroStrategy Web calls the isRequestAuthorized method on the custom ESM, which has been customized to restrict access to users based on certain criteria— in this example, allowing users to have only two open sessions.
- If an error occurs during this process, the getFailureURL method is invoked and no session is created on Intelligence Server.
- If no error occurs during this process, the additional authorization criteria are applied and access is granted or denied based on the number of open sessions the user has.