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 Tivoli 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:

• A short description of a generic token validation process, with a diagram to show the high-level steps

• A set of high-level steps to enable token implementation, to guide you in the coding process 

• Detailed procedural instructions that reflect the high-level steps

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 thesamples\java\ssofolder 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: 

• Use the same naming conventions for the provider component as you use for the consumer component. 

• The naming convention you use for the consumer component should not conflict with the naming convention of the provider component. For example, since uid is already used in MicroStrategy, you should not use it for the consumer component. 

• You can add parameter definitions to the code itself as comments, or keep definitions in a separate file.

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:

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. 

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

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

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

   • If the token is invalid, define the URL to which the user must be redirected. 

   • If the token is valid, retrieve any additional information provided for processing the request, and, based on the user ID provided, attach this user to an available MicroStrategy user profile (user ID).

Detailed procedural instructions

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

• Information passed to MicroStrategy Web 

• MicroStrategy Web actions 

• Token validation 

• Information exchange format 

• Information summary 

• Information that can be customized

Information passed to MicroStrategy Web

You can define the following information passed to MicroStrategy Web: 

• Token/cookies (name and its datatype to be defined) 

• UID (user ID) 

• Other information 

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. 

Single sign-on

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 ) >
<!ELEMENT pass EMPTY >
<!ATTLIST pass userid CDATA #REQUIRED >
<!ELEMENT pass EMPTY >
<!ATTLIST fail msg CDATA #REQUIRED >

Information summary

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

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.

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.