Enabling Single-Sign-On between IBM Cognos 8 BI and IBM WebSphere Portal

Guideline Enabling Single-Sign-On between IBM Cognos 8 BI and IBM WebSphere Portal Product(s): IBM Cognos 8 BI Area of Interest: Security

Copyright Copyright 2008 Cognos ULC (formerly Cognos Incorporated). Cognos ULC is an IBM Company. While every attempt has been made to ensure that the information in this document is accurate and complete, some typographical errors or technical inaccuracies may exist. Cognos does not accept responsibility for any kind of loss resulting from the use of information contained in this document. This document shows the publication date. The information contained in this document is subject to change without notice. Any improvements or changes to the information contained in this document will be documented in subsequent editions. This document contains proprietary information of Cognos. All rights are reserved. No part of this document may be copied, photocopied, reproduced, stored in a retrieval system, transmitted in any form or by any means, or translated into another language without the prior written consent of Cognos. Cognos and the Cognos logo are trademarks of Cognos ULC (formerly Cognos Incorporated) in the United States and/or other countries. IBM and the IBM logo are trademarks of International Business Machines Corporation in the United States, or other countries, or both. All other names are trademarks or registered trademarks of their respective companies. Information about Cognos products can be found at www.cognos.com This document is maintained by the Best Practices, Product and Technology team. You can send comments, suggestions, and additions to cscogpp@ca.ibm.com.

Abstract This document provides step-by-step instructions on how to enable Single Signon (SSO) with Cognos Portal Services (CPS) in IBM WebSphere Portal 5.1. Although this document was written specifically for configuring SSO between WebSphere Portal 5.1 and IBM Cognos 8 MR1, many of the same principles apply to previous versions of both WebSphere and IBM Cognos 8. As a prerequisite, it is assumed that the reader has successfully imported the Cognos portlets. Refer to Installing Cognos Portlets for WebSphere Portal 5.1 on ProvenPractice Website for more information on how to import the Cognos portlets. Contents 1 Determining the Proper SSO Method...4 1.1 Shared Secret...5 1.2 LTPA Token...5 1.3 Alternate Methods...6 2 Gateway considerations...6 3 Setting up Shared Secret...7 4 Setting up LTPA Token...12 Appendix A Enable External Identity Mapping for LDAP Namespace...16 Appendix B Enabling Identity Mapping for AD Namespaces...16 Appendix C The Connection Server URI...18

1 Determining the Proper SSO Method Cognos Portal Services (CPS) provides two main methods for enabling Single-Sign- On (SSO) with IBM WebSphere Portal: Shared Secret or LTPA Token. The method to use depends on the authentication sources you are using with both WebSphere and IBM Cognos. The following diagram depicts different scenarios and the proper SSO method to use: Shared Secret WebSphere Portal Cognos WebSphere Portal Cognos Any Authentication Source (LDAP, NTLM, or Active Directory) Both authentication sources must have matching UIDs (can have different pwds) LTPA Token WebSphere Portal Cognos LDAP Authentication Source (includes ADS accessed as LDAP) Alternatively, the following decision tree can be used: If (IBM Cognos 8 authentication namespace = LDAP) and (you cannot use Shared Secret for any reason) then LTPA Token or alternate method else If (Portal userids) equal to (userids in an IBM Cognos 8 namespace) then Shared Secret. else alternate method

