MicroStrategy ONE

Mapping Credentials using an External Repository

This scenario illustrates how to create a custom External Security Module (ESM) that validates a set of user-supplied non-MicroStrategy login credentials against an external user repository and then maps validated credentials to a corresponding set of MicroStrategy Intelligence Server credentials. The default MicroStrategy log-in page is used to collect the user credentials, but custom code is added to validate these user credentials, map them to their equivalent MicroStrategy credentials, and create a session on Intelligence Server.

This customization is useful when the login credentials for your users are different from those needed to connect to MicroStrategy Web and you want them to have a seamless login/single sign-on experience. In this example, the credentials used to connect to MicroStrategy Web are validated against credentials stored in a sample Access database, but it is easy to modify the code to use any external database housing your user credentials.

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, the user logs in with credentials other than MicroStrategy credentials and expects to be given access to MicroStrategy Web without being asked for additional credentials, and that you have done the following: 

  • Created a custom error page, if desired, to be used if a failure occurs. 

  • Set up an Access database as the external user repository. :

    A simple Access database is used as an example of an external repository in this sample customization, but the repository in a production environment would probably be a more industrial strength database.

  • Created and compiled a custom ExternalSecurity java class that includes code to validate the credentials entered on the default log-in page against an external user repository and map them to MicroStrategy credentials.

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

  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 processMSTRLoginForm method, as explained below.:

    • Override the processMSTRLoginForm method so that it validates the credentials entered by the user against an external repository and maps them to MicroStrategy credentials.

    For this scenario, a sample java file—called UserMapping.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 Mapping Credentials Scenario for a detailed explanation of how to write the code required in the custom ESM class.  

    Compile and save UserMapping.class in the appropriate package structure under the plugins/MappingCredentials/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 an external user repository, called ExternalSecurity.mdb.

    A sample Microsoft® Access database, which already includes log-ins, is provided for you. This is a simple database that contains columns for valid user names and the passwords associated with these user names. This sample database is provided for you by default under samples/java/externalsecurity in the MicroStrategy SDK installation directory. CopyExternalSecurity.mdbto the location of your choice and create a System DSN, called ESMSample, that points to this database. 

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

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

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

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

  10. Save your changes. 

  11. 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 listed above, you are ready to test your customization. Open MicroStrategy Web in a Web browser and click the link for the MicroStrategy Tutorial project. Try the following scenarios to verify that users are being correctly authenticated against the external database. 

  1. Supply a valid user ID and password combination from the database. Your log-in credentials should be mapped automatically to valid MicroStrategy user credentials so that your log-in is successful. 

  2. Log out and then try to log back in using the log-in credentials of an actual MicroStrategy user. This log-in should be denied because there is no mapping to valid MicroStrategy user credentials in your custom ESM. 

  3. Finally, log out and then try to log in with credentials that are not supported by your external user database and are not the log-in credentials of an actual MicroStrategy user. Again, this log-in should fail.

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 (that is, there is no session ID). 

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

  3. USE_MSTR_DEFAULT_LOGIN redirects processing to the default MicroStrategy Web log-in page. 

  4. The user enters the requested information on the default log-in page and submits it.:

    These are not MicroStrategy credentials.

  1. The information is passed to MicroStrategy Web, and it  invokes the processMSTRLoginForm method on the custom ESM, which has been customized to perform user validation against credentials stored in an external repository and then map the validated credentials to MicroStrategy credentials. 

  2. The processMSTRLoginForm method gives the ESM access to the form fields supplied in a standard MicroStrategy log-in request. In the custom ESM, you override this method with code that validates the log-in credentials against an external user repository rather than passing the values from the LoginForm directly to Intelligence Server. You also add code that maps validated credentials to their equivalent MicroStrategy credentials. 

    • 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 user is authenticated and a session is created on Intelligence Server.