MicroStrategy ONE

Displaying Different Start Pages based on User Group

This scenario illustrates how to create a custom External Security Module (ESM) that displays different start pages based on the user group to which the user belongs. It also illustrates how to create a custom log-in page that performs all of the work required to authenticate the user, including collecting and processing credentials and creating a user session on Intelligence Server.

This customization is useful when you want the start page that is displayed to be tailored to the user who is logged on, presenting information related to the functions performed by the group to which the user belongs. For example, you might want users in the Human Resources department to see one page when they log on, sales personnel to see an entirely different page, and corporate executives to see yet another page. To accomplish this, you use a custom login page that— in addition to collecting credentials, authenticating users, and creating sessions— also determines the appropriate start page to display for users who have successfully logged on.

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

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 invoke a custom login page, rather than the default login page. 

  • Created a custom login page that includes code to gather and pass the user credentials and any other necessary information, create a session on Intelligence Server, and determine the start page to display by determining the group to which the user belongs.

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

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. 

  1. Access the plug-in: JSP version. 

  2. Extract the plug-in to the plugins subfolder inside the MicroStrategy Web installation folder.  

  3. 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.

  1. Launch the Web Customization Editor. 

  2. Create a new plug-in and give it a meaningful name, such as  DisplayingDiffStartPages. 

  3. Exit the Web Customization Editor. 

  4. 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 handlesAuthenticationRequest and getCustomLoginURL methods, as explained below.:

    • Override the handlesAuthenticationRequest method so that it returns USE_CUSTOM_LOGIN_PAGE. 

    • Override the getCustomLoginURL method so that it returns the URL of a custom login page. (This custom login page collects user credentials, creates a session, determines the group to which the user belongs, redirects to the appropriate start page, and puts the session and other necessary information in the URL.)

    For this scenario, a sample file— called DiffStartPages.java is available in the plug-in provided by MicroStrategy SDK. You can use this sample class to see the results of this specific customization and as a model for how to create your own custom class. See Code Explanation for Different Start Pages Scenario for a detailed explanation of how to write the code required in the custom ESM class.

    Compile and save DiffStartPages.class, with the proper package folder structure, under the plugins/DisplayingDiffStartPages/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.

  5. Create a custom login page that collects credentials, creates a session, and determines the appropriate start page to display for users who are successfully logged in, based on user group.:

    For this scenario, a sample login page— called DiffStartPagesCustLoginPage.jsp is available inside the jsp folder of the plug-in provided by MicroStrategy SDK. You can use this sample page to see the results of this specific customization and as a model for how to create your own custom page. See Code Explanation for Different Start Pages Scenario for a detailed explanation of how to write the code required in the custom login page.:

    Save DiffStartPagesLoginPage.jsp under the plugins/DisplayingDiffStartPages/jsp 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.

  1. If the Web Customization Editor is closed, launch it again and access your plug-in. 

  2. 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. 

  3. Expand Web Configuration Settings and double-click MicroStrategy Configuration Settings. 

  4. 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.

  5. Save your changes. 

  6. 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.

  1. In MicroStrategy Desktop, create start pages for two user groups - "Customers" and "Managers". To accomplish this, do the following:

    1. Open MicroStrategy Desktop and connect to the Project Source.

      1. In the left-hand pane, choose Administration -> User Manager -> Customers.

        • In the right-hand pane, double-click the user, "Edward Perryman", and the User Editordialog opens.

        • On the User Editor dialog, click Groups and check the Web Usersgroup to give "Edward Perryman" Web User privileges.

      2. In the left-hand pane, choose Administration -> User Manager -> Managers.:

        • In the right-hand pane, double-click the user, "PRose", and the User Editor dialog opens.

        • On the User Editordialog, click Groups and check the Web Users group to give "PRose" Web User privileges.

    2. In the left-hand pane, chooseMicroStrategy Tutorial -> Public Objects -> Reports:

      • In the right-hand pane, right-click and chooseNew -> Folderfrom the context menu. Create a folder called "Customers" and add one report to it. This can be any report. Simply drag an existing report from any folder and drop it into the new "Customers" folder you just created.

      • In the right-hand pane, right-click and chooseNew -> Folderfrom the context menu. Create another new folder called "Managers" and add two reports to it. These can be any reports. Simply drag two existing reports from any folder and drop them into the new "Managers" folder you just created.

  2. Open MicroStrategy Web in a Web browser, and the custom log-in page should be displayed.

  3. Enter the name of the machine where you installed MicroStrategy Web as the Server Name and "MicroStrategy Tutorial" as the Project Name. Enter "Edward Perryman" as the User Name and leave the Password blank. Click Login, and the MicroStrategyShared Reports page should be displayed. Because Edward Perryman is a part of the "Customers" user group, the start page should contain only the one report that you added above.

  4. Log out and login again. Enter the name of the machine where you installed MicroStrategy Web as the Server Name and "MicroStrategy Tutorial" as the Project Name. Enter "PRose" as the User Name and leave the Password blank. Click Login, and the MicroStrategyShared Reportspage should be displayed. Because PRose is a part of the "Managers" user group, the start page should contain the two reports that you added above.

Work-flow for this authentication customization use case

The steps below explain what is happening as the custom ESM attempts to authenticate a user and create a session.

  1. 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.:

    MicroStrategy Web always checks first to see if there is an existing session. If it is still valid, there is no need to authenticate the user again and processing continues. The following steps are only performed if the user needs to be authenticated— that is, the first time the user logs in or when an existing session has been closed or timed out.

  2. MicroStrategy Web creates an instance of the 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_CUSTOM_LOGIN_PAGE. 

  3. USE_CUSTOM_LOGIN_PAGE invokes the getCustomLoginURL method. 

  4. The getCustomLoginURL method returns the URL of a custom log-in page. 

    • If an empty string or NULL is returned, the getFailureURL method is invoked. 

    • If the URL returned is bad, HTTP Status Code 404 is returned from the Web server. 

    • If the URL returned is good, the application redirects the user to the custom log-in page, which can be internal or external to MicroStrategy Web. 

  5. The user enters the requested information on the custom log-in page and submits it.  

  6. If the user submits the correct credentials information, the custom login page creates a MicroStrategy Web IServer Session, determines the group to which the user belongs and redirects to the appropriate start page for that group, and places the session state in the URL using the usrSmgr parameter. Since a valid session state is passed to MicroStrategy Web, the user is given permission to access the appropriate start page.