Enabling Kerberos SSO in IBM Cognos Express on Windows Server 2008

Enabling Kerberos SSO in IBM Cognos Express on Windows Server 2008 Nature of Document: Guideline Product(s): IBM Cognos Express Area of Interest: Infrastructure

2 Copyright and Trademarks Licensed Materials - Property of IBM. Copyright IBM Corp. 2011 IBM, the IBM logo, and Cognos are trademarks or registered trademarks of International Business Machines Corp., registered in many jurisdictions worldwide. Other product and service names might be trademarks of IBM or other companies. A current list of IBM trademarks is available on the Web at http://www.ibm.com/legal/copytrade.shtml 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. IBM does not accept responsibility for any kind of loss resulting from the use of information contained in this document. The information contained in this document is subject to change without notice. This document is maintained by the Best Practices, Product and Technology team. You can send comments, suggestions, and additions to cscogpp@ca.ibm.com. Microsoft, Windows, Windows NT, and the Windows logo are trademarks of Microsoft Corporation in the United States, other countries, or both. Java and all Java-based trademarks and logos are trademarks or registered trademarks of Oracle and/or its affiliates.

3 Table of Contents 1 Introduction...4 1.1 Purpose...4 1.2 Applicability...4 2 What is Kerberos...4 3 Setting up the Express Gateway...4 3.1 Installing the Express Gateway...4 3.2 Configure IIS7 Virtual Directories...6 3.3 Configure and enable the gateway modules...8 3.4 Secure the Virtual Directories...10 4 Enabling the Active Directory Namespace...12 5 Kerberos SSO prerequisites...13 5.1 End User Accounts...13 5.2 Service Accounts...14 5.3 Browser Settings...15 6 Binding the Gateway to a Namespace...16 7 When testing Single Sign On...17 7.1 HTTP 500 when accessing the portal using CGI...17 7.2 HTTP 500 when accessing the portal using ISAPI...17 7.3 Single Sign On to Cognos Express doesn t work in Firefox...17

4 1 Introduction 1.1 Purpose This document describes and demonstrates the basic steps that are required in order to enable Integrated Sign On (or Single Sign On) with Active Directory in IBM Cognos Express using the Microsoft IIS 7 Web server on Windows Server 2008. 1.2 Applicability This document applies to the IBM Cognos Express 9.5 release. All references to IBM Cognos Express in this document refer to this release only. This guide assumes that all IBM Cognos Express Services and the IIS Application pool are running as Local System (default).

5 2 What is Kerberos For the purpose of this document it is sufficient to understand that Kerberos is a network authentication protocol, which allows users/computers to prove their identity to each other in a secure yet silent manner. If you would like more detailed information about Kerberos please see the following links for more information: 1. The Active Directory Story 2. Understanding Delegation 3. Troubleshooting Kerberos Errors 4. Troubleshooting Kerberos Delegation

6 3 Setting up the Express Gateway 3.1 Installing the Express Gateway 1. Locate the Gateway\ folder in the directory where the IBM Cognos Express installation files are kept. Locate the archive containing the gateway instance: CognosExpressGateway.zip. 2. Copy this archive to the designated Web server (either the local Cognos Express Server or a standalone Web Server box) 3. Open and expand the CognosExpressGateway.zip file to a folder. For the purpose of this example we will extract the archive under the c-drive. This results in the Cognos Express Gateway folder being created containing the required bin\ and cgi-bin\ subfolders. 4. In the location where you expanded CognosExpressGateway.zip, navigate to the bin directory and locate the file cogconfig.bat and run it. 5. For example, the location is C:\Cognos Express Gateway\bin\cogconfig.bat. This file launches IBM Cognos Configuration. 6. In IBM Cognos Configuration, in the Explorer window, click the Environment section. 7. In the right pane, in the Environment - Group Properties section, locate the Dispatcher URIs for gateway property and edit the value to include the IBM Cognos Express server name and port number, such as http://express_server_name:express_port/p2pd/servlet/dispatch/ext 8. Save the configuration and exit IBM Cognos Configuration. Note that for the save to be successful the IBM Cognos Express service must be running. 9. On the server where IBM Cognos Express is installed, locate the file express_installation_location/templates/ps/system.xml. Edit this file and change the following line <param name ="welcomeurloverride"> /cognos_express/manager/welcome.html </param>