1.1 Shared Secret Shared Secret is a Cognos-specific method for handling SSO. The Cognos Portlets pick up the enterprise portal s User ID and sends it to the IBM Cognos 8 BI server for authentication. For security purposes, the User ID is transmitted with an encrypted timestamp - encoded and decoded using a shared secret string as the encryption key. Shared Secret is the simplest form of SSO method to setup. It can be used in most environments, as long as the following conditions are met: The Portal User ID (used to log into the WebSphere portal) are the same as those User IDs in the associated IBM Cognos 8 namespace. (For IBM Cognos Series 7 namespaces, the User IDs must be the same or the Enterprise Portal User IDs must be mapped to user entries through the OS Signon feature of IBM Series 7 Access Manager.) The IBM Cognos 8 namespace used for authenticating portal users is of type LDAP, Series 7, NTLM or Active Directory. Additionally, Shared Secret can also be used if the Enterprise Portal and IBM Cognos 8 are sharing the same namespace and the namespace is either Active Directory or NTLM directory. On the IBM Cognos 8 end, an additional second namespace (a Trusted Signon Provider) is used to retrieve the encrypted information and pass it on to a full namespace like LDAP, AD, NTLM or Series7 which then does the actual authentication. 1.2 LTPA Token LTPA token is an SSO method implemented by the IBM WebSphere Application Server. By passing a token across servers, the host applications can share the user s identity and trust that it has been validated and properly secured. The LTPA token is processed only by the security layer of WebSphere Application server, so it s an IBM world technique only. Although the WebSphere portal only executes in the context of the IBM WebSphere Application Server, IBM Cognos 8 BI server can execute in alternate application servers. If IBM Cognos 8 too is deployed in WebSphere then the only necessary step is to put the IBM Cognos 8 Dispatcher under WebSphere security to leverage the identity passed in the LTPA token from the WebSphere Portal Server.

However by default, IBM Cognos 8 runs using Tomcat Application Server. Since Tomcat like any other non-ibm application server does not support LTPA token an additional link is needed. In there cases, where IBM Cognos 8 is deployed in some other application server than WebSphere a dedicated IBM Cognos 8 Servlet Gateway for exclusive use by the Cognos Portlets needs to be deployed in WebSphere and protected by WebSphere security. This protected Gateway in the WebSphere will then be able to pick up the LTPA token and relay the identity contained in it to IBM Cognos 8 s Content Manager in some other variable/header which can be consumed by an IBM Cognos 8 Namespace directly. 1.3 Alternate Methods In certain environments, none of the above three options may suffice. For example, it is possible that an alternate SSO mechanism is required when using dedicated SSO applications, like Netegrity SiteMinder, Oblix, etc. It is also possible that none of the methods described here apply to your current environment. In such cases, contact the Cognos Portals Product Manager or the Best Practices Team for help. 2 Gateway considerations Whenever there s more than just one namespace configured in IBM Cognos 8 Configuration upon authenticating to IBM Cognos 8 for the first time the user is prompted to select a namespace to authenticate with. While this is reasonable for an interactive user it s not feasible for SSO scenarios as those require authentication to one specific namespace only. To resolve this ambiguity the easiest way is to go through a gateway which allows to specify a default namespace to use for authentication. For SSO with external 3 rd party portals this usually meant to install an additional gateway to be able to force the authentication to a specific namespace. So while interactive users would use Gateway1 which would either prompt or have a default namespace set CPS requests were routed to a second gateway which specified a different namespace to use for SSO. As of IBM Cognos 8 MR1 it s no longer mandatory to facilitate a dedicated Gateway for exclusive use by CPS to achieve this. There is a new property which can be configured for the Portlets and a new setting in the Gateway configuration exposed in IBM Cognos 8 Configuration which allow for using just one shared Gateway or no Gateway at all for routing the Portlets requests. Actually though technically possible to go without a Gateway at all it s considered mandatory and in-line with product documentation to use at least one Gateway. So all the requests from Portlets have to go through a Gateway as of now. The properties are

