Enabling Single Signon with IBM Cognos ReportNet and SAP Enterprise Portal

Guideline Enabling Single Signon with IBM Cognos ReportNet and SAP Enterprise Portal Product(s): IBM Cognos ReportNet Area of Interest: Security

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

3 ABSTRACT Contents This document provides step-by-step instructions on how to enable Single Signon (SSO) with Cognos Portal Services (CPS) in SAP Enterprise Portal 6.0. Although this document was written specifically for configuring SSO between SAP Portal 6.0 and Cognos ReportNet, many of the same principles apply to previous versions of both SAP and Cognos. 1 Overview... 4 2 Determining the Proper SSO Method... 4 2.1 Shared Secret... 5 2.2 User Mapping... 6 2.3 SAP Logon Ticket... 6 2.4 Alternate SSO Methods... 7 3 Gateway considerations... 7 4 Installing a dedicated Gateway... 7 5 Setting up Shared Secret... 7 6 Setting Up User Mapping... 12 7 Setting up SAP Logon Ticket... 15 7.1 Configuring the SAP Portal using Logon Tickets... 15 7.2 Configuring SAP BW... 16 Appendix A Installing a Dedicated Gateway... 20 Appendix B Enable External Identity Mapping for LDAP Namespace... 23 Appendix C Enabling Identity Mapping for AD Namespaces... 23 Appendix D The Connection Server URI... 25

4 1 Overview This document provides information and detailed how-to steps on how to enable single signon (SSO) between IBM Cognos ReportNet and SAP Enteprise Portal. This document explains the different techniques that can be used for enabling SSO and provides some best practices guidelines. This document covers most of the common customer environments. As a prerequisite, it is assumed that the reader has successfully imported the Cognos iviews. 2 Determining the Proper SSO Method Cognos Portal Services (CPS) provides three distinct methods for enabling SSO with SAP portal: Shared Secret, SAP Logon Ticket or User Mapping. The method to use depends on the authentication sources you are using with both SAP and IBM Cognos.

5 One approach for determining the right approach is to use the following decision tree: SAP Logon Ticket Shared Secret SAP Portal Cognos SAP Portal Cognos SAP Authentication Source Any Authentication Source (LDAP, Series 7, NTLM, or Active Directory.) Shared Secret User Mapping SAP Port Cognos SAP Portal Cognos Both authentication sources must have matching UIDs (can have different pwds) Both authentication sources have different UIDs 2.1 Shared Secret Shared Secret is an IBM Cognos-specific method for handling SSO. The Cognos iviews 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:

6 The Portal User ID (used to log into SAP portal) are the same as those User IDs in the associated IBM Cognso 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, IBM Cognos 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. 2.2 User Mapping SAP portal supports User Mapping as another way for authenticating users into thirdparty applications. With User Mapping, SAP stores each user s credentials (for each third-party application) into its credential vault. Each portal user is then required to enter their IBM Cognos ReportNet credentials into their User Mapping portal personalization page. When activated, the IBM Cognos portlets will extract the current user s Cognos credentials from the vault and send then to the IBM Cognos ReportNet server (via the alternate gateway) using the standard HTTP Basic Authentication mechanism. The User Mapping method should be used if the following conditions are met: The SAP Portal User IDs are not the same as those User IDs used with IBM Cognos. You have a Web Server or a Web Application Server capable of authenticating users via the HTTP Basic Authentication method and this Web or Application Server is capable of accessing the same directory server as specified in the IBM Cognos ReportNet namespace. Note: Microsoft IIS cannot access an LDAP directory server, but the Web application server most likely can. 2.3 SAP Logon Ticket SAP Logon Ticket is the SAP-recommended method when a number of SAP applications and servers all share the same SAP authentication source. With SAP Logon Ticket, SSO is granted between the SAP portal and SAP BW, if they both share the same authentication server. IBM Cognos ReportNet can leverage SAP Logon Ticket for SSO, if IBM Cognos uses the same SAP namespace as both SAP portal and SAP BW.

7 2.4 Alternate SSO 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. 3 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. 4 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 Error! Reference source not found. 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. 5 Setting up Shared Secret This section provides step-by-step instructions on how to setup SSO using Shared Secret. Step 1 Install and Configure an Alternate Gateway

8 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

9 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. 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 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 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:

10 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. 2. Save the file 3. Restart the ReportNet Service for the changes to take effect Step 4 Configure the Cognos iviews to use Shared Secret in SAP 1. Login to SAP Portal as an administrator. 2. Go to Content Administration > Portal Content and locate the Cognos iviews. By default, the Cognos iviews are saved in the Portal Content > Content by other vendors > End User Content directory. 3. Open each Cognos iview. 4. For each Cognos iview, set the following fields: CPS: Connection Server <connection server URI> CPS: Authorization Secret <The shared secret string> 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. The Authorization secret must be the same as the one set in Step 2 above.

