Enabling Single-Sign-On on WebSphere Portal in IBM Cognos ReportNet

Transcription

1 Guideline Enabling Single-Sign-On on WebSphere Portal in IBM Cognos ReportNet Product(s): IBM Cognos ReportNet Area of Interest: Security

2 2 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 This document is maintained by the Best Practices, Product and Technology team. You can send comments, suggestions, and additions to cscogpp@ca.ibm.com.

3 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 IBM Cognos ReportNet 1.1 MR1+, some of the same principles apply to previous versions of both WebSphere and IBM Cognos. As a prerequisite, it is assumed that the reader has successfully imported the Cognos portlets. Refer to the document on Installing Cognos Portlets In WebSphere Portal for more information on how to import the Cognos portlets. Contents 1 Determining the Proper SSO Method Shared Secret LTPA Token Alternate Methods Gateway considerations Installing a dedicated Gateway Setting up Shared Secret Setting up LTPA Token...10 Appendix A Installing a Dedicated Gateway...14 Appendix B Enable External Identity Mapping for LDAP Namespace...17 Appendix C Enabling Identity Mapping for AD Namespaces...17 Appendix D The Connection Server URI...19

4 4 1 Determining the Proper SSO Method Cognos Portal Services (CPS) provides two main methods for enabling SSO with IBM WebSphere Portal: Shared Secret 1 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 Alternatively, the following decision tree can be used: If (ReportNet 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 ReportNet namespace) then Shared Secret. else alternate method 1 The Shared Secret is available in CRN 1.1 MR1 or later. It s not available in CRN 1.1 RTM

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

6 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 IBM Cognos ReportNet 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 for specifying a default namespace to use for authentication. For SSO with external 3 rd party portals this means to install an additional dedicated gateway just to handle the Portlet requests 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 are routed to a second gateway which specifies a different namespace to use for SSO. 3 Installing a dedicated Gateway The first step before enabling SSO is to install a dedicated IBM Cognos ReportNet gateway to process all requests coming from Cognos portlets. This is mandatory only in mixed use environments where you have users connecting to IBM Cognos ReportNet directly as well as users coming through a portal. The second Gateway will allow for having both existing next to each other. If your use case involves portal only then one Gateway is all you need. You may have to adjust configuration or switch the type of gateway depending on your setup though. Whenever we refer to a dedicated gateway in the following just relate this to your gateway. Installing a dedicated gateway is very simple. Simply follow the steps as described in Appendix A Installing a Dedicated Gateway. On Windows with IIS, we suggest setting up a CGI gateway for simplicity. However, the ISAPI DLL is fully supported and may provide better performance. On UNIX or LINUX go with a Apache2 Mod for good performance or CGI for simplicity. If you are planning to use LTPA token as the SSO method, it is necessary to install a IBM Cognos ReportNet Servlet Gateway and deploy that securely into WebSphere Application server. For more detailed instructions refer to Deploy a secured IBM Cognos 8 MR1 Servlet Gateway in WAS6.doc on the ProvenPractice Website. Although written for IBM Cognos 8 the same steps apply, just use a IBM Cognos ReportNet Gateway.

7 7 4 Setting up Shared Secret Step 1 Install and Configure an Alternate Gateway An alternate gateway is mandatory when using Shared Secret. 1. Install the alternate gateway and configure your web server. (Refer to Appendix A or the Cognos Installation Guide for more information on installing an alternate gateway.) 2. Start Cognos Configuration for the alternate gateway 3. In the Environment section, set the following fields: Internal Dispatcher = <address of your main Cognos Dispatcher> External Dispatcher = <same dispatcher address as above> Gateway namespace=cpstrusted 4. Save and close Cognos Configuration. Step 2 Configure the Trusted Signon Namespace On every installed instance of IBM Cognos ReportNet 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

8 8 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 Security > Authentication > Cognos, set use anonymous access to false. 4. Save the configuration and restart IBM Cognos ReportNet. Step 3 Configure CPS properties On every installed instance in your system running the Dispatcher component adjust CPS properties by following the steps outlined here. 1. Open <install dir>/webapps/p2pd/web-inf/classes/cps_trustedsignon.properties for editing in a texteditor and change the following values.