cps_auth_namespace Portlet property If this property is set to a valid namespace ID in a Portlet s configuration inside the Portal Server it will pass this Namespace ID with any request sent by the Portlets. It can override a default namespace defined in a Gateway s configuration if Allow Namespace override is set to true (see next) Allow Namespace override IBM Cognos 8 Configuration If this new Gateway setting is set to true it allows for cps_auth_namespace to override any default namespace possibly set at the Gateway. So now one can choose to either set up a separate gateway and specify the default namespace there or override by cps_auth_namespace property or just sent CPS requests to Dispatcher directly in conjunction with the cps_auth_namespace setting. If you use a version of IBM Cognos 8 prior to MR1 you have a choice anyway and have to set up a dedicated Gateway to resolve the ambiguity in any case. 3 Setting up Shared Secret Step 1 Configure the Trusted Signon Namespace On every installed instance of IBM Cognos 8 in your system which runs Content Manager component open IBM Cognos 8 Configuration and adjust configuration using the following steps. 1. Under Security/Authentication, add a new namespace with any name (for example SharedSecret ) of type Custom Java Provider. Name = SharedSecret Type = Custom Java Provider

2. For the namespace properties, enter the following: Namespace ID = CPSTrusted Java class name = com.cognos.cps.auth.cpstrustedsignon (Note: The values for id and class name are case sensitive and must be entered as is whenever referred to) 3. Under Environment, open the Portal Services section. Set the following fields: Trusted Signon NamespaceID = <ID of your authentication namespace>

Shared Secret = <The shared secret string> Where: <ID of your authentication namespace> is the ID of the namespace associated with the IBM Cognos 8 Namespace used to authenticate users. It can be of type LDAP, IBM Series 7, NTLM or Active Directory. Note: This is not the CPSTrusted namespace set above (the field name might be confusing) but the target namespace which does the final authentication to IBM Cognos 8. <The shared secret string> is any text string without spaces or special characters. This is the secret key for User ID encryption. Remember this string as it will be needed when configuring the Cognos Portlets in WebSphere portal. Note: If your target namespace is of type LDAP, enable External User mapping. See Appendix A Enable External Identity Mapping for LDAP Namespace for details. If your target namespace is of type AD, enable Identity Mapping. See Appendix B Enabling Identity Mapping for AD Namespaces for details. 4. Under Security > Authentication > Cognos, set use anonymous access to false. 5. Save the configuration and restart IBM Cognos 8.

Step 2 Set Allow Namespace Override On every installed instance in your system running the Gateway component adjust configuration by following the steps outlined here. 1. In IBM Cognos 8 Configuration, go to Local Configuration > Environment. 2. Under the Gateway settings find Allow Namespace Override, set this to true, as shown below. This allows for specifying the namespace to target for SSO in the Portlets rather than in the configuration of the Gateway and hence enables dual use of a Gateway. 3. Save this configuration and restart. Step 3 Configure the Cognos Portlet applications in WebSphere portal 1. Login to WebSphere Portal as an administrator 2. Go to Administration Portlet Management Applications and locate the three Cognos portlet applications: Cognos BI Content Portlets Cognos Extended Applications Portlets Cognos Metric Manager Portlets

3. For each IBM Cognos application, set the following fields: Cognos 8 WSRP WSDL Location <connection server URI> cps_auth_secret cps_auth_namespace Active Credential Type <The shared secret string> <The CPS namespace> (i.e. CPSTrusted) (none) Important: The connection server is to contain the URI to access the WSDL location via a gateway. See Appendix C The Connection Server URI to help determine the proper value based on your setup and the Portlet type. The Authorization secret must be the same as the one set in Step 2 above. When using Shared secret, it is a good idea to leave Active Credential Type as (none). Remember that you must set up the shared secret and WSDL location for each Cognos Portlet. The URI is different for each one. See Appendix C The Connection Server URI Step 4 Test the Cognos Portlets 1. Place the Cognos Portlets on a page and grant access permissions for these portlets to the WebSphere Portal users that will be using Cognos. 2. Logon to WebSphere Portal with a User ID that is common to both WebSphere and IBM Cognos. 3. View the page and notice that the Cognos portlets are showing up with IBM Cognos 8 content.