11

12 Step 5 Test the Cognos iviews 1. Place the Cognos iviews on a page and grant access permissions to the SAP users that will be using IBM Cognos. 2. Logon to SAP portal with a User ID that is common to both SAP and IBM Cognos. 3. View the page and notice that the Cognos iviews actually show up. 6 Setting Up User Mapping Step 1 Install and Configure an Alternate Gateway An alternate gateway is mandatory when using Shared Secret. 4. 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.) 5. Start Cognos Configuration for the alternate gateway 6. In the Environment section, set the following fields: Internal Dispatcher = <address of your main IBM Cognos Dispatcher> External Dispatcher = <same dispatcher address as above> Gateway namespace=cpstrusted 4. Save and close Cognos Configuration. Step 2 Configure the Web Server or Application Server to accept HTTP Basic Authentication This step depends entirely on the combination of Web server, Web application server (WAS) and Authentication directory server used and can be very different depending on the customer environment. Since the IBM Cognos ReportNet server does not process HTTP Basic Authentication tokens, the authentication needs to be performed by either the Web Server (Apache, IIS, IBM HTTP Server, etc.) or the WAS (WebSphere, Bea, Tomcat, NetWeaver, etc.) via a secured servlet gateway. By convention, upon authentication, the Web server (or WAS) generates the REMOTE_USER HTTP variable for the User ID which gets trusted by ReportNet Access Manager and looked up into the associated namespace. The Web server or WAS must be able to use the same Directory Server as the IBM Cognos system. With Windows and IIS, HTTP basic is simple to setup, but can only be used to authenticate against an integrated Windows authentication scheme like Active Directory or NTLM. LDAP and IBM Cognos Series 7 directories are not supported by IIS. If you must authenticate against LDAP, set up a secured gateway in the Web application server.

13 Web Server All popular web servers support HTTP Basic. HTTP Basic authentication should be enabled on the Alternate gateway. The virtual directories should be enabled for HTTP Basic authentication and a CGI, ISAPI or NSAPI gateway should be used. To configure HTTP Basic authentication in IIS: 1. Open the IIS administration console 2. Select the virtual directory associated with the alternate gateway 3. Right-click and select Properties. 4. Under Directory Security, set up basic authentication and specify the proper domain. The domain should also be setup as a namespace in your IBM Cognos ReportNet server (the namespace used for mapping portal User IDs in IBM Cognos ReportNet). Any access to this virtual directory will require a valid HTTP Basic authentication token. If the user does not have a valid HTTP authentication token, the user will be prompted to enter their credentials. The Cognos iviews will not prompt the user for their credentials, if authentication fails. Instead, an error message will be returned. Web Application Server In the event that the Web Application Server will be performing the authentication using HTTP basic authentication, it is recommended that you install a Servlet gateway (as your CPS dedicated gateway for Cognos iviews) directly into your Application Server and secure the gateway entry point with HTTP Basic authentication against a supported security realm/directory server. This directory should be mapped as a namespace in IBM Cognos ReportNet.

14 The procedure to secure an entry point depends on your type of Web Application Server. In Tomcat, this setup is completely manual and can be quite complex. For other Application Servers, like IBM WebSphere, BEA Weblogic, or SAP NetWeaver, refer to the appropriate administration manual. Step 3 Configure a Cognos System Object in the SAP Portal When the ReportNet EPA package file is imported into SAP Portal, a default IBM Cognos ReportNet system object is also included. To edit this system object within SAP Portal: 1. Go to System Administration > System Configuration > System Landscape. Edit the ReportNet system object in the Cognos package. 2. Select the System Definition category and set the following values: Name of the server: Name of the server hosting the dedicated gateway Port Number: Port to access the dedicated gateway Protocol: HTTP IRU of web application: http://<servername>

15 3. Save the settings, then, hit the Display: System Aliases drop down. 4. Create a system alias (like Cognos8 ) and save again. 7 Setting up SAP Logon Ticket 7.1 Configuring the SAP Portal using Logon Tickets This section assumes that the Cognos iviews have been installed and configured in SAP Portal. No additional configuration steps are required within the Cognos iviews for this SSO method. Authentication Source As described above in SAP Logon Ticket, the SAP Portal and IBM Cognos ReportNet must be set up to authenticate all users against the same authentication source. SAP EP and SAP BW do not need to share the same authentication source as both sources use the same User ID. Portal Certificate (verify.der) 1. Download the verify.der and verify.pse files containing the Portal Server s certificate. To download, administrators must be assigned to the System Administration role. The administrator must also be assigned to the J2EE Engine security role administrators. However, by default, this role is assigned to the group Administrators, so it should suffice to only assign the user to the Administrators group.

