Cognos and Portal Single Sign-Off

A previous post created a single sign-on solution between Cognos and Portal. But what about when the user wants to logoff.  Should the user be logged out of both Portal and Cognos? From discussion with one partner, the answer is, “Yes.”

To create a complete single sign-off solution, we need to:

  • Logoff in Portal – clearing the LTPAToken and session cookies
  • Logoff in Cognos – clearing the CAM passport

Rather than create a custom solution, we’ll delegate the logoff behavior to the respective applications.  This is done by redirecting the user’s browser to the appropriate logoff URL.  For example, when the user clicks “Logout” in Portal, Portal handles the logout behavior and then redirects the user to the logout URL of Cognos.  And vice versa.

There’s a supported mechanism in both products to do exactly this.  See the redirect.logout settings in Portal and the seemingly non-existent Cognos documentation here or user suggestions here.

Configure Portal

  1. Log into Portal’s WebSphere Console.
  2. Access the WP_ConfigService resource environment provider under Resources -> Resource Environment Providers -> WP_ConfigService -> Customer Properties.
  3. Add the following entries:
    1. redirect.logout=true
    2. redirect.logout.url=http://cognos.demos.ibm.com:9300/p2pd/servlet/dispatch/ext?b_action=xts.run&m=portal/cc.xts&gohome=#
  4. Save.
  5. Restart Portal.

You can locate the Cognos “Log Off” URL by simply inspecting the href of the “Log Off” link in the Cognos user interface.

Configure Cognos

  1. Update the \c10_64\templates\ps\system.xml file.
    1. Set <logoff enabled=”true“>
    2. Specify a URL in between the <redirect-url> tags.
  2. Run cogconfig.
  3. Add the domain from step 1B in the IBM Cognos Application Firewall “Valid domains or hosts” setting.
  4. Restart Cognos.

Cognos App Firewall

My system.xml is the following.

 <logoff enabled="true">
 <!-- URL to direct to upon logoff. Note: the 'redirect-url' url specified is subject to validation at runtime -->
 <redirect-url>http://portal.demos.ibm.com/wps/myportal/ctcdemo/!ut/p/z1/04_Sj9CPykssy0xPLMnMz0vMAfIjo8zigw0MTJycDB0N3J0MDA08LQ393PxMfQ1Ngsz0wwkpiAJKG-AAjgZA_VGElBTkRhikOyoqAgDTiNm7/dz/d5/L3dDb1ZJQSEhL3dPb0JKTnNBLzRFS2lqaFVNV0hFIS9FYXhVaEZlVTFHUS8xL2xv/</redirect-url>
 </logoff>

Your redirect URL will likely be different.  Again, you can find one by logging into Portal and inspecting the logout link.  The link you see is the current page with an encoded POC action telling Portal to logout.  An alternative suggestion is to create a hidden page in Portal, and use this as the designated redirect URL.  In doing so, you might prevent someone from inadvertently deleting the redirect URL’s page and causing the processes to fail.

Cognos 10.2.2 Single Sign-On

This post should be titled Cognos 10.2.2 SSO déjà vu.  Because in my previous post I figured out how to enable single sign-on with WebSphere Portal and Cognos 10.2.1.  Then 10.2.2 came out, and I needed to figure out how to enable SSO … again.

What’s the Same?

The concepts and practices behind WebSphere SSO are the exact same as my other article.  You’ll still be exporting an LTPA token, using the same registry across servers, and using fully qualified domain names.  You’ll also be configuring cogconfig to set up the external identify mapping.

What’s Different?

By default Cognos 10.2.2 uses WebSphere Liberty Profile.  This actually removes the need to install WebSphere Full Profile, but the WebSphere Liberty Profile lacks the default console application.  So you’ll need to manually edit the server.xml to configure the LDAP registry as well as set up the LTPA token.

Locate the file \cognos\c10_64\wlp\usr\servers\cognosserver\server.xml.  This defines the application server listening on 9300 and running p2pd.  We’ll simply update it to enable LDAP security.  I’ve bold faced the important settings.

<?xml version="1.0" encoding="UTF-8"?>
<!--
 Licensed Materials - Property of IBM
 IBM Cognos Products: disp
 (C) Copyright IBM Corp. 2013 2014
 US Government Users Restricted Rights - Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.
