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 andenable single sign-on (SSO) with IBM® Cognos® Portal Services (CPS) in IBMWebSphere® Portal 6.1.

Table of Contents

1 Introduction.......................................................................................................................22 Installing the Portlet Applications file..............................................................................23 Configuring the portlet applications and enabling SSO between Cognos and WebSpherePortal....................................................................................................................................33.1 Shared Secret method ................................................................................................ 4 3.2 LTPA Token method ................................................................................................. 8 3.3 Alternate methods ................................................................................................... 12

4 Configuring the portlet cache..........................................................................................135 Customizing/testing the content of Cognos portlets.......................................................135.1 Testing the Cognos portlets ..................................................................................... 14

6 Troubleshooting..............................................................................................................147 Resources........................................................................................................................15About the author................................................................................................................15

1 Introduction

Before you can add IBM Cognos portlets to their IBM WebSphere Portal pages, you mustdeploy the Cognos portlets to the WebSphere Portal server. The types of IBM Cognosportlets 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 ExtendedApplications portlet.

Metric Studio portlets. This group includes the Metric List and Metric History Chartportlets.

The deployment process consists of the following five tasks, which we discuss in thisarticle:

1. Installing the portlet applications file.2. Configuring the portlet applications and enabling Single-Sign-On between Cognosand 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 portletapplications 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 forMetric List and Metric History Chart.

To install the portlet applications file, you must be logged on to WebSphere Portal withadministrator privileges, and be able to access the CognosBIPortlets_c83.war file fromyour file system or network file system.

If the Portal Services installation is not within your network access, you must manuallymove the CognosBIPortlets_c83.war file to an accessible location. Note that he portletapplications 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 thenclick 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 filewill be listed in Web Modules list, as shown in figure 1.

Figure 1. Manage Web Modules list

3 Configuring the portlet applications and enabling SSObetween Cognos and WebSphere Portal

Cognos Portal Services (CPS) provides two main methods for enabling SSO withWebSphere Portal:

• Shared Secret• LTPA Token

The method that you should use depends on the authentication sources you are using withboth WebSphere Portal and Cognos.

NOTE: For further details on this and subsequent procedures in this article, refer to thewhite 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 SharedSecret for any reason) then _ LTPA Token or alternate method

