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 content is part # of # in the series: IBM Cognos Proven Practices
This content is part of the series:IBM Cognos Proven Practices
Stay tuned for additional content in this series.
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.
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:
Setting up the Express Gateway
Installing the Express Gateway
- 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.
- Copy this archive to the designated Web server (either the local Cognos Express Server or a standalone Web Server box).
- 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.
- 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. This file launches IBM Cognos Configuration.
- In IBM Cognos Configuration, in the Explorer window, click the Environment section.
- 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
- Save the configuration and exit IBM Cognos Configuration. Note that for the save to be successful the IBM Cognos Express service must be running.
- On the server where IBM Cognos Express is installed, locate the file
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>
- Save this file and restart the IBM Cognos Express service.
Configure IIS7 Virtual Directories
- Create a new application pool for IBM Cognos Express to reside in by right clicking “Application Pools” in IIS Manager.
- Name the application pool and configure the new application pool with the default values *****as demonstrated in the following screen shot*****.
- Right-click the above created application pool and select “Advanced Settings”. In the dialog box set the “Enable 32-bit applications” property to True:
- Create the following two new virtual directories in the Web
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.
- Create the following new application under the IBMCognosExpress
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.
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.
Configure and enable the gateway modules
After having created all virtual directories and applications your IIS Manager tree should look similar to this:
- Select the cgi-bin application as shown above and on the right hand side select “Handler Mappings” in the feature view.
- In the handler mapping screen click on “add Module
Mapping“ and configure your desired Gateway
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.
- 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
For CGI (select the cognos.cgi in the path) For ISAPI (select the cognosisapi.dll in the path)
- Now you should be able to access the gateway using the following
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:
- Select the IBMCognosExpress virtual directory and open the “Authentication” feature.
- In the Authentication feature, ensure that Anonymous access has been disabled and Windows Authentication has been enabled.
- Select “Windows Authentication“ and then click “Providers”. Verify that the Negotiate provider is listed on the very top as demonstrated below:
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:
- Open up Express Manager and click on the Configure button in the “Manager” Section. This should bring up a popup window.
- 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.
- 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.
- 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.
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.
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.
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.
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.
- 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.
- In IBM Cognos Configuration, in the Explorer window, click the Environment section.
- Locate the Gateway Namespace property and fill out the value with the Namespace ID of the Active Directory Namespace (CognosExpressActiveDirectoryID) as shown below.
- 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.