4 Setting up LTPA Token Using LTPA token as the main single signon mechanism between WebSphere Portal and the Cognos portlets involves the user having administrator access rights to the WebSphere Application Server running the IBM Cognos 8 server. If the IBM Cognos 8 server does run in a WebSphere Application Server environment, you must at least install the IBM Cognos 8 Servlet Gateway onto a WebSphere Application Server. For LTPA Token to work properly, the following conditions must be met: An IBM Cognos 8 Servlet Gateway must be installed as a secured application in a WebSphere Application Server IBM Cognos 8 and the WebSphere portal must both access the same LDAP server for authentication. A WebSphere LTPA Domain must have been set up by the WebSphere administrator and both WebSphere instances (the one running WPS and the one running IBM Cognos 8 Gateway/Dispatcher) are part of that same domain.

Step 1 Set Allow Namespace Override On every installed instance in your system running the Gateway component adjust configuration by following the steps outlined here. 1. In IBM Cognos 8 Configuration, go to Local Configuration > Environment. 2. Under the Gateway settings find Allow Namespace Override, set this to true, as shown below. This allows for specifying the namespace to target for SSO in the Portlets rather than in the configuration of the Gateway and hence enables dual use of a Gateway. 3. Save this configuration and restart. Step 2 Secure the Gateway entry point To use LTPA token you need to secure the Gateway with WebSphere security. This requires administration privileges in the WebSphere Application server. The steps are 1. On the alternate gateway, build a WAR or EAR file to deploy into the WebSphere Application Server (as described in the IBM Cognos 8 Administration & Security Guide). 2. Deploy the alternate gateway onto the WebSphere Web Application Server

3. In the WebSphere Administration console, secure access to the gateway application via LTPA token. Configure it to access the same LDAP directory as the portal. Consult your WebSphere Application Server administration manuals for further details. For more detailed instructions refer to Deploy a secured IBM Cognos 8 MR1 Servlet Gateway in WAS6.doc on the Proven Practice Website Step 3 Configure the Cognos Portlet Applications in WebSphere Portal 1. Login to WebSphere Portal as an administrator. 2. Go to Administration Portlet Management Applications and locate the three Cognos portlet applications: Cognos BI Content Portlets Cognos Extended Applications Portlets Cognos Metric Manager Portlets 3. For each Cognos application, set the following fields: Cognos 8 WSRP WSDL Location cps_auth_namespace Active Credential Type <connection server URI> <The authentication namespace ID> (i.e. MyLDAP.) LtpaToken Important: The connection server is to contain the URI to access the WSDL location via a gateway. See Appendix C The Connection Server URI to help determine the proper value based on your setup and the Portlet type. In this case, the Gateway has to be a Servlet Gateway running inside a WebSphere Application server. The Active Credential Type is the key to enabling the sending of the LTPA token back to the Alternate Gateway. Make sure the spelling for LtpaToken is exact.

Step 4 Configure the LDAP namespace in Cognos 8 All request sent by the Cognos Portlets to the Cognos 8 WSRP WSDL Location will carry the LTPA Token. When receiving those requests aimed at a resource protected by Application Server security, the Application Server first authenticates the user implicitly sending the requests through the Portal based on the identity contained in the LTPA token. Authentication is done against the User Registry configured for the Application Server, i.e. an LDAP. Once authentication is successful the Application Server will populate USER_PRINCIPAL and REMOTE_USER with the User ID of the authenticated user. Both of those variables can be consumed by an LDAP namespace via the $environment{} macro and are hence valid for SSO. IBM Cognos 8 will look up the users in the LDAP again and if found authenticate the user for IBM Cognos 8. For the IBM Cognos 8 LDAP namespace to map user IDs correctly, external user mapping needs to be enabled. See Appendix A Enable External Identity Mapping for LDAP Namespace for more details. For AD namespaces, see Appendix B Enabling Identity Mapping for AD Namespaces.

