Integrating IBM WebSphere Portal 6 with IBM Cognos 8 Business Intelligence through secured-way SSO
Ahmed Farouk A. Sattar
IBM Software Group
Application and Integration Middleware Software
Cairo, Egypt
September 2009
Summary: This article provides step-by-step instructions on how to integrate and enable single sign-on (SSO) with IBM Cognos Portal Services (CPS) in IBM WebSphere Portal 6.1.
Table of Contents
1 Introduction 2
2 Installing the Portlet Applications file 2
3 Configuring the portlet applications and enabling SSO between Cognos and WebSphere Portal 3
3.1 Shared Secret method 4
3.2 LTPA Token method 8
3.3 Alternate methods 12
4 Configuring the portlet cache 13
5 Customizing/testing the content of Cognos portlets 13
5.1 Testing the Cognos portlets 14
6 Troubleshooting 14
7 Resources 15
About the author 15
1 Introduction
Before you can add IBM Cognos portlets to their IBM WebSphere Portal pages, you must deploy the Cognos portlets to the WebSphere Portal server. The types of IBM Cognos portlets you can deploy are:
Cognos Content portlets. This group includes Cognos Navigator, Cognos Search, and Cognos Viewer.
Cognos Extended Applications portlets. This group includes the Cognos Extended Applications portlet.
Metric Studio portlets. This group includes the Metric List and Metric History Chart portlets.
The deployment process consists of the following five tasks, which we discuss in this article:
1. Installing the portlet applications file.
2. Configuring the portlet applications and enabling Single-Sign-On between Cognos and Portal.
3. Configuring the portlet cache.
4. Customizing the content of Cognos portlets.
5. Testing the Cognos portlets.
2 Installing the Portlet Applications file
Before Cognos content can appear in any WebSphere page, you must install the portlet applications file named “CognosBIPortlets_c83.war”, located in the
c8_location\cps\ibm\portlets directory.
This file contains the applications for the Cognos portlets, one for Cognos Navigator, Cognos Search, and Cognos Viewer, one for Cognos Extended Applications, and one for Metric List and Metric History Chart.
To install the portlet applications file, you must be logged on to WebSphere Portal with administrator privileges, and be able to access the
CognosBIPortlets_c83.war file from your file system or network file system.
If the Portal Services installation is not within your network access, you must manually move the
CognosBIPortlets_c83.war file to an accessible location. Note that he portlet applications file can be installed only once; however, it can be updated when required.
To install the portlet applications file, follow these steps:
1. At the top of the WebSphere Portal page, click the Administration tab.
2. From the menu on the left, click Portlet Management, Web Modules, and then click Install.
3. Click the Browse button, locate the folder containing the file mentioned above, and select the CognosBIPortlets_c83.war file.
4. Click Next and click Finish.
You'll see a message confirming that the portlets were successfully installed, and the file will be listed in Web Modules list, as shown in figure 1.
Figure 1. Manage Web Modules list
3 Configuring the portlet applications and enabling SSO between Cognos and WebSphere Portal
Cognos Portal Services (CPS) provides two main methods for enabling SSO with WebSphere Portal:
The method that you should use depends on the authentication sources you are using with both WebSphere Portal and Cognos.
NOTE: For further details on this and subsequent procedures in this article, refer to the white paper, “
Enabling Single-Sign-On between IBM Cognos 8 BI and IBM WebSphere Portal,” from which this material is excerpted.
Figure 2 illustrates the different scenarios and the corresponding SSO method to use.
Figure 2. Shared Secret vs. LTPA Token methods/scenarios
Alternatively, you can use the following decision tree:
If (IBM Cognos 8 authentication namespace = LDAP) and (you cannot use Shared Secret for any reason) then _
LTPA Token or
alternate method
else
If (Portal userIDs) equal to (userIDs in an IBM Cognos 8 namespace)
then _
Shared Secret.
else _
alternate method
Now let's discuss these SSO methods in detail and how you can select the proper one to use.
3.1 Shared Secret method
Shared Secret is a Cognos-specific method for handling SSO. The Cognos portlets pick up the enterprise WebSphere Portal’s User ID and sends it to the IBM Cognos 8 BI server for authentication.
For security purposes, the User ID is transmitted with an encrypted timestamp that is encoded and decoded by use of a “shared secret” string as the encryption key.
Shared Secret is the simplest form of SSO method to set up and can be used in most environments, as long as the following conditions are met:
- The Portal User ID (used to log in to WebSphere Portal) is the same as the User ID in the associated IBM Cognos 8 namespace.
- The Cognos 8 namespace used for authenticating WebSphere Portal users is of type LDAP, Series 7, Windows NT LAN Manager (NTLM), or Active Directory.
Additionally, Shared Secret can be used if Enterprise Portal and IBM Cognos 8 are sharing the same namespace, and the namespace is either Active Directory or NTLM directory.
3.1.1 Setting up the Shared Secret method
First, disable Anonymous Access to Cognos 8 components.
WebSphere Portal Services uses SSO for authentication. If anonymous logon is enabled in Cognos 8 components, Portal Services logs all users as anonymous. You must ensure that anonymous access is disabled in Cognos 8 components for SSO in Portal Services to be successful.
NOTE:
- You can test the Portal Services connections, using anonymous logon, to ensure that the portlets are working in the third-party portal.
- If Portal Services fails to authenticate a user, the user receives an error message at the third-party portal.
Now, follow these steps:
1. Start Cognos Configuration.
2. In the Explorer window, under Security, Authentication, click Cognos.
3. In the Resource Properties window, ensure that Allow anonymous access is set to False (see figure 3).
Figure 3. Allow anonymous access “False”
4. From the File menu, click Save.
5. Repeat steps 1 to 4 on all servers where you installed Cognos 8 components.
Second, enable SSO using Shared Secret.
Here are the steps to configure the required namespaces:
1. In Cognos Configuration, configure a namespace to authenticate WebSphere Portal users. For instructions, see the topic on configuring LDAP or NTLM authentication providers in the
IBM Cognos 8 Analytic Applications information center.
2. For an LDAP namespace, configure the following properties:
- For the Use external identity property, change the setting to True.
- For the External identity mapping property, set it to (uid=${environment("REMOTE_USER")})
IMPORTANT: Do not forget the parentheses around the external identity mapping value. The use of USER_PRINCIPAL is somewhat obsolete since REMOTE_USER is populated too, but it's mentioned for the sake of completeness. Other properties may be required. For more information, see the topic about configuring Cognos 8 components to use LDAP in the
IBM Cognos 8 Analytic Applications information center.
3. In Cognos Configuration, create and configure a Custom Java Provider namespace (see figure 4):
- For the Namespace ID property, specify any new ID. For example, CJProviderID. This new ID must be used in the portlet configuration settings.
- For the Java class name property, type “com.cognos.cps.auth.CPSTrustedSignon”. Note that Java class names are case sensitive.
Figure 4. Custom Java Provider namespace
4. In Cognos Configuration, under Environment > Portal Services, configure the following properties:
- For Trusted Signon Namespace ID, type the namespace ID of the LDAP or NTLM namespace that you configured in step 1.
- For Shared Secret, type the key to be used for single sign-on.
This parameter represents the authorization secret that must be shared between the Cognos portlets and the Cognos server. Consider this as a secret password. You must use the same character string when you configure the portlet application, and you must use a single word as the key. For security reasons, we recommend specifying a non-null value.
5. Under Environment, for Gateway Settings, set the
Allow namespace override property to true (see figure 5).
Figure 5. Allow namespace override “True”
6. From the File menu, click Save, and then Restart the Cognos 8 service.
3.1.2 Configuring the Cognos portlets for WebSphere Portal
To do this, follow these steps:
1. For each Cognos portlet application, click Modify Parameters.
2. For the
cps_auth_secret property (see figure 6), enter the secret character string that you used for the Shared Secret property when you configured the Custom Java Provider namespace.
3. For the
cps_auth_namespace property, enter the Custom Java Provider namespace ID.
Figure 6. Modify parameters
4. For the
Cognos 8 WSRP WSDL Location property, enter the URL path to access Portal Services components
through the gateway. The format of the URL is as follows:
For Cognos content portlets:
Gateway_URI/wsrp/cps4/portlets/nav?wsdl&b_action=cps.wsdl
Example for a servlet gateway:
http://172.0.16.1:9500/wsrp/cps4/portlets/nav?wsdl&b_action=cps.wsdl
For Cognos Extended applications:
Gateway_URI/wsrp/cps4/portlets/sdk?wsdl&b_action=cps.wsdl
Example for a servlet gateway:
http://172.0.16.1:9500/wsrp/cps4/portlets/sdk?wsdl&b_action=cps.wsdl
For Metrics Manager Watchlist portlets:
Gateway_URI/wsrp/cps4/portlets/cmm?wsdl&b_action=cps.wsdl
Example for a servlet gateway:
http://172.0.16.1:9500/wsrp/cps4/portlets/cmm?wsdl&b_action=cps.wsdl
3.2 LTPA Token method
LTPA token is an SSO method implemented by IBM WebSphere Application Server. 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 only by the security layer of WebSphere Application server, so it’s an IBM-world technique only.
Although the WebSphere portal executes only in the context of WebSphere Application Server, IBM Cognos 8 BI server can execute in alternate application servers.
If IBM Cognos 8 is also deployed in WebSphere
Application Server, then the only step necessary is to put the IBM Cognos 8 Dispatcher under WebSphere Application Server security, to leverage the identity passed in the LTPA token from the WebSphere Portal server.
However, by default, IBM Cognos 8 runs using Tomcat Application Server. Since Tomcat, like any other non-IBM application server, does not support LTPA token, an additional link is needed. In these cases—in which IBM Cognos 8 is deployed in some other application server than WebSphere—a dedicated IBM Cognos 8 Servlet Gateway for exclusive use by the Cognos Portlets must be deployed in WebSphere and protected by WebSphere security.
This protected Gateway in WebSphere will then be able to pick up the LTPA token and relay the identity contained in it to IBM Cognos 8’s Content Manager in some other variable/header that can be consumed by an IBM Cognos 8 Namespace directly.
3.2.1 Setting up the LTPA Token
Using LTPA token as the main SSO mechanism between WebSphere Portal and the 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 WebSphere Application Server.
For LTPA Token to work properly, the following conditions must be met:
- An IBM Cognos 8 Servlet Gateway must be installed as a secured application in WebSphere Application Server.
- IBM Cognos 8 and the WebSphere portal must both access the same LDAP server for authentication.
- A WebSphere LTPA Domain must have been set up by the WebSphere administrator and both WebSphere instances (the one running WebSphere Portal Server and the one running IBM Cognos 8 Gateway/Dispatcher) are part of that same domain.
First, set “Allow Namespace Override”.
On every installed instance in your system running the Gateway component, adjust the configuration as follow:
1. In IBM Cognos 8 Configuration, go to Local Configuration > Environment.
2. Under the Gateway settings find “Allow namespace override” and set it to True, as shown in figure 7. This allows for specifying the namespace to target for SSO in the Portlets rather than in the configuration of the Gateway, thus enabling dual use of a Gateway.
Figure 7. Allow namespace override “True”
3. Save this configuration and restart.
Secure the Gateway entry point.
To use LTPA token, you need to secure the Gateway with WebSphere security. This requires administration privileges in the WebSphere Application server. To do this:
1. On the alternate gateway, build a WAR or EAR file to deploy into WebSphere Application Server (as described in the
IBM Cognos 8 Analytic Applications information center).
2. Deploy the alternate gateway onto the WebSphere Web Application server enabling SSO between IBM Cognos 8 BI and IBM WebSphere Portal Cognos Proprietary Information.
3. In the WebSphere Administration console, secure access to the gateway application via LTPA token. Configure it to access the same LDAP directory as the portal. Consult your WebSphere Application Server administration manuals for further details.
For more detailed instructions, refer to “Deploy a secured IBM Cognos 8 MR1 Servlet Gateway in WAS6.doc” on the
IBM WebSphere Application Server, version 6.0 information center.
3.2.2 Configure the Cognos Portlet Applications in WebSphere Portal
To do this:
1. Log in to WebSphere Portal as an administrator.
2. Go to Administration > Portlet Management > Applications, and locate the three Cognos portlet applications:
- Cognos BI Content Portlets
- Cognos Extended Applications Portlets
- Cognos Metric Manager Portlets
3. For each Cognos application, set the following fields (see figure 8):
Cognos 8 WSRP WSDL Location:
cps_auth_namespace: (i.e. MyLDAP.)
Active Credential Type: LtpaToken
Figure 8. Set parameter values
IMPORTANT: The connection server is to contain the URI to access the WSDL location via a gateway. The format of the URL is as follows:
For Cognos Content portlets:
Gateway_URI/wsrp/cps4/portlets/nav?wsdl&b_action=cps.wsdl
Example for a servlet gateway:
http://172.0.16.1:9500/wsrp/cps4/portlets/nav?wsdl&b_action=cps.wsdl
For Cognos Extended applications:
Gateway_URI/wsrp/cps4/portlets/sdk?wsdl&b_action=cps.wsdl
Example for a servlet gateway:
http://172.0.16.1:9500/wsrp/cps4/portlets/sdk?wsdl&b_action=cps.wsdl
For Metrics Manager Watchlist portlets:
Gateway_URI/wsrp/cps4/portlets/cmm?wsdl&b_action=cps.wsdl
Example for a servlet gateway:
http://172.0.16.1:9500/wsrp/cps4/portlets/cmm?wsdl&b_action=cps.wsdl
In this case, the Gateway must be a Servlet Gateway running inside 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.
3.2.3 Configure the LDAP namespace in Cognos 8
All requests sent by the Cognos Portlets to the “Cognos 8 WSRP WSDL Location” will carry the LTPA Token. When receiving those requests aimed at a resource protected by WebSphere Application Server security, Application Server first authenticates the user implicitly, sending the requests through the portal based on the identity contained in the LTPA token.
Authentication is done against the User Registry configured for WebSphere Application Server, that is, an LDAP. Once authentication is successful, WebSphere Application Server will populate USER_PRINCIPAL and REMOTE_USER with the User ID of the authenticated user.
Both these variables can be consumed by an LDAP namespace via the $environment{} macro and are hence valid for SSO. IBM Cognos 8 will look up the users in the LDAP again and, if found, authenticate the user for IBM Cognos 8.
For the IBM Cognos 8 LDAP namespace to map user IDs correctly, external user mapping needs to be enabled.
To configure the required Namespaces:
1. Open IBM Cognos 8 Configuration and locate your LDAP namespace.
2. Configure the following properties:
- For the Use external identity property, change the setting to True.
- For the External identity mapping property, set it to (uid=${environment("REMOTE_USER")})
NOTE: Do not forget the parentheses around the external identity mapping value. Using USER_PRINCIPAL is somewhat obsolete since REMOTE_USER is populated too, but it's mentioned for the sake of completeness.
3. Save the Configuration and restart IBM Cognos 8 for the changes to take effect.
3.3 Alternate 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, and Oblix.
It's also possible that none of the methods described here apply to your current environment. In such cases, contact the Cognos Portals Product Manager or the Best Practices Team for help.
4 Configuring the portlet cache
Portal Services caches HTML markup fragments that are used to quickly regenerate recent views of portlet pages. These markup fragments are compressed and stored in the user’s session object.
You can configure the number of pages stored for each user’s portlet. The size of the markup fragment for each page depends on the complexity of the portlet, but they are typically about 5KB. By default, the cache stores ten pages for each user’s portlet.
To configure the cache:
1. On the Administration tab, click Portlet Management > Web Modules.
2. Select the portlet applications file
CognosBIPortlets_c83.war.
3. In the portlet applications list, select the application you want.
4. For the portlet you want to set the cache size, click the Configure Portlet button.
5. For the
Maximum Cached Pages property, enter the maximum number of pages you want to cache; click OK.
6. Repeat steps 4 and 5 for each portlet.
5 Customizing/testing the content of Cognos portlets
As an administrator, you can define the default content and appearance of portlets. When you customize a portlet instance using the Configure button, the settings become the default for all users who view this instance.
If the portlet is not locked for editing, users can customize the content for their instance of the portlet. Users retain their custom settings, even if you reset the portlet. Users inherit the settings you configure only when they view the instance you configured, or when they reset the portlet using the Reset button in the edit page of the portlet.
Applications that appear in the Cognos Extended Applications portlet may include editable application parameters with default values defined by the developer. To change the parameter values that users see as defaults, you must edit the
applications.xml file. For information about modifying application parameters, see the
IBM Cognos 8 Analytic Applications information center.
The configurable properties for the Cognos portlets vary. For more information, see the
IBM Cognos 8 Analytic Applications information center, User Reference Help for Portal Services section.
To configure the portlets:
1. Go to the page where you added the Cognos portlets.
2. Click the Configure button for the portlet that you want to configure.
3. Edit the settings as desired; these become the default settings for user instances of this portlet.
4. Click OK.
5.1 Testing the Cognos portlets
To test the Cognos portlets:
1. Place the Cognos portlets on a page and grant access permissions for these portlets to the WebSphere Portal users that will be using Cognos.
2. Log on to WebSphere Portal with a User ID that is common to both WebSphere and Cognos.
3. View the page; notice that the Cognos portlets are showing up with IBM Cognos 8 content.
6 Troubleshooting
Problem: Prompt page appears when viewing Cognos content page on WebSphere Portal server even though SSO is applied.
When you log in to the WebSphere Portal server and select your page that includes Cognos contents, you may be prompted to select a namespace to authenticate with (see figure 9). This is especially likely if you have more than just one namespace configured in IBM Cognos 8 that is used to authenticate to Cognos 8.
Obviously, this is not feasible for SSO scenarios as those require authentication to one specific namespace only, as we configured it above in this document.
Figure 9. Prompt to authenticate namespace
Solution: Usually this occurs when using the Windows Internet Explorer browser. To fix the problem:
1. From IE, select Tools > Internet Options.
2. Select the Privacy Tab.
3. Click the Advanced button under the Settings section.
4. In the Advanced Privacy Settings dialog, check the “Override automatic cookie handling” option under the Cookies section.
5. Compare the options in figure 10 with your settings.
6. Click OK twice.
Figure 10. Advanced Privacy Settings dialog
7 Resources
- developerWorks Information Management white paper, “Enabling Single Sign-On between IBM Cognos 8 BI and IBM WebSphere Portal”:
http://www.ibm.com/developerworks/data/library/cognos/page37.html
- IBM Cognos 8 v4 Business Intelligence information center:
http://publib.boulder.ibm.com/infocenter/c8bi/v8r4m0/index.jsp?topic=/com.ibm.swg.im.cognos.c8bi.ug_cra.doc/ug_cra_id980ReportNetAdministration.html
- Cognos Business Intelligence and Financial Performance Management product page:
http://www-01.ibm.com/software/data/cognos/
About the author
Ahmed Farouk is an IT Specialist at the Cairo Technology Development Center in Egypt. He has been involved in the development of WebSphere Business Modeler and WebSphere Publisher Server for four years and recently expanded his focus to include the Information Management Profiles, especially the BI domain. You can reach Ahmed at
afarouk@eg.ibm.com.