Setting Up and Using the Single Sign-On Sample

Single sign-on (SSO) is a mechanism that allows users to access all the computers and systems to which they have permission by a single action of user authentication and authorization—without having to log in separately for each system. SSO normally requires a centralized identity management system or authentication server to validate user identities, determine which resource users have permission to access, and then pass the authentication information on to the requested application and establish a session for the user.

 

To illustrate a typical simple single sign-on scenario, the MicroStrategy SDK includes a Single Sign-on (SSO) Sample. This sample has two basic parts:

 

 

The SSO Sample is useful if you want an identity management application to provide the authentication for your MicroStrategy Web users. In this case, when a user requests a MicroStrategy Web page, the identity management application authenticates the user, checks to see if he or she has access to MicroStrategy Web, and if so sends the request to MicroStrategy Web with a token. MicroStrategy Web must be able to use this token to validate the user and handle the request. The code in the custom ESM class in the Single Sign-on Sample provides an example of how to do this.

 

In order for this ESM to work properly, any initial request to MicroStrategy Web must include a parameter corresponding to the authentication server token. This parameter is normally passed as part of the URL. The name of this parameter must be defined in ssoesm.properties (default is SSO_TOKEN_NAME), and the value must be the token returned from the authentication server. If a MicroStrategy Intelligence Server session does not exist and an authentication server token is not found in the request or is not valid, then the ESM tells MicroStrategy Web to redirect the request to a custom login page. This custom login page is also defined in ssoesm.properties (default is CUSTOM_LOGIN_URL). Finally, the ssoesm.properties file must define a URL that is used to authenticate the authentication server token (default is SSO_URL).

 

The sample authentication server provided as part of this sample handles login and authentication.

 

 

You can use this sample as the basis for creating your own single sign-on environment that uses a third-party-provided authentication mechanism. You can customize and extend the External Security class in this sample to meet your requirements, modify the properties file as required, and replace the sample web application with the real authentication server used in your production environment.

 

Note: The External Security Sample Application was included in prior versions of MicroStrategy SDK, but it was packaged— and, thus, installed— differently. The installation directions in this topic apply only to the sample application packaged as a plug-in.

 

The sections below describe how to set up and use the Single Sign-on Sample. Two other topics— SSO Sample: Custom ESM Code Explanation and SSO Sample: Custom Properties File— describe the code in the custom ESM class and the properties file.
 

Setting Up the Single Sign-on Sample

The file needed for this sample are provided in a plug-in, called SSOSample, which is located in the CustomizationPlugins/AdvancedScenarios folder insides the SDK installation directory. Just as you do with any customization plug-in, you must copy the SSOSample plug-in to the plugins folder inside your MicroStrategy Web installation directory.

 

This plug-in contains the following files.

 

 

A sample web application that simulates an authentication server in the SSO Sample is also provided. This file is called sso.war. To set  up the SSO Sample, deploy the sso.war file (located by default in the samples\java\sso folder inside the MicroStrategy SDK installation) to your application server. This sample application acts as the authentication server for the SSO Sample.
 

Note: In order to use the sample as-is, the sso.war file (that is, the sample authentication server) must be deployed to a Tomcat server on the same machine where MicroStrategy Web is installed. If the WAR file is deployed to a different machine, the values in the custom properties file must be changed to reflect the different location.

Using the Single Sign-on Sample

To test the functioning of the SSO Sample, do the following:

 

  1. Open a browser and request the login page of the sample web application, login.jsp. For example, if you deployed the application on your local machine with 8080 as the port number, use the following URL to invoke the login page:
     

http://localhost:8080/sso/jsp/login.jsp

 

When the login page opens, replace YOUR_ISERVER in the URL under MicroStrategy Page Requested to the name of the computer where your MicroStrategy Intelligence Server is installed.

SSOSample_Init.gif

 

  1. Log in to the authentication server using valid authentication credentials that have access to the authentication server. In this sample, log in as test1/test1.

    SSOSample_Auth.gif
     

The user account with a userID of test1 and a password of test1 is a valid account on the authentication server and is also authorized to use MicroStrategy Web. When you enter these credentials and click "Login", the requested MicroStrategy Web page is displayed.

SSOSample_reportPage.gif
 

  1. Close the browser and reopen it, again requesting the login page of the sample web application, login.jsp. (Follow the instructions in step 1 above to open the page and modify the URL to add your Intelligence Server location.)
     

  2. Log in to the authentication server using valid authentication credentials that do not have access to MicroStrategy Web. In this sample, log in as test2/test2.
     

The user account with a userID of test2 and a password of test2 is a valid account on the authentication server but is not authorized to use MicroStrategy Web. When you enter these credentials and click "Login", the login page is displayed with a note at the top indicating that authorization failed and this user account was denied access to MicroStrategy Web.

SSOSample_NoAuth.gif

 

  1. Close the browser and reopen it, again requesting the login page of the sample web application, login.jsp. (Follow the instructions in step 1 above to open the page and modify the URL to add your Intelligence Server location.)
     

  2. Log in to the authentication server using invalid authentication credentials. In this sample, you can log in as anything other than test1/test1 or test2/test2. For example, you can log in as test3/test3.
     

Any user account other than  test1/test1 or test2/test2 is an invalid account on the authentication server. When you enter any such credentials and click "Login", the login page is displayed with a note at the top indicating that this is an invalid user account and login has failed.

SSOSample_LoginFail.gif