Appendix A Enable External Identity Mapping for LDAP Namespace Enabling External Identity Mapping is required if IBM Cognos 8 is using an LDAP namespace. This is a namespace of type LDAP and not IBM Series 7. On every installed instance of IBM Cognos 8 in your system which runs Content Manager component open IBM Cognos 8 Configuration and adjust configuration using the following steps. 1. Open IBM Cognos 8 Configuration and locate your LDAP namespace. 2. Enable External Identity mapping by setting the following fields: Use external identity True mapping External identity mapping (uid=${environment("remote_user")}) or (uid=${environment("user_principal")}) Important: Do not forget the parentheses around the external identity mapping value. Using USER_PRINCIPAL is kind of obsolete since REMOTE_USER is populated too but is mentioned for the sake of completeness. 3. Save the Configuration and restart IBM Cognos 8 for these changes to take effect. Appendix B Enabling Identity Mapping for AD Namespaces Enabling Identity Mapping is required if IBM Cognos 8 is using an AD namespace. This is a namespace of type AD and not Series 7 or LDAP.

On every installed instance of IBM Cognos 8 in your system which runs Content Manager component open IBM Cognos 8 Configuration and adjust configuration using the following steps. 1. Open Cognos Configuration and locate your AD namespace. 2. Under Advanced Properties, click edit.

3. Type in singlesignonoption for the name and IdentityMapping for value. 4. Save the Configuration and restart IBM Cognos 8 for these changes to take effect. Appendix C The Connection Server URI The Connection Server URI is the server connection between the Enterprise Portal and IBM Cognos 8. This is the value to be set for each Cognos Portlet or iview in the Portlet properties. The connection URI will differs depending on the type of Gateway and the type of Portlet Gateway Type Connection Server URI Example URI CGI Gateway MOD Gateway MOD2 Gateway http://<server:port>/<alias>/cgibin/cognos.cgi/wsrp/cps4/portlets/nav?wsdl&b_action=cps.wsdl http://myserver/c8gw2/cgibin/cognos.cgi/wsrp/cps4/portlets/n av?wsdl&b_action=cps.wsdl http://<server:port>/<alias>/cgibin/mod_cognos.dll/wsrp/cps4/portlet s/nav?wsdl&b_action=cps.wsdl http://<server:port>/<alias>/cgibin/mod2_cognos.dll/wsrp/cps4/portl ets/nav?wsdl&b_action=cps.wsdl http://myserver/c8gw2/cgibin/mod_cognos.dll/wsrp/cps4/portl ets/nav?wsdl&b_action=cps.wsdl http://myserver/c8gw2/cgibin/mod2_cognos.dll/wsrp/cps4/por tlets/nav?wsdl&b_action=cps.wsdl

ISAPI Gateway Servlet Gateway Type of Portlet Each portlet group has a different entry point for the WSDL address. In the examples below, the /nav?... section of the URI needs to be changed accordingly: Portlet Type End Point Example Cognos Navigator Cognos Search /nav? http://<server:port>/<alias>/cgibin/cognosisapi.dll/wsrp/cps4/portlets /nav?wsdl&b_action=cps.wsdl http://<server:port>/<contextroot>/s ervlet/gateway/wsrp/cps4/portlets/na v?wsdl&b_action=cps.wsdl http://myserver/c8gw2/cgibin/cognosisapi.dll/wsrp/cps4/portle ts/nav?wsdl&b_action=cps.wsdl http://myserver:9080/servletgatew ay/servlet/gateway/wsrp/cps4/portl ets/nav?wsdl&b_action=cps.wsdl http://myserver/c8gw2/cgibin/cognos.cgi/wsrp/cps4/portlets/nav?wsdl&b_actio n=cps.wsdl Cognos Viewer Metric Manager Watchlist Cognos Extended Applications /cmm? /sdk? http://myserver/c8gw2/cgibin/cognos.cgi/wsrp/cps4/portlets/cmm?wsdl&b_acti on=cps.wsdl http://myserver/c8gw2/cgibin/cognos.cgi/wsrp/cps4/portlets/sdk?wsdl&b_actio n=cps.wsdl Appendix D SSL enabled Connection Server URI In some rare cases the Connection Server URI may be running HTTPS rather than HTTP, so the Webserver hosting the Gateway is SSL enabled. Often only externally exposed Webservers get SSL secured. It s a bad practice to use an externally exposed Gateway for Portal SSO rather than a dedicated internal one, which can be secured by firewalls against intrusion and fraud. Though in some cases even internal Gateways get SSl enabled. The Cognos Portlets can communicate with SSL enabled Connection Sevrer URIs and this is fully supported. The reason why is simple, the Portlet doesn t care if the Connection Server URI is running HTTP or HTTPS. The transport layer is to be provided by the Portal Server, not by the Portlet code. This being said, it evolves, that establishing the necessary trust between the Portal Server and the Webserver hosting the IBM Cognos Gateway is to be established within the Portal Server and not in IBM Cognos Software. Hence this is a non-cognos task and is not covered by IBM Cognos Support, rather it s a task for the Portal Server Administrator.

