IBM Cognos Proven Practices: Enabling Kerberos SSO in IBM Cognos Express on Windows Server 2008

Nature of Document: Guideline; Product(s): IBM Cognos Express; Area of Interest: Infrastructure

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.

Share:

Introduction

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.

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


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

Setting up the Express Gateway

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
    Configure the dispatcher endpoint
  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>

    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.

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.
    Add an Application Pool
  2. Name the application pool and configure the new application pool with the default values *****as demonstrated in the following screen shot*****.
    Application pool properties
  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:
  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.
    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.
    Add Application
    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.
    Application pool settings

Configure and enable the gateway modules

After having created all virtual directories and applications your IIS Manager tree should look similar to this:

Example configuration
  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
    CGI Module MappingFor 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.
    ISAPI Module Mapping
  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)
    CGI restrictionFor ISAPI (select the cognosisapi.dll in the path)
    ISAPI restriction
  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

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.
    Authentication
  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:
    Providers

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.


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

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.

Account is Sensitive Property

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.

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.

Trust Computer for Delegation property

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.

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

Internet Explorer Internet Zone settings

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.


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:

Namespace Prompting

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.
    Gateway Namespace specification
  4. Save the configuration and exit the tool.

When testing Single Sign On

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

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.

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.

Comments

developerWorks: Sign in

Required fields are indicated with an asterisk (*).


Need an IBM ID?
Forgot your IBM ID?


Forgot your password?
Change your password

By clicking Submit, you agree to the developerWorks terms of use.

 


The first time you sign into developerWorks, a profile is created for you. Information in your profile (your name, country/region, and company name) is displayed to the public and will accompany any content you post, unless you opt to hide your company name. You may update your IBM account at any time.

All information submitted is secure.

Choose your display name



The first time you sign in to developerWorks, a profile is created for you, so you need to choose a display name. Your display name accompanies the content you post on developerWorks.

Please choose a display name between 3-31 characters. Your display name must be unique in the developerWorks community and should not be your email address for privacy reasons.

Required fields are indicated with an asterisk (*).

(Must be between 3 – 31 characters.)

By clicking Submit, you agree to the developerWorks terms of use.

 


All information submitted is secure.

Dig deeper into Big data and analytics on developerWorks


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=Big data and analytics, Information Management
ArticleID=630066
ArticleTitle=IBM Cognos Proven Practices: Enabling Kerberos SSO in IBM Cognos Express on Windows Server 2008
publish-date=03022011