9 9 namespace_id= <ID of your authentication namespace> auth_cookie_name= cps_auth_user cps_auth_secret= <The shared secret string> Where: <ID of your authentication namespace> is the ID of the namespace associated with the IBM Cognos ReportNet namespace used to authenticate users. It can be of type LDAP, IBM Cognos Series 7, NTLM or Active Directory. Note: This is not the CPSTrusted namespace set above but the target namespace which does the final authentication to IBM Cognos ReportNet. <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 B Enable External Identity Mapping for LDAP Namespace for details. If your target namespace is of type AD, enable Identity Mapping. See Appendix C Enabling Identity Mapping for AD Namespaces for details. Step 4 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: CPS Endpoint cps_auth_secret Active Credential Type <connection server URI> <The shared secret string> (none) Important: The connection server is to contain the URI to access the WSDL location via a gateway. See Appendix D The Connection Server URI to help determine the proper value based on your Gateway type and the Portlet type.

10 10 The Authorization secret must be the same as the one set in Step 3 above. When using Shared secret, it is a good idea to leave Active Credential Type as (none). Step 5 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 IBM 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 actually show up. 5 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 ReportNet server. If the IBM Cognos ReportNet server does run in a WebSphere Application Server environment, you must at least install the IBM Cognos ReportNet Servlet Gateway onto a WebSphere Application Server. For LTPA Token to work properly, the following conditions must be met: An IBM Cognos ReportNet Servlet Gateway must be installed as a secured application in a WebSphere Application Server IBM Cognos ReportNet 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 ReportNet Gateway/Dispatcher) are part of that same domain.

11 11 Step 1 Deploy and Secure the Servlet Gateway as a WebSphere Application An alternate gateway is mandatory when setting up SSO with LTPA token. This step requires administration privileges in the WebSphere Application server. 1. Do a new Gateway component only install. Either install to the same server as your other Gateway into some other directory or to another server. 2. On the alternate gateway, build a WAR or EAR file to deploy into the WebSphere Application Server (as described in the IBM Cognos ReportNet Administration & Security Guide). 3. Deploy the alternate gateway onto the WebSphere Web Application Server 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 ProvenPractice Website. Although written for IBM Cognos 8 the same steps apply, just use a IBM Cognos ReportNet Gateway. 4. Start Cognos Configuration for that alternate gateway. 5. In the Environment section, set the following fields: Internal Dispatcher = <address of your main IBM Cognos ReportNet Dispatcher> External Dispatcher = <same dispatcher address as above> Gateway namespace=<your authentication namespace> Where <your authentication namespace> is the ID of the namespace associated with the Directory server to be used for looking up users accessing the IBM Cognos ReportNet server via the portlets. This namespace can be of type LDAP, NTLM or IBM Cognos Series Save and close Cognos Configuration. 7. Restart the Servlet Gateway application by restarting the WebSphere it has been deployed in to. Step 3 Configure the Cognos Portlet Applications in WebSphere Portal 1. Login to WebSphere Portal as an administrator.

12 12 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: CPS Endpoint Active Credential Type <connection server URI> LtpaToken Important: The connection server is to contain the URI to access the WSDL location via a gateway. See Appendix D 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 or Active Directory namespace in ReportNet

13 13 All request sent by the Cognos Portlets to the CPS Endpoint 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 ReportNet will look up the users in the LDAP again and if found authenticate the user for IBM Cognos ReportNet. For the IBM Cognos ReportNet LDAP namespace to map user IDs correctly, external user mapping needs to be enabled. See Appendix B Enable External Identity Mapping for LDAP Namespace for more details. For AD namespaces, see Appendix C Enabling Identity Mapping for AD Namespaces.