The way this works is, that whenever the Portlets send a request to the Connection Server URI the Portal Server will try to establish a connection to that URI. Since in the HTTPS case the Websever will first initiate an SSL handshake by presenting its server certificate, the Portal Server needs to be configured such that it trusts that certificate and hence can successfully complete the SSL handshake. For this to work, the CA which signed the Webserver certificate (self-signed certificates are a bad practice and are hence discouraged, so there has to be a CA which signed this), needs to be trusted. Since a Portal Server is just an application running inside an Application Server, this falls back to the JRE used by the Application Server. Each JRE has some truststore, a Java Keystore which contains a set of CA certificates which are trusted by the JRE. For JREs provided by SUN this truststore is a file called cacerts which is located in <JRE>/lib/security/ folder. We need to add the CA certificate which signed the Webserver certificate to this keystore. Any SUN JRE incorporates the keytool command line utility to manage keystores. The easiest way to do this for WebSphere Portal however, is to use the ikeyman tool coming with WebSphere Portal. This is a java based GUI allowing to manage keystores. You ll find examples for using both tools below. Once the certificate has been added to the JRE s truststore, restart the Portal Server and edit the WSRP location (Connection Server URI) property of the Cognos Portlets to reflect the https protocol. Save the changed properties and view the Portlets. Et voilá. Use IKeyman to add the CA certificate to the WPS JRE truststore Acquire a base64 ASCII encoded version of the CA certificate which signed the Webservers certificate, either PEM or DER format is fine. Start the IKeyman tool by executing <WPS_HOME>/AppServer/bin/ikeyman.bat

Select open a keystore

Find cacerts at <WPS_HOME>/AppServer/java/jre/lib/security by clicking Browse in the file open dialog. Change the Files of Type filter to see it listed. Click Open Ensure Key database type is JKS and click OK

You will get prompted for a password, by default this is changeit (without quotes) Enter this and click OK. You will now see a list of all the CA certificates the JRE trusts out of the box. If your Webserver certificate was signed by one of the commercial entities in this list you re most probably done. If it doesn t work then just import your CA anyway. Click Add

Find your CA certificate by browsing for it. The type depends on whether you got a PEM (base64-encoded ASCII) or DER (binary DER) file. Click OK The tool will prompt you for an alias name to assign to this certificate. Just choose any but using the name of your company or the CA itself is a good practice like Cognos CA or MyCA. Click OK. You ll now find your Certificate being listed. Done. You can close the tool, no additional save needed.

Use keytool add the CA certificate to the WPS JRE truststore Acquire a base64 ASCII encoded version of the CA certificate which signed the Webservers certificate, either PEM or DER format is fine. (So are PKCS#12 chains). Open a shell/command window and change to <WPS_HOME>/AppServer/java/jre/bin Issue the following command (all on one line) keytool import alias <AnAliasName> -file <absolute_path_to_cert> -keystore../lib/security/cacerts storepass changeit This will have added the certificate with the given alias. To check issue keytool list keystore../lib/security/cacaerts storepass chageit this will list all certificates with their alias and other information inside the keystore. For reference to keytool see http://java.sun.com/j2se/1.4.2/docs/tooldocs/windows/keytool.html