7 and add the URL information where IBM Cognos Express is installed: <param name ="welcomeurloverride"> http://express_server_name:express_port/cognos_express/manager/welcome.html </param> 10. Save this file and restart the IBM Cognos Express service. 3.2 Configure IIS7 Virtual Directories 1. Create a new application pool for IBM Cognos Express to reside in by right clicking Application Pools in IIS Manager. 2. Name the application pool and configure the new application pool with the default values as demonstrated in the following screen shot. 3. Right-click the above created application pool and select Advanced Settings. In the dialog box set the Enable 32-bit applications property to True:

8 4. Create the following two new virtual directories in the Web server. IBMCognosExpress/ This alias should be pointing at the express_gateway_location/cognos Express Gateway/webcontent folder. In this example this would result in an alias referencing C:\Cognos Express Gateway\webcontent\. cognos_express/ This alias should reference the express_gateway_location/cognos Express Gateway/cognos_express folder. In this example this would result in an alias referencing C:\Cognos Express Gateway\cognos_express. 5. Create the following new application under the IBMCognosExpress virtual directory according to the screenshots. IBMCognosExpress/cgi-bin/ This alias should be created under the IBMCognosExpress Virtual Directory and should reference the express_gateway_location/cognos Express Gateway/cgi-bin folder. In this example this would result in an alias referencing C:\Cognos Express Gateway\cgi-bin This is done by right clicking the IBMCognosExpress virtual directory and select Add Application.

9 In the dialog box then configure the Alias, physical path as per step 5. Select the Application pool you created in step 2 in the Application Pool input field. 3.3 Configure and enable the gateway modules After having created all virtual directories and applications your IIS Manager tree should look similar to this:

10 1. Select the cgi-bin application as shown above and on the right hand side select Handler Mappings in the feature view. 2. In the handler mapping screen click on add Module Mapping and configure your desired Gateway module: For CGI For ISAPI The ISAPI-dll Module mapping should already exist but is disabled by default. To enable it select the mapping, click the Edit Feature Permissions on the right and check the execute option.

11 3. Now click on the Webserver home page in IIS Manager and select ISAPI and CGI Restrictions in the feature view where you can Add an allowed application. For CGI (select the cognos.cgi in the path) For ISAPI (select the cognosisapi.dll in the path) 4. Now you should be able to access the gateway using the following URIs: for CGI: http://gateway_host/ibmcognosexpress/cgi for ISAPI: http://gateway_host/ibmcognosexpress/isapi 3.4 Secure the Virtual Directories Now that we have set up the modules and can access the gateway we are still prompted for Authentication to IBM Cognos Express. To resolve this we need to force end user to authenticate to IIS as follows: 1. Select the IBMCognosExpress virtual directory and open the Authentication feature.

12 2. In the Authentication feature, ensure that Anonymous access has been disabled and Windows Authentication has been enabled. 3. Select Windows Authentication and then click Providers. Verify that the Negotiate provider is listed on the very top as demonstrated below:

13 4 Enabling the Active Directory Namespace Now that the web server is configured and set up for Windows Integrated sign on, you must ensure that the Cognos Express instance can leverage this newly enabled feature. To do this, integrate IBM Cognos Express with the existing Active Directory infrastructure using the following steps: 1. Open up Express Manager and click on the Configure button in the Manager Section. This should bring up a popup window. 2. In the popup, enable the Enable Active Directory authentication check box and fill out the desired namespace name and the host and port number of the Active Directory Controller. 3. Depending on how your Active Directory infrastructure is implemented you might also want to change the inclusion buttons. For more information on the meaning of these properties please refer to the Include or Exclude domains section listed in the Installation and Configuration guide that comes with the product. 4. Press OK when finished and wait for the IBM Cognos Express service to recycle and apply the settings. At this point (if all default settings are in use) Kerberos SSO should be working. You can verify this by logging into a work station as a Domain User and browse to the URI mentioned at the end of Section 3. You should not be prompted to provide Credentials (e.g. username/password) when selecting the Active Directory namespace if you have added this website to IE s Local Intranet Security Zone already. If SSO is not working for you at this point please continue and verify all Kerberos Prerequisites mentioned in the next section.

