WebSphere Single Sign-On with Cognos BI Server

In a past IBM life, I led a support team focused on integration related issues between the then-Lotus and WebSphere brand. A particular problem was that of single sign-on. So when a business partner asked me to investigate a single sign-on solution between Cognos Business Intelligence server and WebSphere Portal, I figured this would be rather straight forward. It was not – partly because Cognos is not my area of expertise and partly because the approach I had historically used was difficult to locate in documentation. So read how I did it and save yourself a lot of time … and I mean a lot of time.


But first, let me give a little bit of background that framed my approach. In my former role, the LTPAToken was the primary single sign-on mechanism. It is a token-based cookie that is proprietary to IBM products. Log into one IBM application server, get an LTPAToken, the browser gives that to another IBM server, and you’re logged in.

What’s in an LTPAToken and how it must be used? First, it’s a cookie used by the browser. It’s session based – meaning if you close the browser, the cookie is not able to be used when you restart. Inside this cookie are three pieces of information:

  1. the distinguished name of the user (e.g. uid=vanstaub,cn=demos,dc=ibm,dc=com)
  2. the realm (e.g. defaultWIMFileBasedRealm)
  3. the expiration time, which is an absolute timeout (e.g. the current time plus 2 hours – configurable by the app sever)

The cookie gets set upon authentication to the first application server and is received by any other server you visit. The browser is what sends the cookie to those other servers – provided they are in the same internet domain. Let me explain that last statement.

