Using a Custom ESM: Single Sign-on Sample

ESM does not support SAML authentication.

MicroStrategy Web provides out-of-the-box support for three identity management applications—CA SiteMinder, IBM Tivoli Access Manager, and Oracle Identity Manager—as well as a customization technique for adding a new single sign-on provider. These single sign-on (SSO) solutions work in an environment in which the identity management application is a trusted authentication provider (that is, no validation is required) and the MicroStrategy metadata has been configured to store the identity management application login name for each valid MicroStrategy user.

The Single Sign-on (SSO) Sample illustrates a different way to implement single sign-on when MicroStrategy Web is used with an identity management application. In this sample, a custom External Security Module (ESM) contains the logic to confirm whether or not a user has been successfully logged in by an authentication server and is a valid MicroStrategy user. To accomplish this, the code in the custom ESM class retrieves a token that has been passed in the URL and validates it using the sample authentication server provided as part of this sample. (In a production environment, the token would be validated using the API of the existing identity management application.) If the token is valid, the ESM creates a new MicroStrategy Intelligence Server session and returns the newly created session to MicroStrategy Web. If the token is invalid, the ESM tells MicroStrategy Web to redirect the user to a custom login page.

The ESM in this sample does not force you to do the validation of the token, but it provides the ability if you want to validate it.

The custom ESM—together with a properties file and an error messages file—are included in a plug-in called SSOSample, which is located under the CustomizationPlugins/AdvancedScenarios folder in the SDK installation directory. The files for the sample authentication server are packaged in a WAR file called SSO.war, which is located in the root of the same plug-in.

The following topics explain how to set up and use the SSO Sample. They also provide a detailed explanation of the code in both the custom ESM class and the properties file to help you customize these files for your specific environment and requirements.

• Setting Up and Using the SSO Sample

  This topic explains how to set up the SSO Sample and provides instructions for using it.

• SSO Sample: Custom ESM Code Explanation

  This topic explains the code in each method  or inner class of the custom External Security class used in the SSO Sample.

• SSO Sample: Custom Properties File

  This topic explains the properties that are used by the custom External Security class in the SSO Sample.  

Refer to Retrieving and validating a token for a description of how to tailor the code in the SSO Sample to your environment.

The plug-in for this sample works in both a J2EE and a .NET environment., but the sample authentication server provided as part of this sample must be deployed to a Tomcat server on the same machine in order for the sample to work as-is. If the sample authentication server is deployed to a different machine, the values in the properties file must be changed to reflect the different location.