**UPDATE** Include sample code
In the previous article, I showed you how to present the Cognos logon window to authenticate against the Cognos BI server and run a simple report via CMS. However, for both aesthetic and technical reasons its often required to integrate the logon interface directly into your mashup application.
CMS provides the authentication service to accomplish this task. In the example below, a simple HTML form is used to ask the user for their user ID and password before running the report.
In this scenario, we have a single namespace in Cognos 8 BI such that the credential consists of a user name and password. Using this information, we can construct a credential XML document that we can send to the logon method of the CMS Authentication API.
The credential XML consists of a set of credential elements. The first piece, CAMNamespace tells CMS to use the “kdap” namespace, which is hard-coded for simplicity of this example. To authenticate with the server, we just need to grab the values the user typed in for user name and password and set CAMUserName and CAMPassword respectively.
Note that this is done as a POST request instead of a GET request, which is important for security reasons. Anything on the URL can be seen over the wire, even if the request is to an HTTPS server. By sending the credential in a POST' message body, it can be encrypted and sent securely.
What happens when there might be multiple namespaces? Fortunately, we can extend the sample to cover any possible authentication provider and generate an appropriate UI dynamically. My server now contains two namespaces, one called bluepages and one called LDAP. With the CMS authentication API, I can now present a drop down list to let the user pick the correct namespace.
Once the user has picked the correct namespace, then the sample needs to prompt for the missing pieces of information that a user needs to complete the authentication process.
To accomplish this, we need to generate only the UI that's required. By sending an empty <crendential/> logon request to the server, we will get a response from the CMS authentication service indicating what additional credential elements are required, at which point we will prompt the user to supply the required information. Once a full credential has been built, the CMS authentication service will respond with the user's logon display name and account ID. This technique allows us to handle any type of credential format that the underlying authentication provider requires.
Once we've received the response from the server, we need to do some processing on the client end to determine if logon is complete or we need to prompt for more information. We first look to see if an “accountInfo” object has been returned. If this is the case, authentication is complete and we can run the report.
If we didn't receive an account information response, then we need to start prompting the user. We start by looking at each credentialElement returned by the server. The element may contain a label such as “Namespace:” which is used to indicate to the user what they need to provide. The element may also contain an “actualValue”, which is a piece of the credential we need to maintain, but we don't need to ask the user for. For example, if we have already run through the namespace dropdown, it's not necessary to prompt for the namespace again when asking for the user ID and password. If we have an actualValue but no corresponding label, we do not need to present the user with this information in the UI.
Alternatively, a missingValue element indicates what further information is required to complete the credential. In some cases, we might receive an enumeration of possible values, others might be of type “textnoecho” which tells us to create a password type-in box in our UI.
While generating your own UI requires a bit more code than reusing the Cognos logon dialog, it provides for much greater flexibility and can work in a proxied environment where the user cannot access the Cognos BI server directly.
In the next article, I'll discuss single signon and the techniques that can be used to support it in your REST CMS application.