16 2. In the SAP portal, select System Administration SystemConfiguration Keystore Administration. 3. Choose Content. Scroll to the bottom of the screen. Choose Download verify.der File or Download verify.pse File as required 7.2 Configuring SAP BW This section describes the steps for Configuring BW 3.5 Systems for SSO with SAP Logon Tickets. Prerequisites 1. For correct integration of BW and the portal, the BW system server and the portal server must be in the same network domain. 2. Users must have the same user IDs in all SAP Systems that are accessed via Single Sign-On with SAP logon tickets. If the SAP user IDs are different to the portal user IDs, you must define an SAP reference system or use another SSO method as described under Determining the proper SSO method. 3. BW system must be up to date with latest binary and HP patches 4. SAP Systems based on SAP Web Application 6.20 or higher do not require the plug-in.

17 5. The SAP Security Library is installed on all of the system's application servers. For best practices, we recommend installing the most recent version of the library, which is available on the SAP Service Marketplace in the software distribution center at service.sap.com/swdc under Download Support Packages and Patches Entry by Application Group. Select Additional Components and then SAPSECULIB. (Place uncared files in the RUN directory of the application server)

18 Set the following profile parameters on the SAP Web Application Server: Logon TicketsParameter Value Comment login/accept_sso2_ticket 1 Allows the server to accept an existing logon ticket. login/create_sso2_ticket 1: the server's certificate is to be included in the logon ticket. For best results, set this parameter to the value 1 if the server possesses a certificate signed by the SAP CA. login/ticket_expiration_time Desired value 200 Default = 60 hours Using Transaction STRUSTSSO2 in SAP System The next step is to import public-key certificate of Portal Server to component system's certificate list and add Portal Server to ACL of component system. Both of these steps can be performed with transaction STRUSTSSO2, which is an extended version of transaction STRUST. For detailed documentation on transaction STRUST, see the Web Application Server documentation under Security Trust Manager. 1. In the SAP System, start transaction STRUSTSSO2. 2. A screen with the following layout appears. The PSE status frame on the left displays the PSEs that are defined for the system. The PSE maintenance section on the top right displays the PSE information for the PSE selected in the PSE status frame. Below that, the certificate section displays certificate information for a certificate that you have selected or imported.

19 The Single Sign-On ACL section on the bottom right displays the entries in the ACL of the system. 3. In the PSE status frame on the left, choose the system PSE. 4. In the certificate section, choose Import Certificate. The Import Certificate screen appears. 5. Choose the File tab. 6. In the File path field, enter the path of the portal s verify.der file. 7. Set the file format to DER coded or Binary and confirm. 8. In the Trust Manager, choose Add to PSE. [ ADD to Certificate List] button 9. Choose Add to ACL, to add the Portal Server to the ACL list. 10. In the dialog box that appears, enter the portal s system ID and client. By default, the portal s system ID is the common name (CN) of the Distinguished Name entered during installation of the portal. The default client is 000.

20 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 Cognos installation, but it is mandatory that you install this dedicated gateway to a separate folder than the main 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

21 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 IBM Cognos ReportNet Enterprise Portal users. In IIS, this can only be set to NTLM or Active Directory namespace.

22

23 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 IBM Cognos 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 1 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. 1 Enabling Identity Mapping is available as of CRN 1.1.MR2 only

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

25 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 http://myserver/crngw2/cgibin/mod_cognos.dll/cps2/nav http://myserver/crngw2/cgibin/mod2_cognos.dll/cps2/nav http://myserver/crngw2/cgibin/cognosisapi.dll/cps2/nav http://myserver:9080/servletgat eway/cp2/nav http://<server:port>/<alias>/cgibin/mod2_cognos.dll/cps2/nav http://<server:port>/<alias>/cgibin/cognosisapi.dll/cps2/nav http://<server:port>/<contextroot>/ cps2/nav http://<server:port>/<alias>/cgibin/cognos.cgi/cps2/nav http://myserver/crngw2/cgibin/cognos.cgi/cps2/nav http://<server:port>/<alias>/cgibin/mod_cognos.dll/cps2/nav

26 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? http://myserver/crngw2/cgi-bin/cognos.cgi/cps2/nav Cognos Search Cognos Viewer Metric Manager Watchlist Cognos Extended Applications /cmm? /sdk? http://myserver/crngw2/cgibin/cognos.cgi/cps2/cmm http://myserver/crngw2/cgi-bin/cognos.cgi/cps2/sdk