Your browser will not send cookies to any server you visit. If I visit www.ibm.com and later visit www.vanstaub.me, vanstaub.me isn’t sent ibm.com cookies. Cookies are only sent by the browser when the servers’ domain matches. So portal.demos.ibm.com’s cookies will be sent to cognos.demos.ibm.com because the cookie is set for the .demos.ibm.com domain. This is done by the application server. Shown below is the WebSphere setting (Security -> Global Security -> Web and SIP security -> Single Sign-On (SSO).


The reason for explanation is that in your testing, you can not use either http://myserver (i.e. machine name) or (i.e. IP address). You must use fully qualified domain names, which you can solve by simply updating you local hosts file.

To setup single sign-on within WebSphere, you export the LTPAToken from the source server and import on the target. This option is found on the Global Security -> LTPA page. The password is simply used to protect the key – it’s not like you have to remember you LTPAToken password. Just set one on the export and use the same one when you import on the other WebSphere server. The key is also just a text file, so you could name it LTPA.key.



This is the basis to create single sign-on between WebSphere Portal and Cognos BI server.

  1. Deploy Cognos on WebSphere
  2. Configure single sign-on between the two WebSphere servers (e.g. SSO settings and security)
  3. Login to WebSphere Portal
  4. Change the URL to Cognos and expect to be logged in

The majority of the work lies on deploying and configuring Cognos. Be aware that this approach means that Cognos and the WebSphere Application Server are co-located on the same machine.

Deploying Cognos on WebSphere

Doing this using documentation is rather straightforward – if you know what to look for. I did not. Eventually, I came across this Using an application server other than Tomcat. Read it; follow it. But I’m providing the shortened version and linking to steps in the documentation.

Set environment variables

There are external Cognos libraries that the WebSphere Application server must know about. To ensure this, you update the PATH (Windows in my example) to reference the Cognos bin directory. This is found on the WebSphere server’s Java and Process Management -> Process Definition -> Environment Entries page.


Add user role to enable single signon between IBM WebSphere profiles

This is rather straightforward. Just take care in which file you are editing – there are several files with similar names. Also open the XML file with a web browser to check the document is well formed and that you did not make a syntactic mistake.

Configure IBM Cognos components to run within the application server

This needs to be done in cogconfig, which must run using the WebSphere JVM. See my Windows script for example.

set JAVA_HOME=C:\IBM\FormsExperienceBuilder\WebSphere\AppServer\java

I’ve added a new Authentication resource to utilize the same LDAP directory as my WebSphere security settings. It’s a Domino server, which is why you see dominoPerson as the user’s object class. You’ll likely use inetOrgPerson and groupOfNames for user are group object classes.


Of particular attention is the Use external identity and External identity mappings settings. Once the user logs in to WebSphere Portal and an LTPAToken is issued, WebSphere will automatically begin setting the REMOTE_USER environment variable. This is what allows the Cognos EAR on WebSphere to map from the WebSphere user to the user in the LDAP. Also of note, keep the parentheses on the end of the mapping.

Next, set the Allow anonymous access to false. This ensures that when you switch to Cognos, the user is automatically logged in. If you don’t do this, the user must click Log On or some other challenge must be issued. If you were to click Log On from the dashboard, the page is simply refreshed rather than a login form being presented. The reason no login form is presented is because we are authenticated with the LTPAToken.


Update the Environment settings to use WebSphere URIs rather than the defaults. You can locate the HTTP ports in the WebSphere console or within ..\WebSphere\AppServer\profiles\<profile_name>\logs\AboutThisProfile.txt. Cognos will actually read this file in a later step so it’s important that the information within it is accurate. The file is created by WebSphere when the profile is initially created.


Use the Build Application Wizard to build and install IBM Cognos on IBM WebSphere Application Server

Finally, install the Cognos EAR into the WebSphere profile. Start by creating a WebSphere configuration.


Next build the p2pd EAR that will be deployed into WebSphere. Right mouseclick the service seen above. Select the Build option. Building the EAR is required to incorporate the manual modifications you made in application.xml.template and web.xml.withCM.


Install IBM Cognos on WebSphere

There are two ways to do this. Since the EAR has been built, you could login to the WebSphere Console and use the Applications -> Application Types -> WebSphere enterprise applications -> Install option. Simply using the fast path is sufficient.

Alternatively, you can use cogconfig. This is the option presented at the end of the build process. Make sure you increase the heap memory size or set this to the current WebSphere server’s heap. When cogconfig completes the install, it will update the WebSphere heap. But the currently running WebSphere server is still using the old value. If too low, Cognos will run out of memory if you start the EAR. So you might want to consider stopping and starting WebSphere at the end of the installation.

Cognos_installCognos_install2Cognos_install3Cognos_install4Cognos_install5Cognos_install6Finally, add the All Authenticated role to the Cognos EAR. Optionally, you can also map the web module to your webserver. Save, and restart WebSphere.


Test Single Sign-On

If everything is set up properly, you will be able to log into WebSphere Portal and switch the URL in the address bar to http://feb.demos.ibm.com:9080/p2pd/servlet/dispatch/ext. You must use this URL – not the CGI scripts or /ibmcognos context. The user should be shown as logged on. If not, either SSO is not correctly configured or Allow Anonymous was not set to false in cogconfig. Debugging SSO can be difficult, so just review your steps.


Couple of points I learned along the way.

  • You do not need to rebuild the EAR upon configuration changes. The EAR will reference a link that points to the Cognos installation, which is the reason we co-locate WebSphere and Cognos. But you do need to restart the Congos EAR to refresh settings.
  • It’s best to restart the WebSphere Application Server rather than the Cognos EAR. I know it takes longer, but there seems to be a classloading issue when you restart the EAR. The EAR evidently tries to re-instantiate a class that results in a Java exception. If you hit the p2pd servlet and get a 500 error, this is probably why. Restart.
  • Turn on AAA trace.  For SSO investigation, you’re looking for entries similar to <name xsi:type=”xsd:string”>REMOTE_USER</name><value>xsi:type=”xsd:string”>wpadmin</value>. If this is seen when the user comes from the Portal application, we know that Cognos “knows” the identity of the user. The value (e.g. wpadmin) is what gets used in the External identity mapping setting (e.g. (uid=${environment(“REMOTE_USER”)})) and Cognos issues an LDAP search.

One thought on “WebSphere Single Sign-On with Cognos BI Server”

Leave a Reply

Your email address will not be published.