Enabling SSO between Cognos 8 and WebSphere Portal

Guideline Enabling SSO between Cognos 8 and WebSphere Portal Product(s): Cognos 8 Area of Interest: Security

Enabling SSO between Cognos 8 and WebSphere Portal 2 Copyright Your use of this document is subject to the Terms of Use governing the Cognos software products and related services which you have licensed or purchased from Cognos. The information contained in this document is proprietary information of Cognos Incorporated and/or its licensors and is protected under copyright and other applicable laws. You may use the information and methodologies described in this document 'as is' or you may modify them, however Cognos will not be responsible for any deficiencies or errors that result from modifications which you make. Copyright 2006 (c) Cognos Incorporated. All Rights Reserved. You can print selected pages, a section, or the whole book. Cognos grants you a non-exclusive, non-transferable license to use, copy, and reproduce the copyright materials, in printed or electronic format, solely for the purpose of providing internal training on, operating, and maintaining the Cognos software. This document is maintained by the Best Practices, Product and Technology team. You can send comments, suggestions, and additions to Best Practices, Product and Technologies.

Enabling SSO between Cognos 8 and WebSphere Portal 3 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 Cognos 8 MR1, many of the same principles apply to previous versions of both WebSphere and 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...11 Appendix A Enable External Identity Mapping for LDAP Namespace...15 Appendix B Enabling Identity Mapping for AD Namespaces...15 Appendix C The Connection Server URI...17

Enabling SSO between Cognos 8 and WebSphere Portal 4 1 Determining the Proper SSO Method Cognos Portal Services (CPS) provides two main methods for enabling 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 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 (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 a Cognos8 namespace) then Shared Secret. else alternate method

Enabling SSO between Cognos 8 and WebSphere Portal 5 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 Cognos 8 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 Cognos 8 namespace. (For 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 Series 7 Access Manager.) The 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 Cognos 8 are sharing the same namespace and the namespace is either Active Directory or NTLM directory. On the 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 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, Cognos 8 server can execute in alternate application servers. If Cognos 8 too is deployed in WebSphere then the only necessary step is to put the Cognos 8 Dispatcher under WebSphere security to leverage the identity passed in the LTPA token from the WebSphere Portal Server. However by default, 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 Cognos 8 is deployed in some other application server than WebSphere a dedicated 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 Cognos 8 s Content Manager in some other variable/header which can be consumed by a Cognos 8 Namespace directly.

Enabling SSO between Cognos 8 and WebSphere Portal 6 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 Cognos Configuration upon authenticating to 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 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 Cognos 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 Cognos 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.

Enabling SSO between Cognos 8 and WebSphere Portal 7 If you use a version of C8 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 Cognos 8 in your system which runs Content Manager component open Cognos 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)

Enabling SSO between Cognos 8 and WebSphere Portal 8 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 Cognos 8 Namespace used to authenticate users. It can be of type LDAP, 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 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 Cognos 8.

Enabling SSO between Cognos 8 and WebSphere Portal 9 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 Cognos 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

Enabling SSO between Cognos 8 and WebSphere Portal 10 3. For each 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 Cognos. 3. View the page and notice that the Cognos portlets are showing up with Cognos 8 content.

Enabling SSO between Cognos 8 and WebSphere Portal 11 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 Cognos 8 server. If the Cognos 8 server does run in a WebSphere Application Server environment, you must at least install the Cognos 8 Servlet Gateway onto a WebSphere Application Server. For LTPA Token to work properly, the following conditions must be met: A Cognos 8 Servlet Gateway must be installed as a secured application in a WebSphere Application Server 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 Cognos 8 Gateway/Dispatcher) are part of that same domain.

Enabling SSO between Cognos 8 and WebSphere Portal 12 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 Cognos 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 Cognos 8 Administration & Security Guide). 2. Deploy the alternate gateway onto the WebSphere Web Application Server

Enabling SSO between Cognos 8 and WebSphere Portal 13 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 C8 MR1 Servlet Gateway in WAS6.doc on the ProvenPractice 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.

Enabling SSO between Cognos 8 and WebSphere Portal 14 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. Cognos 8 will look up the users in the LDAP again and if found authenticate the user for Cognos 8. For the 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.

Enabling SSO between Cognos 8 and WebSphere Portal 15 Appendix A Enable External Identity Mapping for LDAP Namespace Enabling External Identity Mapping is required if Cognos 8 is using an LDAP namespace. This is a namespace of type LDAP and not Series 7. On every installed instance of Cognos 8 in your system which runs Content Manager component open Cognos Configuration and adjust configuration using the following steps. 1. Open Cognos 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 Cognos 8 for these changes to take effect. Appendix B Enabling Identity Mapping for AD Namespaces Enabling Identity Mapping is required if 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 Cognos 8 in your system which runs Content Manager component open Cognos Configuration and adjust configuration using the following steps.

Enabling SSO between Cognos 8 and WebSphere Portal 16 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.

Enabling SSO between Cognos 8 and WebSphere Portal 17 4. Save the Configuration and restart 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 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 ISAPI Gateway Servlet 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://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 http://myserver:9080/servletgatew ay/servlet/gateway/wsrp/cps4/portl ets/nav?wsdl&b_action=cps.wsdl 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: 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://<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 tlets/nav?wsdl&b_action=cps.wsdl http://myserver/c8gw2/cgibin/cognosisapi.dll/wsrp/cps4/portle ts/nav?wsdl&b_action=cps.wsdl Portlet Type End Point Example Cognos Navigator /nav? http://myserver/c8gw2/cgibin/cognos.cgi/wsrp/cps4/portlets/nav?wsdl&b_actio Cognos Search 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

Enabling SSO between Cognos 8 and WebSphere Portal 18 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 Cognos Gateway is to be established within the Portal Server and not in Cognos Software. Hence this is a non-cognos task and is not covered by 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á.

Enabling SSO between Cognos 8 and WebSphere Portal 19 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

Enabling SSO between Cognos 8 and WebSphere Portal 20 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

Enabling SSO between Cognos 8 and WebSphere Portal 21 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

Enabling SSO between Cognos 8 and WebSphere Portal 22 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.

Enabling SSO between Cognos 8 and WebSphere Portal 23 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