...

Integrating IBM Cognos 8 into IBM WebSphere Portal Proven Practice

by user

on
Category: Documents
10

views

Report

Comments

Transcript

Integrating IBM Cognos 8 into IBM WebSphere Portal Proven Practice
Proven Practice
Integrating IBM Cognos 8 into IBM
WebSphere Portal
Product(s): IBM Cognos 8
Area of Interest: Infrastructure
Integrating IBM Cognos 8 into IBM WebSphere Portal
2
Copyright
Copyright © 2008 IBM Cognos ULC (formerly IBM Cognos Incorporated). IBM
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. IBM 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 IBM 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 IBM Cognos. IBM Cognos
and the IBM Cognos logo are trademarks of IBM Cognos ULC (formerly IBM 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 IBM Cognos products can be found at
www.IBM Cognos.com
This document is maintained by the Best Practices, Product and Technology team.
You can send comments, suggestions, and additions to [email protected] .
IBM Cognos Confidential Information
Integrating IBM Cognos 8 into IBM WebSphere Portal
3
Contents
1
INTRODUCTION ............................................................................................ 4
PART 1 – IBM COGNOS’ INTEGRATION INTO IBM WEBSPHERE PORTAL................ 5
IBM COGNOS PORTLETS IN IBM WEBSPHERE ............................................................................ 5
IBM COGNOS PORTLET FEATURES ........................................................................................... 6
PORTAL CONFORMANCE ........................................................................................................ 7
PART 2 – INSTALL AND CONFIGURE IBM COGNOS 8 PORTLETS IN IBM WEBSPHERE
PORTAL..................................................................................................................... 8
INSTALLING THE IBM COGNOS PORTLET IN IBM WEBSPHERE PORTAL .............................................. 8
INITIAL CONFIGURATION .................................................................................................... 11
VIEWING PORTLETS ON A PAGE ............................................................................................ 12
DISTRIBUTED ENVIRONMENTS .............................................................................................. 14
PART 3 – ENABLING SINGLE SIGNON.................................................................... 15
OVERVIEW ...................................................................................................................... 15
PREREQUISITES, NAMESPACE SETTINGS, AND CONFIGURATION ...................................................... 16
SETTING UP SHARED SECRET FOR SSO .................................................................................. 21
ALTERNATIVE METHODS FOR SSO (ASIDE FROM SHARED SECRET) ................................................. 26
PART 4: TROUBLESHOOTING ................................................................................. 29
ERRORS WHEN ANONYMOUS ACCESS IS TO SET TO “TRUE” IN IBM COGNOS CONFIGURATION ................ 29
ERRORS WITH SINGLE SIGNON ............................................................................................. 33
THE CONNECTION SERVER URI ............................................................................................ 37
IBM Cognos Confidential Information
Integrating IBM Cognos 8 into IBM WebSphere Portal
4
1 Introduction
This document provides step-by-step instructions on how to enable install and configure
IBM Cognos 8 BI portlets within IBM WebSphere Portal 5.x. This document contains
detailed information about how to enable Single Signon (SSO) and the relevant
troubleshooting steps required to isolate and resolve the issue.
This document is divided into four main sections:
1. Overview of IBM Cognos’ Portlets
2. Installing and Configuring the IBM Cognos 8 BI Portlets
3. Enabling Single Signon between IBM Cognos and WebSphere Portal
4. Troubleshooting issues relating to the IBM Cognos portlets
Although this document was written specifically for configuring SSO between WebSphere
Portal 5.1 and IBM Cognos 8 MR2, many of the same principles apply to previous and latest
versions of both WebSphere and IBM Cognos.
IBM Cognos Confidential Information
Integrating IBM Cognos 8 into IBM WebSphere Portal
5
Part 1 – IBM Cognos’ Integration into IBM WebSphere Portal
IBM Cognos Portlets in IBM WebSphere
IBM Cognos 8 provides five out-of-the-box portlets for consumer functionality:
ƒ
IBM Cognos Navigator – Allows users to browse through IBM Cognos content and
folders and run reports and pages. Within the Navigator, users can choose the
appropriate action and destination when selecting an object (i.e. launch in new window,
other portlet, etc.).
ƒ
IBM Cognos Search – Allows users to search through IBM Cognos content for relevant
objects (i.e. reports, pages, folders, etc.). The IBM Cognos Search portlet support both
the regular IBM Cognos string search and the full indexed IBM Cognos GO! Search.
Similar with the Navigator, with Search, users can choose the appropriate action and
destination when selecting an object (i.e. launch in new window, other portlet, etc.)
ƒ
IBM Cognos Viewer – Allows users to view reports and pages. Users can specify the
column size of this portlets as well as the default actions.
ƒ
IBM Cognos Metrics Watchlist – Allows users to view the Metrics stored in their
Metrics Manager watchlist. Within this portlet, users can specify the Metrics package
they would like to view.
ƒ
IBM Cognos Extended Applications – Allows developers to build their own portlets
to consume in a third-party Portal. With the IBM Cognos SDK, three open-source
sample portlets are provided (Navigator, Search, and Viewer) along with their source
code. Developers can then modify the source code to create their own unique portlets
to meet their exact business requirements.
IBM Cognos Confidential Information
Integrating IBM Cognos 8 into IBM WebSphere Portal
6
IBM
Cognos
Metrics
Watchlist
IBM
Cognos
Navigato
r
IBM
Cognos
Search
IBM
Cognos
Viewer
IBM Cognos Portlet Features
ƒ
Portlet-to-portlet communication – This feature allows users to select an object in
the Navigator or Search portlet and have this object rendered in the IBM Cognos Viewer
portlet.
ƒ
Customization and personalization – IBM Cognos portlets can be customized to
provide a slightly different look-and-feel. For example, default reports and folders can
be specified – reducing the amount of clicks necessary for the user to view a report.
Additionally with the Navigator and Search, options can be specified to show more or
less information and actions for each user.
ƒ
Extensibility through the SDK – The Extended Applications portlet allows users to
build their own portlet using existing open sourced samples. This is ideal for users to
build powerful portlets to meet their custom business logic and requirements.
ƒ
WSRP Support – The IBM Cognos portlets conform to the WSRP standard and use this
standard protocol when communicating with the IBM Cognos 8 server.
IBM Cognos Confidential Information
Integrating IBM Cognos 8 into IBM WebSphere Portal
ƒ
7
“Ready for IBM WebSphere Portal” Certification – With each major release, IBM
Cognos’ portlets regularly obtain the rigorous IBM certification to be deemed “Ready for
IBM WebSphere Portal”.
Portal Conformance
IBM Cognos has a long history of support with IBM WebSphere Portal. Contained below are
the certified versions of IBM WebSphere Portal for each major version of IBM Cognos BI.
IBM Cognos Version
ƒ
ƒ
IBM Cognos Series 7
IBM Cognos ReportNet
IBM WebSphere Portal Version
ƒ
IBM WebSphere Portal 4.2
ƒ
IBM WebSphere Portal 5.x
ƒ
IBM WebSphere Portal 4.2
ƒ
IBM WebSphere Portal 5.x
ƒ
IBM Cognos 8.1
ƒ
IBM WebSphere Portal 5.x
ƒ
IBM Cognos 8.2
ƒ
IBM WebSphere Portal 5.x
ƒ
IBM WebSphere Portal 6.0
IBM Cognos Confidential Information
Integrating IBM Cognos 8 into IBM WebSphere Portal
8
Part 2 – Install and Configure IBM Cognos 8 Portlets in IBM WebSphere
Portal
Installing the IBM Cognos Portlet in IBM WebSphere Portal
IBM Cognos 8 contains deployment file to automatically deploy and register the IBM Cognos
portlets within IBM WebSphere Portal. In this section, we will deploy the IBM Cognos
portlets (with no authentication) to verify that they function in this environment.
Enable Anonymous Access
Prior to enabling single signon (SSO), it is best to test the IBM Cognos portlets without any
user authentication. To do this:
1. Open the IBM Cognos Configuration tool.
2. Browse to Security > Authentication > IBM Cognos
3. Set Anonymous Access to “True”, as such:
4. Restart the IBM Cognos 8 service for the changes to take effect.
Deploy the IBM Cognos Portlets
IBM Cognos Confidential Information
Integrating IBM Cognos 8 into IBM WebSphere Portal
9
1. Locate WebSphere deployment file. In IBM Cognos 8, the deployment name is IBM
CognosBIPortlets_c81.war (in the /c8/cps/ibm/portlets folder) on the C8 server.
Additional Notes – Within this folder, /c8/cps/ibm folder is a build.properties file. This file
contains all of the default parameters used by the portlets. Users can specify all of the
default values for these portlets ahead of time. Simply modify these parameters to the
desired parameters and double-click on the build.bat file. The IBM
CognosBIPortlets_c81.war file will be updated to reflect this change.
2. Login to IBM WebSphere Portal as an administrative user.
3. Click on the Administration link
4. Click on Portlet Management > Web Modules
IBM Cognos Confidential Information
Integrating IBM Cognos 8 into IBM WebSphere Portal
5.
10
Click “Install”.
6. Browse the /c8/cps/ibm/portlets/CognosBIPortlets_c81.war file and install.
7. Once the portlets have been installed, a list of the deployed portlet applications will be in
the Portlet Management > Applications folder. To filter this list, search on “IBM
Cognos”.
8. If the IBM Cognos portlets do not appear in the list, it is likely that an error has occurred
during the installation. Repeat the steps above or contact your Portal administrator.
IBM Cognos Confidential Information
Integrating IBM Cognos 8 into IBM WebSphere Portal
11
Initial Configuration
Once the portlets have been successfully deployed, some initial configuration can be done
to ensure that the portlets are functionality correctly. To do this:
1. In the Portlet Management > Applications screen, edit the “IBM Cognos BI Content
Portlets” by clicking on the edit on the right (
). This will display a list of the portlet
preferences and properties.
2. Delete the “IBM Cognos 8 WSRP WSDL Location” parameter by clicking on the delete
button (
).
3. Click OK.
4. Edit the IBM Cognos BI Content Portlets.
5. Under “New Parameter”, type in “IBM Cognos 8 WSRP WSDL Location”. Under “New
Value”, type in: http://server-name/Cognos8/cgi-bin/
Cognos.cgi/wsrp/cps4/portlets/nav?wsdl&b_action=cps.wsdl (substituting server-name
for the C8 server). Click “Add”.
6. The new value will now be shown in the list below.
IBM Cognos Confidential Information
Integrating IBM Cognos 8 into IBM WebSphere Portal
12
7. Repeat this step for the “IBM Cognos Metrics Manager Watchlist” application.
Viewing Portlets on a Page
The installation and initial configuration is now complete. The final step is to place these
portlets on a page for consumption. To do this:
1. Within the Administration area, click on Portlet User Interface > Manage Pages. In the
list, click on “My Portal”.
2. Click on New Page to create a new page. (In this example, a new page will be created
as a main tab. By drilling down within the subfolders, we can create a page and have it
appear as a sub-tab within an existing main tab).
3. The new page will now appear in the page list.
IBM Cognos Confidential Information
Integrating IBM Cognos 8 into IBM WebSphere Portal
13
4. Edit this page. Within this page, add some portlets to the page. It is often easiest to
search for “IBM Cognos” in the title to filter the list.
5. As a first step, it is often easiest to add only one portlet to the page.
6. View the page to ensure that the portlets are working correctly. In this case, the IBM
Cognos Navigator was the only portlet added to the page.
7. When the portlets are working correctly, you can add some additional portlets to the
page, lay it out to the desired specification, and start to personalize and customize the
page.
IBM Cognos Confidential Information
Integrating IBM Cognos 8 into IBM WebSphere Portal
14
Distributed Environments
In an environment where the IBM Cognos Gateway and the IBM Cognos Dispatcher are
running on separate servers, an additional setting needs to be enabled. The _gatewayURL
parameter needs to point to the IBM Cognos gateway, while the IBM Cognos 8 WSRP WSDL
Location will point to the dispatcher server, as such:
IBM Cognos 8 WSRP WSDL Location
http://dispatcher-server/Cognos8/cgi-
bin/Cognos.cgi/wsrp/cps4/portlets/nav?wsdl&b_action=cps.wsdl
_gatewayURL
IBM Cognos Confidential Information
http://gateway-server/Cognos8
Integrating IBM Cognos 8 into IBM WebSphere Portal
15
Part 3 – Enabling Single Signon
Overview
There are a variety of different options for single signon (SSO) from WebSphere Portal to
IBM Cognos. The different techniques depend on specific customer needs and
requirements. At a high-level, these requirements can be summarized as either using
regular SSO or leveraging IBM’s LPTA Token. Additional details on the differences and how
we handle complex situations will be discussed further along in this document. At a highlevel, we have three different ways to handle single signon:
1. Shared Secret
2. Native C8 SSO
3. LPTA Token
Shared Secret
“Shared Secret” is a IBM Cognos-specific method for handling SSO. The IBM Cognos
Portlets 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 setup. It can be used in most
environments, as long as the following conditions are met:
ƒ
The Portal User ID (used to log into WebSphere 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 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.
IBM Cognos 8 SSO
IBM Cognos Confidential Information
Integrating IBM Cognos 8 into IBM WebSphere Portal
16
There are many different ways to accomplish SSO directly into IBM Cognos Connection. All
of these techniques can be used in IBM Cognos’ portlets. This allows IBM Cognos’ portlets
to support third-party authentication providers, like Netegrity.
LPTA Token
LTPA token is an SSO methods implemented by the WebSphere Application Server (WAS).
By passing a token across servers, the host applications can share the user’s identity and
trust that it has been validated and properly secured. The LTPA token is processed by the
Application server’s security layer. Although WebSphere Portal only executes in the context
of the IBM WAS, IBM Cognos 8 server can execute in alternate applications servers. To
take advantage of security provided at the Application server level, a dedicated IBM Cognos
8 Servlet Gateway must be installed and configured. By default, IBM Cognos 8 runs using
Tomcat Application Server. Since Tomcat does not support LTPA token, a IBM Cognos
servlet gateway needs to be installed running on WAS. This WAS needs to be able to
accept tokens from the WAS hosting WPS.
Determining the Proper SSO Method
Shared Secret is the simplest to setup and can be used in almost all situations, except if you
are using a custom authentication provider or if you wish to leverage LPTA Token.
Prerequisites, Namespace Settings, and Configuration
Disable NT Challenge Response (for IIS)
In IIS, when NT Authentication is enabled, it requires the Web browser to handle the
authentication request. That is, instead of prompting the user with a windows
authentication box, the browser will automatically answer this request. This sort of NT
authentication cannot be handled within a portlet. To disable NT challenge:
1. Open IIS on the IBM Cognos 8 server.
2. Right-click on the IBM Cognos8 virtual directory and select properties.
3. Go to Directory Security and under “Anonymous Access and Authentication Control”,
click “edit”.
IBM Cognos Confidential Information
Integrating IBM Cognos 8 into IBM WebSphere Portal
17
4. Uncheck “Integrated Windows Authentication”. Make sure that Anonymous Access is
checked.
5. Open IBM Cognos Connection (http://server-name/Cognos8) to make sure that the IBM
Cognos Web application can still be viewed.
Namespace Settings
1. LDAP Namespaces
The IBM Cognos portlets set the value of remote_user to be the User ID of WebSphere
Portal user. As a result, we need to make sure that the LDAP namespace defined in IBM
Cognos Configuration can handle this. In many cases, if the user IDs are identical in both
the IBM Cognos and WebSphere Portal namespace, then you only need to set the External
Identity Mapping value to ${environment(“REMOTE_USER”)}, as shown below.
1. Open IBM Cognos Configuration associated with each IBM Cognos 8 BI server and locate
your LDAP namespace.
IBM Cognos Confidential Information
Integrating IBM Cognos 8 into IBM WebSphere Portal
18
2. Enable External Identity mapping by setting the following fields:
Use external identity mapping
True
External identity mapping
(uid=${environment("REMOTE_USER")})
Important: Do not forget the parentheses around the external identity mapping value.
3. Save the Configuration and restart the service for these changes to take effect.
In other cases, users may be using a different namespace in both IBM Cognos and in
WebSphere Portal. In this case, the User IDs may be slightly different. In particular, either
IBM Cognos or WebSphere Portal may append a domain prefix ahead of the User ID. In
these cases, we would need to remove the domain so that we are mapping the same User
IDs. Some examples are included below:
Example 1: WebSphere Portal User ID = domain1/administrator, IBM Cognos
User ID = administrator
In this case, we would need to ignore the “domain” prefix ahead of WebSphere
Portal User ID. This can be done by setting the External Identity Mapping variable
to:
(uid=${replace(${environment("REMOTE_USER")},"domain1 \\",)})
Example 2: WebSphere Portal User ID = administrator, IBM Cognos User ID
= domain2/administrator
In this case, we would need to ignore the “domain” prefix ahead of WebSphere
Portal User ID. This can be done by setting the External Identity Mapping variable
to:
(uid=${replace(${environment("REMOTE_USER")},"domain1 \\",)})
IBM Cognos Confidential Information
Integrating IBM Cognos 8 into IBM WebSphere Portal
19
Example 3: WebSphere Portal User ID = domain1/administrator, IBM Cognos
User ID = domain2/administrator
In this case, we would need to ignore the “domain” prefix ahead of WebSphere
Portal User ID. This can be done by setting the External Identity Mapping variable
to:
(|(uid=${replace(${environment("REMOTE_USER")},"domain1
\\",)})(uid=${replace(${environment("REMOTE_USER")},"domain2
\\",)}))
Refer to the troubleshooting section for more information on how to determine the correct
User IDs.
2. Active Directory
As mentioned above, the IBM Cognos portlets set the value of remote_user to be the User
ID of WebSphere Portal user. As a result, we need to make sure that the Active Directory
namespace defined in IBM Cognos Configuration can handle this. In many cases, if the user
ID is identical in both the IBM Cognos and WebSphere Portal namespace, then you only
need to set the singleSignonOption to IdentityMapping. To do this:
1. Open IBM Cognos Configuration associated with each IBM Cognos 8 BI server and locate
your LDAP namespace.
2. Under “Advanced Properties”, click edit.
IBM Cognos Confidential Information
Integrating IBM Cognos 8 into IBM WebSphere Portal
20
3. Type in “singleSignonOption” for the name and “IdentityMapping” for value.
4. Save the Configuration and restart the service for these changes to take effect.
3. Series 7 SunOne LDAP
IBM Cognos Confidential Information
Integrating IBM Cognos 8 into IBM WebSphere Portal
21
Similarly, in a Series 7 namespace, we need to make sure that the namespace can leverage
the remote_user value. Series 7 LDAPs are commonly exclusively only used in the IBM
Cognos environments while the other applications contain another LDAP. As a result, the
User IDs in both IBM Cognos and WebSphere Portal are often slightly different. In most
cases, WebSphere Portal’s namespace will have a different alias or include a domain prefix.
Set OS Signon
1. In Access Manager, right-click on the default namespace and select Properties >
Signon.
2. Make sure that “Both” is checked under signons (and not “basic” or “OS”).
Account for Different User Aliases
1. In Access Manager, browse to an actual user within Access Manager
2. Right-click on the user and select Properties > OS Signon.
3. Within the OS Signons, make sure that this window contains all of the correct user
aliases. For example, WebSphere Portal will often grab the user ID and include
domain prefixes ahead of WebSphere Portal UID. For these situations, add new
users with these prefixes.
Additional Notes:
ƒ
To understand the exact User IDs for both WebSphere Portal and the IBM Cognos
namespaces, refer to the troubleshooting section below.
ƒ
For additional information on security and authentication, refer to the “Security” section
of the proven practice site: http://provenpractice.
Setting Up Shared Secret for SSO
At this point, we can now start to enable SSO for the IBM Cognos portlets. To do this:
Step 1 – Configure the Trusted Signon Namespace
1. Start IBM Cognos Configuration. For a distributed install with several IBM Cognos 8 BI
servers, configure all servers.
2. Under Security/Authentication, add a new namespace
IBM Cognos Confidential Information
Integrating IBM Cognos 8 into IBM WebSphere Portal
Name = CPSTrusted
Type = Custom Java Provider
3. In the namespace fields, enter the following:
Namespace ID
= CPSTrusted
Java class name
= com.IBM
Cognos.cps.auth.CPSTrustedSignon
(Note: All values are case sensitive and must be entered as is)
4. Under Environment, open WebSphere Portal Services section.
Set the following fields:
Trusted Signon NamespaceID
= <ID of your authentication
namespace>
Shared Secret
Where:
IBM Cognos Confidential Information
= <The shared secret string>
22
Integrating IBM Cognos 8 into IBM WebSphere Portal
ƒ
23
<ID of your authentication namespace> is the ID of the namespace associated
with the Directory Server used to authenticate portlet 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).
ƒ
<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.
Additional Notes:
ƒ
If your directory namespace is of type LDAP, enable External User mapping. See the
Namespace Configuration section above for more information.
ƒ
If your directory namespace is of type Active Directory, enable Identity Mapping.
See the Namespace Configuration section above for more information.
ƒ
If your directory namespace is of type Series7, enable OS Signon. See the
Namespace Configuration section above for more information.
ƒ
The troubleshooting section of this document contains additional information relating
to namespace settings.
5. Under Security > Authentication > IBM Cognos, set “use anonymous access” to false.
6. Save the configuration and restart IBM Cognos 8.
7. Repeat these steps for all IBM Cognos 8 BI servers in a distributed install.
Step 2 – Set “Allow Namespace Override”
1. In IBM Cognos Configuration, go to Local Configuration > Environment.
2. Under the setting “Allow Namespace Override”, set this to “true”, as shown below.
IBM Cognos Confidential Information
Integrating IBM Cognos 8 into IBM WebSphere Portal
24
This step is necessary for WebSphere Portal to know which namespace to authenticate
its users against.
3. Save this configuration and restart the IBM Cognos service. (Note, if you have multiple
installs, you need to configure this on each server.)
Note:
ƒ
In this section, we created a new namespace. As a result, when the user accesses IBM
Cognos Connection, they will be prompted to select a namespace. To avoid, you can set
the IBM Cognos gateway to only use one namespace. For example, suppose that I have
an LDAP that I use for authentication. Since another namespace has been created
(CPSTrusted), the user will be prompted to select one of these namespaces.
ƒ
To avoid this, in IBM Cognos Configuration, go to Environment. Under “Gateway
Namespace”, set this to your authentication namespace (i.e. LDAP, ADS, Series7, etc.)
Step 3 – Configure the IBM Cognos Portlet applications in WebSphere Portal
1. Login to WebSphere Portal as an administrator
2. Go to Administration Æ Portlet Management Æ Applications and locate the three IBM
Cognos portlet applications:
IBM Cognos Confidential Information
Integrating IBM Cognos 8 into IBM WebSphere Portal
25
1. IBM Cognos BI Content Portlets
2. IBM Cognos Extended Applications Portlets
3. IBM Cognos Metric Manager Portlets
3. For each IBM Cognos application, set the following fields:
IBM Cognos 8 WSRP WSDL Location <connection server URI>l
cps_auth_secret
<The shared secret string>
cps_auth_namespace
<The CPS namespace> (i.e. CPSTrusted)
Active Credential Type
(none)
The Authorization secret must be the same as the one set in “Step 2” above. When using
Shared secret, it is important to leave Active Credential Type as (none).
Remember that you must set up the shared secret and WSDL location for each IBM
Cognos application.
Step 4 – Test the IBM Cognos Portlets
1. Place the IBM Cognos Portlets on a page and grant access permissions for these portlets
to WebSphere Portal users that will be using IBM Cognos.
2. Logon to WebSphere Portal with a User ID that is common to both WebSphere and IBM
Cognos.
3. View the page and notice that the IBM Cognos portlets.
IBM Cognos Confidential Information
Integrating IBM Cognos 8 into IBM WebSphere Portal
26
Alternative Methods for SSO (aside from Shared Secret)
Shared Secret is the recommended method for handling SSO – primarily because it is the
simplest to setup and it can be used in almost all cases. There are some instances where
users may prefer to use alternate methods.
Leveraging Native IBM Cognos 8 SSO
If you have already enabled SSO into IBM Cognos 8, then you can leverage these
techniques with the IBM Cognos portlets. More specifically, if WebSphere Portal and IBM
Cognos use the same namespace for authentication, then this namespace can used in
WebSphere Portal, instead of the CPSTrusted namespace.
Additional Notes:
ƒ
The portlets do not work with any NT Challenge response. Therefore, make sure that
SSO can be done into IBM Cognos Connection without this challenge response.
ƒ
For more information on this, visit the Security section of the proven practice site:
http://provenpractice.
Using LTPA Token for SSO
Using LTPA token as the main single signon mechanism between WebSphere Portal and the
IBM Cognos portlets involves the user having administrator access rights to the WebSphere
Application Server running the IBM Cognos 8 server. If the IBM Cognos 8 server does run
in a WebSphere Application Server environment, you must at least install the IBM Cognos 8
Servlet Gateway onto a WebSphere Application Server.
For LTPA Token to work properly, the following conditions must be met:
ƒ
The IBM Cognos 8 Servlet Gateway must be installed as a secured application in a
WebSphere Application Server.
ƒ
IBM Cognos 8 and WebSphere Portal must both access the same LDAP server for
authentication.
Step 1 – Set “Allow Namespace Override”
1. In IBM Cognos Configuration, go to Local Configuration > Environment.
2. Under the setting “Allow Namespace Override”, set this to “true”, as shown below.
IBM Cognos Confidential Information
Integrating IBM Cognos 8 into IBM WebSphere Portal
27
This step is necessary for Plumtree to know which namespace to authenticate its users
against.
3. Save this configuration and restart the IBM Cognos service. (Note, if you have
multiple installs, you need to configure this on each server.)
Step 2 – Deploy and Secure the Servlet Gateway as a WebSphere Application
This step requires administration privileges in the WebSphere Application server.
1. On the alternate gateway, build a WAR or EAR file to deploy into the WebSphere
Application Server (as described in the IBM Cognos 8 Administration & Security Guide).
2. Deploy the alternate gateway onto the WebSphere Web Application Server
3. In the WebSphere Administration console, secure access to the gateway application via
LTPA token. Configure it to access the same LDAP directory as WebSphere Portal.
Consult your WebSphere Application Server administration manuals for further details.
Step 3 – Configure the IBM Cognos Portlet Applications in WebSphere Portal
1. Login to WebSphere Portal as an administrator.
2. Go to Administration Æ Portlet Management Æ Applications and locate the three IBM
Cognos portlet applications:
IBM Cognos Confidential Information
Integrating IBM Cognos 8 into IBM WebSphere Portal
28
4. IBM Cognos BI Content Portlets
5. IBM Cognos Extended Applications Portlets
6. IBM Cognos Metric Manager Portlets
3. For each IBM Cognos application, set the following fields:
IBM Cognos 8 WSRP WSDL Location <connection server URI>l
cps_auth_secret
<The shared secret string>
cps_namespace
<The authentication namespace> (i.e.
Active Credential Type
(none)
IBM Cognos 8 namespace.)
Important: The connection server is to contain the Uri to access the WSDL location via the
alternate gateway.
In this case, the alternate gateway is a Servlet Gateway running inside a WebSphere
Application server. The Active Credential Type is the key to enabling the sending of the
LTPA token back to the Alternate Gateway. Make sure the spelling for LTPAToken is exact.
Step 4 – Configure the LDAP namespace in IBM Cognos 8
All communications from the IBM Cognos portlets to the Servlet Gateway will carry the LTPA
Token. When receiving those connections, the Application Server will look up the user ID
(from the LTPA token) into the associated LDAP directory. When the User ID is found, the
Application Server will set up the REMOTE_USER HTTP variable to the ID of the current
user. This variable is then propagated by the Servlet Gateway to the IBM Cognos 8 server
where it is looked-up again in the attached LDAP namespace.
Additional Notes:
IBM Cognos Confidential Information
Integrating IBM Cognos 8 into IBM WebSphere Portal
ƒ
29
For the IBM Cognos 8 LDAP and AD namespaces to map user IDs correctly, external
user mapping needs to be enabled.
ƒ
For more information on LPTA Token, refer to the document on LPTA Tokens and SSO
on the proven practice site, http://provenpractice.
Part 4: Troubleshooting
In this section, it is important to first isolate this issue to either an error with the portlets or
an error with SSO.
Errors when Anonymous Access is to set to “True” in IBM Cognos Configuration
When Anonymous Access is enabled, users get an error when trying to access IBM Cognos’
portlets through WebSphere Portal (i.e. getMarkup Failed). In most cases, these errors are
a result of WebSphere Portal not being able to access the IBM Cognos 8 server.
Access to the IBM Cognos WSDL
Place the following URL in a Web browser and ensure that you can view the WSDL:
http://server-name/Cognos8/cgibin/Cognos.cgi/wsrp/cps4/portlets/nav?wsdl&b_action=cps.wsdl
Disable NT Challenge in IIS
IBM Cognos Confidential Information
Integrating IBM Cognos 8 into IBM WebSphere Portal
30
If you are using IIS as a Web Server, make sure that “Anonymous Access” is enabled and
“Integrated Windows Authentication” is disabled for the IBM Cognos8 virtual directory.
Once this has been enabled, ensure that you can get to IBM Cognos Connection (i.e.
http://machine-name/Cognos8) without any access error messages.
Trace SOAP Messages through TCPMon
TCPMon is a IBM Cognos troubleshooting utility that traces all of the SOAP messages
between the client and the IBM Cognos server. This utility can be enabled to trace all
communication between WebSphere Portal and IBM Cognos 8. To do this:
1. Open tcpmon.bat. This utility can be found in the /c8/webapps/p2pd/WEB-INF folder.
IBM Cognos Confidential Information
Integrating IBM Cognos 8 into IBM WebSphere Portal
31
2. The tcpmon utility will open.
3. Under “Listen Port #”, provide a port number that is not used by any other application
(i.e. 9393). Under the “Target Port #”, change this to 80. Click Add.
4. A new tab will appear, as such:
IBM Cognos Confidential Information
Integrating IBM Cognos 8 into IBM WebSphere Portal
32
This means that all requests will be made through port 9393. This means that if you get an
error accessing the WSDL, then you can add port 9393 to the WSDL address, as such:
http://server-name:9393/ Cognos8/cgibin/Cognos.cgi/wsrp/cps4/portlets/nav?wsdl&b_action=cps.wsdl
In most cases, users are able to retrieve the WSDL in a new browser, but they are unable to
view the IBM Cognos portlets through WebSphere Portal. A good next step is to place this
port number in the WSDL location in WebSphere Portal, as such:
IBM Cognos Confidential Information
Integrating IBM Cognos 8 into IBM WebSphere Portal
33
When you reproduce this issue in WebSphere Portal, the tcpmon utility will now trace all of
the communication between WebSphere Portal and the IBM Cognos server. In particular,
you will want to make sure there are not any proxy servers or firewalls that are blocking
these requests.
Errors with Single Signon
When Anonymous Access is set to False in IBM Cognos Configuration, the portlets need to
handle authentication through the CPS trusted signon provider. Issues that are specific to
SSO usually begin with the error message “initcookie failed”. These error messages are
then usually followed by a “user didn’t specify a namespace” or “credentials are
invalid” error message.
“initcookie failed. User didn’t specify a namespace” error message appears
In most cases, this error message is a result of no namespace being defined in WebSphere
Portal. There are a few settings to verify:
1. In WebSphere Portal, make sure that the setting cps_auth_namespace is populated with
the CPSTrusted namespace ID.
IBM Cognos Confidential Information
Integrating IBM Cognos 8 into IBM WebSphere Portal
34
2. Make sure that the cps_auth_secret value matches the setting defined in IBM Cognos
Configuration > WebSphere Portal Services.
“initcookie failed. User credentials are invalid” error message appears
These issues tend to involve more involved troubleshooting. In most cases, the issue is that
the User ID in WebSphere Portal is not the exact same as the User ID in IBM Cognos – due
to a prefix or different domain. To isolate this issue, it is required that additional logging is
enabled to identify the User IDs in both IBM Cognos and in WebSphere Portal.
Enable IPF Logging
To enable IPF logging:
1. Save the attached file to the /c8/configuration folder on the IBM Cognos 8 server.
ipfclientconfig.xml
2. Restart the IBM Cognos 8 service for the logging to begin.
3. When the IBM Cognos 8 service has started, two new logs files will be present in the
/c8/logs folder: cps.log (traces the portlets requests) and cam.log (traces the
authentication requests).
4. Login to WebSphere Portal using a User ID that is valid in both WebSphere Portal and
IBM Cognos.
Analyzing the Log Files
CPS.log File
IBM Cognos Confidential Information
Integrating IBM Cognos 8 into IBM WebSphere Portal
35
In the cps.log file, we will be able to view the entries from the portlets. In particular, you
should notice the following entries:
10.66.31.81:9300 4280
2007-02-07 10:36:30.915
-5
Thread-64
cps
0
4
Trace.cps <trace>DEBUG: value for cookie
'cps_auth_user' is: administrator 1170862587781 d678e5d5a0f670ce0b628ca7f9d2b36d9fe72c34</trace>
com.IBM Cognos.cps.auth.CPSTrustedSignon
10.66.31.81:9300 4280
2007-02-07 10:36:30.915
-5
Thread-64
cps
0
4
Trace.cps <trace>DEBUG: Setting namespace:
S7_LDAP</trace> com.IBM Cognos.cps.auth.CPSTrustedSignon
10.66.31.81:9300 4280
2007-02-07 10:36:30.915
-5
Thread-64
cps
0
4
Trace.cps <trace>DEBUG: Tokens:administrator,
1170862587781, d678e5d5a0f670ce0b628ca7f9d2b36d9fe72c34, administrator 1170862587781</trace>
com.IBM Cognos.cps.auth.CPSTrustedSignon
10.66.31.81:9300 4280
Thread-64
user</trace>
2007-02-07 10:36:30.915
cps
0
4
-5
Trace.cps <trace>DEBUG: setting remote
There are a few entries to note:
cps_auth_user – Ensure that WebSphere Portal is grabbing the User ID that corresponds
to the appropriate LDAP. In this case, the UID is “administrator”.
ƒ
Null User ID – If this field is <null>, then the IBM Cognos portlets are not able to
retrieve a valid UID. Ensure that the namespace used in WebSphere Portal has the
“uid” field populated.
ƒ
Incorrect User ID – If this field contains a prefix, then you will need to make sure that
the namespace defined in IBM Cognos Configuration can handle this prefix. See the
section on namespaces for more information on this topic.
Setting namespace – Ensure that the correct namespace is being used
ƒ
Empty Namespace or Incorrect Namespace – Make sure that the namespace
mapping in IBM Cognos Configuration is correct. In the Configuration tool, go to
WebSphere Portal Services and ensure that the correct namespace is being used.
Remote User – Ensure that an entry for “setting remote user” is present. In this stage,
the IBM Cognos portlets will set a remote_user variable that CAM will use for authentication.
IBM Cognos Confidential Information
Integrating IBM Cognos 8 into IBM WebSphere Portal
36
CAM.log File
In the cam.log file, we will be able to view how CAM is using these variables for
authentication. We will also be able to determine any errors in the process:
1. Search the CAM log to make sure that CAM is getting this User ID:
<bus:dispatcherTransportVars xsi:type="SOAP-ENC:Array" SOAP-ENC:arrayType="bus:dispatcherTransportVar[3]">
<item xsi:type="bus:dispatcherTransportVar">
<name xsi:type="xsd:string">html</name>
<value xsi:type="xsd:string">false</value>
</item>
<item xsi:type="bus:dispatcherTransportVar">
<name xsi:type="xsd:string">front</name>
<value xsi:type="xsd:string">false</value>
</item>
<item xsi:type="bus:dispatcherTransportVar">
<name xsi:type="xsd:string">originalSOAPAction</name>
<value xsi:type="xsd:string">urn:oasis:names:tc:wsrp:v1:initCookie</value>
</item>
</bus:dispatcherTransportVars>
<bus:hdrSession xsi:type="bus:hdrSession">
<bus:cookieVars xsi:type="SOAP-ENC:Array" SOAP-ENC:arrayType="bus:cookieVar[1]">
<item xsi:type="bus:cookieVar">
<name xsi:type="xsd:string">cps_auth_user</name>
<value xsi:type="xsd:string">administrator 1170863119703
832e65b0b56b9815cf322dbe0343e8188661d302</value>
</item>
</bus:cookieVars>
<bus:environmentVars xsi:type="SOAP-ENC:Array" SOAPENC:arrayType="bus:environmentVar[1]">
<item xsi:type="bus:environmentVar">
<name xsi:type="xsd:string">CAMNamespace</name>
<value xsi:type="xsd:string">cpstrusted</value>
</item>
</bus:environmentVars>
<bus:formFieldVars xsi:type="SOAP-ENC:Array" SOAP-ENC:arrayType="bus:formFieldVar[0]"/>
<setCookieVars xsi:type="SOAP-ENC:Array" SOAP-ENC:arrayType="bus:setCookieVar[1]">
<item xsi:type="bus:setCookieVar">
<name xsi:type="xsd:string">CRN</name>
<value
xsi:type="xsd:string">contentLocale%3Den%26productLocale%3Den%26format%3DHTML%26timeZoneID%3DEST%26useA
ccessibilityFeatures%3Dfalse%26skin%3Dcorporate%26listViewSeparator%3Dnone%26automaticPageRefresh%3D30%26sho
wOptionSummary%3Dtrue%26linesPerPage%3D15%26displayMode%3Dlist%26columnsPerPage%3D3%26showWelcomePag
e%3Dtrue%26</value>
<maxAge xsi:type="xsd:int">0</maxAge>
</item>
</setCookieVars>
</bus:hdrSession>
2. If we get a valid User ID and Namespace, then we will want to make sure that the User
ID (administrator) matches the user ID that we would get when we login to IBM Cognos
Connection directly.
3. Login to IBM Cognos Connection as the same user.
4. Open the cam.log file and search for the last log entry containing this User ID (i.e.
administrator).
IBM Cognos Confidential Information
Integrating IBM Cognos 8 into IBM WebSphere Portal
37
<bus:formFieldVars xsi:type="SOAP-ENC:Array" SOAP-ENC:arrayType="bus:formFieldVar[8]">
<item>
<name xsi:type="xsd:string">CAMUsername</name>
<value xsi:type="xsd:string">administrator</value>
</item>
<item>
<name xsi:type="xsd:string">encoding</name>
<value xsi:type="xsd:string">UTF-8</value>
</item>
<item>
<name xsi:type="xsd:string">m</name>
<value xsi:type="xsd:string">portal/main.xts</value>
</item>
<item>
<name xsi:type="xsd:string">CAMPassword</name>
<value xsi:type="xsd:string"/>
</item>
<item>
<name xsi:type="xsd:string">b_action</name>
<value xsi:type="xsd:string">xts.run</value>
</item>
<item>
<name xsi:type="xsd:string">CAMNamespaceDisplayName</name>
<value xsi:type="xsd:string">john</value>
</item>
<item>
<name xsi:type="xsd:string">startwel</name>
<value xsi:type="xsd:string">yes</value>
</item>
<item>
<name xsi:type="xsd:string">CAMNamespace</name>
<value xsi:type="xsd:string">john</value>
</item>
</bus:formFieldVars>
5. Additionally, remote_user should be set through identitymapping.
<item>
<name xsi:type="xsd:string">REMOTE_USER</name>
<value xsi:type="xsd:string"/>domain\administrator</value>
</item>
6. Make sure the User ID from #4 and #5 matches the User ID from #1. Refer to the
section in Part 2 on above on Namespace Settings for the correct values.
The Connection Server URI
The “Connection Server URI” is the server connection between the Enterprise Portal and
IBM Cognos. This is the value to be set for each IBM Cognos Portlet or iView in the CPS:
Connection Server property. The connection URI will differs depending on the type of
alternate gateway and the type of portlet
Type of Alternate Gateway
IBM Cognos Confidential Information
Integrating IBM Cognos 8 into IBM WebSphere Portal
Gateway
38
Connection Server URI
Example URI
CGI
http://<gateway:port>/<directory>/cgi
http://myserver/cpsgateway/
Gateway
-bin/
cgi-bin/
Cognos.cgi/wsrp/cps4/portlets/nav?wsd
Cognos.cgi/wsrp/cps4/portlet
l&b_action=cps.wsdl
s/nav?wsdl&b_action=cps.w
Type
sdl
ISAPI
http://<gateway:port>/
http://myserver/
Gateway
Cognosisapi.dll/wsrp/cps4/portlets/nav?
Cognosisapi.dll/wsrp/cps4/po
wsdl&b_action=cps.wsdl
rtlets/nav?wsdl&b_action=cp
s.wsdl
Servlet
http://<servletgateway:port>/wsrp/cps
http://myserver:8080/wsrp/c
Gateway
4/portlets/nav?wsdl&b_action=cps.wsdl
ps4/portlets/nav?wsdl&b_act
ion=cps.wsdl
IBM Cognos Confidential Information
Integrating IBM Cognos 8 into IBM WebSphere Portal
39
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
IBM Cognos
End
Example
Point
/nav?
http://myserver/cpsgateway/cgi-bin/
Navigator
Cognos.cgi/wsrp/cps4/portlets/nav?wsdl&b_action
IBM Cognos
=cps.wsdl
Search
IBM Cognos
Viewer
Metric Manager
/cmm?
Watchlist
http://myserver/cpsgateway/cgi-bin/
Cognos.cgi/wsrp/cps4/portlets/cmm?wsdl&b_actio
n=cps.wsdl
IBM Cognos
/sdk?
http://myserver/cpsgateway/cgi-bin/
Extended
Cognos.cgi/wsrp/cps4/portlets/sdk?wsdl&b_action
Applications
=cps.wsdl
IBM Cognos Confidential Information
Fly UP