14 14 Appendix A Installing a Dedicated Gateway This section provides a high-level overview of installing a dedicated gateway. Please refer to the IBM Cognos Install & Configuration Guide for more details about dedicated and alternate Gateways. Installing a Gateway 1. Run the IBM Cognos ReportNet installation CD. 2. Select a server or folder for the new gateway. The gateway can be on the same machine as the main IBM Cognos installation, but it is mandatory that you install this dedicated gateway to a separate folder than the main IBM Cognos ReportNet installation. (i.e. a new folder like cpsgateway will suffice). Configuring a Gateway The first step is to determine the type of Gateway required. There are four types of gateways: CGI, ISAPI, MOD(2), and Servlet. The type of gateway to use depends on your environment and preference. When SSO is performed by an application server, such as in certain cases of SAP User Mapping and WebSphere LTPA token, a servlet gateway must be installed. For brevity, the rest of this section will describe how to setup a CGI gateway on IIS. This is the simplest gateway to configure, but the same general principles apply to all other types of gateways. Please refer to the IBM Cognos Installation & Configuration Guide for more information on how to configure these other types of gateways. Regardless of the type of Gateway used, it is important to run the instance of Cognos Configuration used for this dedicated gateway. In Cognos Configuration, configure the following fields: Dispatcher URI for gateway = <same dispatcher URI as for your main IBM Cognos ReportNet server> Controller URI for gateway = <same controller URI as for your main IBM Cognos ReportNet server> Gateway Namespace = <ID of the target authentication namespace for portal users> The gateway namespace value should be the ID (and not the name) of the target namespace. If you are using the Shared Secret SSO method, then the gateway namespace needs to be the ID of the Custom Java Provider or Shared Secret namespace. Configure the Web Server

15 15 This step does not apply when setting up a servlet gateway. The Web Server must be configured to have three virtual directories to access the content of the dedicated gateway, similar to the main gateway. In IIS: Step 1 Create the Appropriate Virtual Directories: 1. Create a new virtual directory called cpsgateway and map this directory to the <install dir>/webcontent folder. 2. Under cpsgateway virtual directory, create another virtual folder called cgibin. Map this folder to the <install dir>/cgi-bin folder. Make sure that this virtual directory has Execute Permissions for Scripts and Executables. 3. Under cpsgateway virtual directory, create another virtual folder called help and map this directory to the <install dir>/webcontent/documentation folder. Step 2 Set the appropriate directory security access on the cpsgateway directory. 1. In IIS, right-click on cpsgateway and select Properties. Click on the Directory Security tab and select edit under the Anonymous access and authentication control heading. 2. The directory security depends on the type of SSO method used: For Shared Secret or SAP Logon Ticket, select anonymous access. For Basic Authentication with SAP User Mapping, select Basic authentication. Click on edit and assign a compatible domain that contains the namespace for the ReportNet Enterprise Portal users. In IIS, this can only be set to NTLM or Active Directory namespace.

16 16

17 17 Appendix B Enable External Identity Mapping for LDAP Namespace Enabling External Identity Mapping is required if IBM Cognos ReportNet is using an LDAP namespace. This is a namespace of type LDAP and not Series 7. On every installed instance of IBM Cognos ReportNet 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 IBM Cognos ReportNet for these changes to take effect. Appendix C Enabling Identity Mapping for AD Namespaces 2 Enabling Identity Mapping is required if IBM Cognos ReportNet is using an AD namespace. This is a namespace of type AD and not IBM Cognos Series 7 or LDAP. 2 Enabling Identity Mapping is available as of CRN 1.1.MR2 only

18 18 On every installed instance of IBM Cognos ReportNet 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 AD namespace. 2. Under Advanced Properties, click edit.

19 19 3. Type in singlesignonoption for the name and IdentityMapping for value. 4. Save the Configuration and restart IBM Cognos ReportNet for these changes to take effect. Appendix D The Connection Server URI The Connection Server URI is the server connection between the Enterprise Portal and IBM Cognos ReportNet. 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 eway/cp2/nav cps2/nav

20 20 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 /nav? Cognos Search Cognos Viewer Metric Manager Watchlist Cognos Extended Applications /cmm? /sdk? Appendix E 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.

21 21 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

22 22 Select open a keystore

23 23 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

24 24 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

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

26 26 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