14 5 Kerberos SSO prerequisites The following additional items must be set up for Kerberos SSO/Delegation to function correctly. These include the user account properties of the end user account and the IBM Cognos Express Service account, IIS Application pool account. The latter two will be referred to as Service Accounts. More detailed information on Kerberos Prerequisites can also be found in Technote 1341889 (Scenario 1). 5.1 End User Accounts On your Active Directory Domain Controller open up the Users and Computers MMC snap-in and launch the Account properties dialog for the end user account in question. Ensure that the Account has the Account is sensitive and cannot be delegated property unchecked. If this property is checked, delegation of this account is prohibited and hence Kerberos SSO cannot take place. In some situations it might also be necessary to enable the Account is trusted for Delegation checkbox. E.g. Framework Manager requires this setting to be enabled to achieve seamless sign on to data sources.

15 5.2 Service Accounts On your Active Directory Controller, open the Users and Computers MMC snap-in and launch the Computer properties dialog for the Cognos Express computer account and the Cognos Express Gateway computer account. As pointed out in section 1.2 Applicability this guide assumes that services are running as Local System. If the Service Account has been changed to a Domain User Account then please enable/disable the same properties as outlined in the End User Account section above (including the Account is trusted for delegation property) to enable delegation for such domain service accounts. Ensure that the Computer Account has the property Trust Computer for delegation enabled. If this property is not checked the computer is not allowed to delegate authentication requests and hence Kerberos SSO cannot take place.

16 5.3 Browser Settings Before accessing the IBM Cognos Express Gateway, you must also verify that this website is added to IE s Local Intranet Security Zone on all end-user workstations. Failing to do so might result in a Windows Logon prompt to appear. Internet Explorer will by default only send credentials to websites that are in this zone. You can modify this behavior (although not recommended) on a per Zone basis by configuring a Custom Level. This is done by clicking the Custom Level button on the Security tab of the Internet Options After enabling the Automatic logon with current username and password property in a Zone IE will automatically send on your Network Credentials to any website in this zone that requires authentication. The preferred method though is to add the IBM Cognos Express Gateway to the Local Intranet zone though. Another often occurring issue is URI inconsistency. Always be sure to configure the IBM Cognos Express Server and gateway using the same hostname format throughout. E.g. if you use the host name in the gateway configuration make sure you use the same in the Express server configuration. Note that when using Firefox the network prompt will always appear since seamless sign on is an Internet Explorer only feature.

17 6 Binding the Gateway to a Namespace One side effect of enabling the additional Active directory namespace is that end users will now be prompted to choose a Namespace to log into as shown below: Note that this doesn t mean that SSO isn t working but rather that the content manager needs more information in order to complete the authentication request. If you want to eliminate possible confusion for end users, you can instruct the gateway to select the namespace for you. 1. In the location where you expanded CognosExpressGateway.zip, navigate to the bin directory and locate the file cogconfig.bat and run it. For example, the location is C:\Cognos Express Gateway\bin\cogconfig.bat. 2. In IBM Cognos Configuration, in the Explorer window, click the Environment section. 3. Locate the Gateway Namespace property and fill out the value with the Namespace ID of the Active Directory Namespace (CognosExpressActiveDirectoryID) as shown below. 4. Save the configuration and exit the tool.

18 7 When testing Single Sign On 7.1 HTTP 500 when accessing the portal using CGI This web server error can occur when you are trying to access the Cognos Express Gateway from within a Windows Remote Desktop session to the Cognos Express Server. This behaviour has nothing to do with IBM Cognos Express but rather with how Microsoft Windows, CGI and Remote Desktop work. The workaround for behaviour is to launch Remote Desktop with the /console parameter: mstsc.exe /console 7.2 HTTP 500 when accessing the portal using ISAPI This web server error can occur when you are trying to access the Cognos Express Gateway ISAPI module running on a 64-bit server machine. The root of the problem lies within the IIS application pool configured for the IBM Cognos Express Gateway. Refer back to section 3.2 step 3 for instructions on how to make ISAPI work on a 64-bit IIS instance. 7.3 Single Sign On to Cognos Express doesn t work in Firefox Once Integrated Authentication has been enabled, IIS requires users to be authenticated before it will send them any content. It does this by challenging the end user for credentials. Internet Explorer is able to respond to this Authentication Challenge automatically, if configured correctly, where Firefox is not. As a consequence the Network Logon will always be displayed when accessing the gateway using Firefox. This doesn't mean that Single Sign On to IBM Cognos Express doesn't work in Firefox though. As mentioned before it is the web server that is requiring Authentication and not Cognos Express. Once you respond to the Authentication Request (e.g. provide credentials) you should still be automatically logged into IBM Cognos Express.