elseIf (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 touse.

3.1 Shared Secret methodShared Secret is a Cognos-specific method for handling SSO. The Cognos portlets pickup the enterprise WebSphere Portal’s User ID and sends it to the IBM Cognos 8 BI serverfor authentication.

For security purposes, the User ID is transmitted with an encrypted timestamp that isencoded 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 mostenvironments, 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 inthe associated IBM Cognos 8 namespace.

• The Cognos 8 namespace used for authenticating WebSphere Portal users is of typeLDAP, Series 7, Windows NT LAN Manager (NTLM), or Active Directory.

Additionally, Shared Secret can be used if Enterprise Portal and IBM Cognos 8 aresharing the same namespace, and the namespace is either Active Directory or NTLMdirectory.

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 enabledin Cognos 8 components, Portal Services logs all users as anonymous. You must ensurethat anonymous access is disabled in Cognos 8 components for SSO in Portal Services tobe successful.

NOTE:

• You can test the Portal Services connections, using anonymous logon, to ensure thatthe portlets are working in the third-party portal.

• If Portal Services fails to authenticate a user, the user receives an error message at thethird-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 toFalse (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 Portalusers. For instructions, see the topic on configuring LDAP or NTLM authenticationproviders 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 mappingvalue. The use of USER_PRINCIPAL is somewhat obsolete since REMOTE_USER ispopulated too, but it's mentioned for the sake of completeness. Other properties maybe required. For more information, see the topic about configuring Cognos 8components 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 thefollowing properties:

• For Trusted Signon Namespace ID, type the namespace ID of the LDAP orNTLM 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 theCognos portlets and the Cognos server. Consider this as a secret password. Youmust use the same character string when you configure the portlet application, andyou must use a single word as the key. For security reasons, we recommendspecifying 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 PortalTo 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 thatyou used for the Shared Secret property when you configured the Custom JavaProvider namespace.

3. For the cps_auth_namespace property, enter the Custom Java Provider namespaceID.

Figure 6. Modify parameters

4. For the Cognos 8 WSRP WSDL Location property, enter the URL path to accessPortal 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. Bypassing a token across servers, the host applications can share the user’s identity and trustthat it has been validated and properly secured.

The LTPA token is processed only by the security layer of WebSphere Applicationserver, so it’s an IBM-world technique only.

Although the WebSphere portal executes only in the context of WebSphere ApplicationServer, 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 stepnecessary is to put the IBM Cognos 8 Dispatcher under WebSphere Application Serversecurity, to leverage the identity passed in the LTPA token from the WebSphere Portalserver.

However, by default, IBM Cognos 8 runs using Tomcat Application Server. SinceTomcat, like any other non-IBM application server, does not support LTPA token, anadditional link is needed. In these cases—in which IBM Cognos 8 is deployed in someother application server than WebSphere—a dedicated IBM Cognos 8 Servlet Gatewayfor exclusive use by the Cognos Portlets must be deployed in WebSphere and protectedby WebSphere security.

This protected Gateway in WebSphere will then be able to pick up the LTPA token andrelay the identity contained in it to IBM Cognos 8’s Content Manager in some othervariable/header that can be consumed by an IBM Cognos 8 Namespace directly.

3.2.1 Setting up the LTPA TokenUsing LTPA token as the main SSO mechanism between WebSphere Portal and theCognos portlets involves the user having administrator access rights to the WebSphereApplication 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 ApplicationServer.

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 inWebSphere Application Server.

• IBM Cognos 8 and the WebSphere portal must both access the same LDAP server forauthentication.

• A WebSphere LTPA Domain must have been set up by the WebSphere administratorand both WebSphere instances (the one running WebSphere Portal Server and the onerunning 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 theconfiguration 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, asshown in figure 7. This allows for specifying the namespace to target for SSO in thePortlets rather than in the configuration of the Gateway, thus enabling dual use of aGateway.

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. Thisrequires administration privileges in the WebSphere Application server. To do this:

1. On the alternate gateway, build a WAR or EAR file to deploy into WebSphereApplication Server (as described in the IBM Cognos 8 Analytic Applications information center).

2. Deploy the alternate gateway onto the WebSphere Web Application server enablingSSO between IBM Cognos 8 BI and IBM WebSphere Portal Cognos ProprietaryInformation.

3. In the WebSphere Administration console, secure access to the gateway application viaLTPA token. Configure it to access the same LDAP directory as the portal. Consultyour WebSphere Application Server administration manuals for further details.

For more detailed instructions, refer to “Deploy a secured IBM Cognos 8 MR1 ServletGateway in WAS6.doc” on the IBM WebSphere Application Server, version 6.0 information center.

3.2.2 Configure the Cognos Portlet Applications in WebSphere PortalTo do this:

1. Log in to WebSphere Portal as an administrator.

2. Go to Administration > Portlet Management > Applications, and locate the threeCognos 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: <connection server URI> cps_auth_namespace: <The authentication namespace ID> (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 locationvia 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 WebSphereApplication Server. The Active Credential Type is the key to enabling the sending of theLTPA token back to the Alternate Gateway. Make sure the spelling for LtpaToken isexact.

3.2.3 Configure the LDAP namespace in Cognos 8All requests sent by the Cognos Portlets to the “Cognos 8 WSRP WSDL Location” willcarry the LTPA Token. When receiving those requests aimed at a resource protected byWebSphere Application Server security, Application Server first authenticates the userimplicitly, sending the requests through the portal based on the identity contained in theLTPA token.

Authentication is done against the User Registry configured for WebSphere ApplicationServer, that is, an LDAP. Once authentication is successful, WebSphere ApplicationServer will populate USER_PRINCIPAL and REMOTE_USER with the User ID of theauthenticated 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 LDAPagain and, if found, authenticate the user for IBM Cognos 8.

For the IBM Cognos 8 LDAP namespace to map user IDs correctly, external usermapping 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 populatedtoo, 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 ispossible that an alternate SSO mechanism is required when using dedicated SSOapplications like Netegrity SiteMinder, and Oblix.

It's also possible that none of the methods described here apply to your currentenvironment. In such cases, contact the Cognos Portals Product Manager or the BestPractices Team for help.

4 Configuring the portlet cachePortal Services caches HTML markup fragments that are used to quickly regeneraterecent views of portlet pages. These markup fragments are compressed and stored in theuser’s session object.

You can configure the number of pages stored for each user’s portlet. The size of themarkup fragment for each page depends on the complexity of the portlet, but they aretypically 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 pagesyou 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. Whenyou customize a portlet instance using the Configure button, the settings become thedefault for all users who view this instance.

If the portlet is not locked for editing, users can customize the content for their instanceof the portlet. Users retain their custom settings, even if you reset the portlet. Usersinherit the settings you configure only when they view the instance you configured, orwhen 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 includeeditable application parameters with default values defined by the developer. To changethe 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 AnalyticApplications 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 PortalServices 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 ofthis 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 portletsto the WebSphere Portal users that will be using Cognos.

2. Log on to WebSphere Portal with a User ID that is common to both WebSphereand Cognos.

3. View the page; notice that the Cognos portlets are showing up with IBM Cognos 8content.

6 Troubleshooting

Problem: Prompt page appears when viewing Cognos content page on WebSphere Portalserver even though SSO is applied.

When you log in to the WebSphere Portal server and select your page that includesCognos 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 namespaceconfigured 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 onespecific 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 fixthe 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 cookiehandling” 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-Onbetween 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 andWebSphere Publisher Server for four years and recently expanded his focus to include theInformation Management Profiles, especially the BI domain. You can reach Ahmed at afarouk@eg.ibm.com.