Retrieving and Validating a Token

This single sign-on implementation is typically used if you have a 3rd-party mechanism for user authentication. In this implementation, an external user repository is in place for storing user information, as well as information about whether a given user has access to a given application. This type of authentication mechanism is known as an identity management application. Examples include CA Siteminder, IBM Tivoi Access Manager, Oracle Identity Manager, and RSA Security, among others.


This implementation is limited to receiving a request that has been previously verified by an identity management application, retrieving the information provided as part of the request, verifying the authenticity of the information provided by directly communicating with the identity management application, and, finally, handling the request appropriately.


This topic contains the following information:



The instructions in this topic reference the sample code in the Single Sign-on Sample, which is provided as part of the MicroStrategy SDK. It is located by default in the samples\java\sso folder of your MicroStrategy SDK installation. You can modify this code depending on your own requirements.

Token validation process

Each identity management application provides a different set of user information to the target application, based on its own user authentication and authorization process. The identity management application also provides APIs to verify the validity of the information passed. Some identity management applications pass a token for an authorized user as part of the user's request to MicroStrategy Web. You can use the 3rd-party application's API to verify the authenticity of this token.


A typical, high-level token validation process is shown in the diagram below:




Before you begin the high-level steps below, obtain the following information from your identity management application vendor's documentation:


  1. After the user is authenticated and authorized, what information is or can be passed as part of the request to the target application (MicroStrategy Web)?

  2. What vendor APIs can be used by the target application to verify or validate the information (tokens) passed, by connecting to the identity management application?

  3. For any subsequent requests by the same user, what information will be passed to the target application, and do any additional checks need to be made?

  4. Where should the user be redirected if the information provided (the token) is invalid or times out?


The SSO sample code provided as part of the SDK must be customized based on the information gathered from the four questions above. Generally, information passed to MicroStrategy Web includes a token (time-based, which means it will time out at some point) and a user ID. MicroStrategy Web must make a call to the vendor APIs to validate the token passed. In the response from the vendor application, the token may be valid or invalid. If it is invalid, the appropriate URL must be defined within the getfailureURL() method of the custom ESM to direct the user to the correct location. If the token is valid, additional information may be provided from the vendor application as part of the response. If the userID was not provided in the initial request, this information may be passed as part of the valid token response. This is the userID that will be used as the MicroStrategy userID to handle the user's request.


When naming URL parameters that are passed from a consumer component to the provider component, MicroStrategy Web, be sure they are named and defined intuitively and that the same names are used within the ESM code that handles the requests. In particular, ensure the following:

High-level steps to enable token implementation

This section describes how to retrieve and validate a token and includes a diagram depicting the generic single sign-on scenario you can implement using the steps that follow and the code in the SSO sample provided as part of the SDK. To keep the code generic, a simple external authentication system was created that works in the same way as a typical identity management application.


This example covers a generic single sign-on scenario where users are authenticated by an external system before they connect to MicroStrategy. The process is depicted in the diagram below:




Note: In the diagram above, the directory server may be any MicroStrategy-supported directory server. The token/ticket validation server is an identity management application, such as CA Siteminder, IBM Tivoli, or Oracle Identity Manager.


The following steps provide an overview of what you need to do to implement single sign-on using a token. These steps are followed by detailed instructions for this procedure.


  1. Define the information that will be passed to MicroStrategy. This can be defined as part of the code, or this can be defined in the Page Configuration file.

  1. Write code so MicroStrategy Web can retrieve the information passed. Additionally, if a token is present, MicroStrategy must validate the token.

  2. Define the API/URL call or Web Services call that must be made to validate the token.

  3. Define the information that will be provided by the 3rd-party authentication mechanism, depending on whether the token is valid or invalid:

Detailed procedural instructions

The following sections provide more detailed procedural information about the high-level steps listed above.



Information passed to MicroStrategy Web


You can define the following information passed to MicroStrategy Web:

The information can be sent to MicroStrategy Web as cookies (if in the same domain), as a header variable, or as part of the URL parameters.


MicroStrategy Web actions


MicroStrategy Web must be able to make a call to the single sign-on application to validate the token. You must define the mode of communication between MicroStrategy and the 3rd-party authentication system, based on the authentication system. To determine how to set up the communication mechanism, answer the following questions:

  1. How will the token be validated?

  2. What are the scenarios for a valid token? For an invalid token?

  3. How are the different scenarios above handled, for both valid and invalid tokens?

  4. How (in what format) will this information be communicated to MicroStrategy?

  5. How will execution errors/exceptions be handled?


Token validation


Token validation can be in the form of a URL, Web Services, or API call, using the token as an input parameter. The table below lists possible validation scenarios and how they should be handled.

Possible options


Valid token

The single sign-on application must provide the URL information to validate a token by passing the token as headers or as URL parameters.

No token sent or token is empty

The single sign-on application must provide the URL information to redirect the user.

Invalid token

The single sign-on application must provide the URL information to redirect the user.

Token has expired or timed out

The single sign-on application must provide the URL information to redirect the user.


Information exchange format


When a call is made to the single sign-on application, it may respond with an XML file. The response can include an error code (0 indicates there was no problem with the token) and an error description. The format of the XML file is dependent on the identity management application; see the identity management application's documentation for information on the correct format.


The following diagram shows the basic XML response for token validation:




The following code sample shows the XML structure for the response. This structure can be enhanced depending on your requirements:


<!ELEMENT return_code ( pass | fail ) >






Information summary


In summary, the following information must be defined for any 3rd-party authentication mechanism.




A single sign-on URL to validate the user's request

Specified in a properties file

A single sign-on token name

Specified in a properties file

Any additional properties being passed to the MicroStrategy product

Specified in a properties file

A URL to which the user is sent when there is no token. May be the same URL as when a token is missing or expired.

Specified in a properties file


A URL to which the user is sent when the token is invalid.  Specified in a properties file.

Specified in a properties file

A URL to which the user is sent when the token has timed out or expired. May be the same URL as when a token is missing or invalid.

Specified in a properties file

The format of the XML response for the validation URL



Information that can be customized


The following table presents each part of the process, its basic implementation, and some customization options that depend on your requirements and environment.


Part of the process

Basic implementation

Customization options

Token  passed

Passed as URL parameters

Can be:

  • URL parameters

  • Headers

  • Cookies (if same domain)

URL for when token is missing, invalid, or timed out

All scenarios point to the same URL


Separate URLs for some or all scenarios

Properties supported

Token name, authentication and logon page URL

Separate URLs for different token-handling scenarios

Return code XML

Simplified XML

XML and the resulting code modified to cater to the external authentication system XML response (dependent on single sign-on system)

Handling token failures

Send to external logon page

Separate destination for each error type in the request XML


Note: Communication between MicroStrategy and the identity management application depends entirely on the identity management application that is used. Therefore, when you select the token, the return codes, the URL format, and so on, refer to the identity management application documentation for details.