Enabling Single Signon with IBM Cognos 8 BI MR1 and SAP Enterprise Portal

Guideline Enabling Single Signon with IBM Cognos 8 BI MR1 and SAP Enterprise Portal Product: IBM Cognos 8 BI 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 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 and IBM Cognos 8 BI MR1, many of the same principles apply to previous versions of both SAP and Cognos. Contents 1 Overview...4 2 Determining the Proper SSO Method...4 2.1 Shared Secret...5 2.2 User Mapping...5 2.3 SAP Logon Ticket...6 2.4 Alternate SSO Methods...6 3 Gateway considerations...6 4 Setting up Shared Secret...7 5 Setting Up User Mapping...11 6 Setting up SAP Logon Ticket...15 6.1 Configuring the SAP Portal using Logon Tickets...15 6.2 Configuring SAP BW...16 Appendix A Enable External Identity Mapping for LDAP Namespace...19 Appendix B Enabling Identity Mapping for AD Namespaces...19 Appendix C The Connection Server URI...21

4 1 Overview This document provides information and detailed how-to steps on how to enable single signon (SSO) between IBM Cognos 8 BI and 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 iviews. 2 Determining the Proper SSO Method IBM 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. 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 Portal Cognos SAP Portal Cognos Both authentication sources must have matching UIDs (can have different pwds) Both authentication sources have different UIDs

5 2.1 Shared Secret Shared Secret is a Cognos-specific method for handling SSO. The iviews pick up the enterprise portal s User ID and sends it to the IBM 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 set up. It can be used in most environments, as long as the following conditions are met: The Portal User ID (used to log into the SAP 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 Cognos 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. 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 8 credentials into their User Mapping portal personalization page. When activated, the IBM Cognos portlets will extract the current user s IBM Cognos credentials from the vault and send then to the IBM Cognos 8 server 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 an 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 8 namespace. Note: Microsoft IIS cannot access an LDAP directory server, but the application server most likely can.

6 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 8 can leverage SAP Logon Ticket for SSO, if IBM Cognos uses the same SAP namespace as both SAP portal and SAP BW. 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 IBM Cognos Portals Product Manager or the Best Practices Team for help. 3 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 you 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 iviews 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 iviews 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 iviews have to go through a Gateway as of now. The properties are cps_auth_namespace (for SAP it S CPS: Namespace ID ) iview property If this property is set to a valid namespace ID in a iview 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)

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

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 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 IBM Cognos 8 BI. <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 IBM Cognos Portlets in WebSphere portal. Note:

9 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 BI. 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 iviews rather than in the configuration of the Gateway and hence enables dual use of a Gateway.

10 3. Save this configuration and restart. Step 3 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 CPS: Authorization Secret CPS: Namespace ID <connection server URI> <The shared secret string> <The CPS namespace> (i.e. CPSTrusted) 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. Step 4 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 iviews are showing up with IBM Cognos 8 content.

11 5 Setting Up User Mapping 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 iviews rather than in the configuration of the Gateway and hence enables dual use of a Gateway. 3. Save this configuration and restart. Step 2 Configure the Web Server or Application Server to Accept HTTP Basic Authentication

12 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 8 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 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, setup a secured gateway in the application server. 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 8 server (the namespace used for mapping portal User IDs in IBM Cognos 8).

13 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 iviews will not prompt the user for their credentials, if authentication fails. Instead, an error message will be returned. Application Server In the event that the 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 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 8. 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 IBM Cognos 8 EPA package file is imported into SAP Portal, a default IBM Cognos 8 system object is also included. To edit this system object within SAP Portal: 1. Go to System Administration > System Configuration > System Landscape. Edit the IBM Cognos 8 system object in the Cognos package.

14 2. Select the System Definition category and set the following values: Name of the server: Name of server hosting the dedicated gateway Port Number: Port to access the dedicated gateway Protocol: HTTP URI of web application: http://<servername> 3. Save the settings, then, hit the Display: System Aliases drop down. 4. Create a system alias (like Cognos8 ) and save again.

15 6 Setting up SAP Logon Ticket 6.1 Configuring the SAP Portal using Logon Tickets This section assumes that the iviews have been installed and configured in SAP Portal. No additional configuration steps are required within the iviews for this SSO method. Authentication source As described above in SAP Logon Ticket, the SAP Portal and IBM Cognos 8 must be setup 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. 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

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

17 Set the following profile parameters on the SAP 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.

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

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

20 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 AD namespace. 2. Under Advanced Properties, click edit.

21 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 ISAPI 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://<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 tlets/nav?wsdl&b_action=cps.wsdl http://myserver/c8gw2/cgibin/cognosisapi.dll/wsrp/cps4/portle

22 Servlet Gateway /nav?wsdl&b_action=cps.wsdl http://<server:port>/<contextroot>/s ervlet/gateway/wsrp/cps4/portlets/na v?wsdl&b_action=cps.wsdl ts/nav?wsdl&b_action=cps.wsdl 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: Portlet Type End Point Example Cognos Navigator Cognos Search /nav? 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