-->
<server description="Cognos 10"> 
 <featureManager> 
 <feature>servlet-3.0</feature> 
 <feature>monitor-1.0</feature> 
 <feature>jsp-2.2</feature>
 <feature>appSecurity-2.0</feature>
 <feature>ldapRegistry-3.0</feature>
 </featureManager>
 <logging consoleLogLevel="ERROR" logDirectory="${install.dir}/logs" messageFileName="p2pd_messages.log"/> 
 <application autoStart="true" id="p2pd" location="${install.dir}/webapps/p2pd" name="p2pd" type="war"> 
 <classloader apiTypeVisibility="spec" privateLibraryRef="p2pd"/>
 </application> 
 <httpEndpoint id="defaultHttpEndpoint" httpPort="9300" host="*"/> 
 <library id="p2pd" apiTypeVisibility="spec"> 
 <fileset dir="${install.dir}/bin" includes="jcam_jni.jar"/> 
 </library> 
 <config monitorConfiguration="false"/> 
 <applicationMonitor dropins="${install.dir}/wlpdropins" updateTrigger="mbean" pollingRate="10s"/>
 <webContainer skipMetaInfResourcesProcessing="true" deferServletLoad="false" com.ibm.ws.webcontainer.servewelcomefilefromextendeddocumentroot="true" />
 <executor coreThreads="100" maxThreads="1500" />
 <ldapRegistry id="dominoLDAP" realm="defaultWIMFileBasedRealm" 
 host="domino.demos.ibm.com" port="389" ignoreCase="true" 
 baseDN="o=IBM" 
 ldapType="IBM Tivoli Directory Server"
 sslEnabled="false">
 <idsFilters
 userFilter="(&amp;(uid=%v)(objectclass=dominoPerson))" 
 groupFilter="(&amp;(cn=%v)(objectclass=dominoGroup))"
 userIdMap="*:uid" 
 groupIdMap="*:cn" 
 groupMemberIdMap="dominoGroup">
 </idsFilters> 
 </ldapRegistry>
 <ltpa keysFileName="F:\IBM\cognos\c10_64_2\wlp\usr\servers\cognosserver\resources\security\ltpakey.key" keysPassword="{xor}Lz4sLCgwLTs=" expiration="125" />
 <logging traceSpecification="com.ibm.ws.security.*=all:com.ibm.websphere.security.*=all:com.ibm.ws.wim.*=all:SASRas=all" />
</server>

First, we’re adding the security features using the <feature> nodes.  Then we configure an LDAP registry.  Couple of points on the ldapRegistry.

  • Use your other WebSphere server’s security.xml as a guide. This will be in the profile’s config folder under the cell name.  For example, the realm value will be defined in the LDAPUserRegistry_1 node of the security.xml as will the userFilters and etc.
  • Notice the userFilter uses the ampersand symbol followed by amp semicolon.  This is not an encoding mistake on the blog, it is required.
  • I could not get SSO working with my federated security WebSphere Portal server.  I think this is completely possible, but the system we finally tested SSO on was using a single user registry.  As such, the nature of the changes you see above are all that was needed.

Then you specify the LTPA token.  When you restart the server after adding ldapRegistry, the \cognos\c10_64\wlp\usr\servers\cognosserver\resources\security directory will be created.  Then you can copy the LTPA token file you exported from your WebSphere server.  After you’ve done this, then add the <ltpa> node with appropriate settings.  The keysPassword value can also be plaintext while you are testing.

Save, restart Cognos, and test SSO per my other article.

Something else I found is that the static resources like images are not contained in the p2pd web application by default.  Said differently, you’ll see a bunch of broken images if you go to http://cognos.demos.ibm.com:9300/p2pd/servlet/dispatch/ext.  In the past, we would have simply re-built the WAR from cogconfig and elected to include the static resources.  Unfortunately there is no build option in cogconfig for Liberty Profile.  And I ended up simply copying the contents of \cognos\c10_64\webcontent into \cognos\c10_64\webapps\p2pd\servlet.  (You’ll need to create the servlet directory.)  There is likely a supported process to follow, but this worked for testing purposes.

We also did not need to create the security roles as documented previously.

Summary

In Cognos 10.2.2 you’re really only configuring the Liberty Profile for SSO.  If you’ve done this before in Liberty, you should have Cognos SSO completed in no time.  If you haven’t, read my previous article as well as the Liberty documentation on LDAP registry and LTPA.

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.

Background

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).

WAS_LTPA_Domain

The reason for explanation is that in your testing, you can not use either http://myserver (i.e. machine name) or http://192.168.2.2 (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.

WAS_LTPA_importexport

Approach

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.

WAS_envar

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
F:\IBM\cognos\c10_64\bin64\cogconfigw.exe

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.

Cognos_Auth

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.

Cognos_anon

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.

Cognos_environment

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.

Cognos_resource

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.

Cognos_build1Cognos_build2Cognos_build3

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.

WAS_role

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.

Troubleshooting

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.