...

Enabling Single-Sign-On on WebSphere Portal in IBM Cognos ReportNet

by user

on
Category: Documents
15

views

Report

Comments

Transcript

Enabling Single-Sign-On on WebSphere Portal in IBM Cognos ReportNet
Guideline
Enabling Single-Sign-On on
WebSphere Portal in IBM Cognos
ReportNet
Product(s): IBM Cognos ReportNet
Area of Interest: Security
Enabling Single-Sign-On on WebSphere Portal in IBM Cognos ReportNet
2
Copyright
Copyright © 2008 Cognos ULC (formerly Cognos Incorporated). 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. 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
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 Cognos. Cognos
and the Cognos logo are trademarks of Cognos ULC (formerly 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 Cognos products can be found at www.cognos.com
This document is maintained by the Best Practices, Product and Technology team. You
can send comments, suggestions, and additions to [email protected] .
Cognos Proprietary Information
Enabling Single-Sign-On on WebSphere Portal in IBM Cognos ReportNet
3
Abstract
This document provides step-by-step instructions on how to enable Single Signon
(SSO) with Cognos Portal Services (CPS) in IBM WebSphere Portal 5.1. Although this
document was written specifically for configuring SSO between WebSphere Portal 5.1
and IBM Cognos ReportNet 1.1 MR1+, some of the same principles apply to previous
versions of both WebSphere and IBM Cognos. As a prerequisite, it is assumed that the
reader has successfully imported the Cognos portlets. Refer to the document on
“Installing Cognos Portlets In WebSphere Portal” for more information on how to import
the Cognos portlets.
Contents
1
Determining the Proper SSO Method ......................................................................4
1.1
1.2
1.3
Shared Secret ...................................................................................................................................5
LTPA Token......................................................................................................................................5
Alternate Methods.............................................................................................................................6
2
Gateway considerations ...........................................................................................6
3
Installing a dedicated Gateway ................................................................................6
4
Setting up Shared Secret..........................................................................................7
5
Setting up LTPA Token...........................................................................................10
Appendix A – Installing a Dedicated Gateway.............................................................14
Appendix B – Enable External Identity Mapping for LDAP Namespace....................17
Appendix C – Enabling Identity Mapping for AD Namespaces ..................................17
Appendix D – The Connection Server URI ...................................................................19
Cognos Proprietary Information
Enabling Single-Sign-On on WebSphere Portal in IBM Cognos ReportNet
4
1 Determining the Proper SSO Method
Cognos Portal Services (CPS) provides two main methods for enabling SSO with IBM
WebSphere Portal: Shared Secret 1or LTPA Token. The method to use depends on the
authentication sources you are using with both WebSphere and IBM Cognos. The
following diagram depicts different scenarios and the proper SSO method to use:
WebSphere
Portal
Cognos
WebSphere
Portal
Cognos
Shared
Secret
Any Authentication Source (LDAP,
NTLM, or Active Directory)
WebSphere
Portal
Both authentication sources must have
matching UIDs (can have different pwds)
Cognos
LTPA
Token
LDAP Authentication Source
Alternatively, the following decision tree can be used:
If (ReportNet 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 a ReportNet namespace)
then Shared Secret.
else alternate method
1
The Shared Secret is available in CRN 1.1 MR1 or later. It’s not available in CRN 1.1 RTM
Cognos Proprietary Information
Enabling Single-Sign-On on WebSphere Portal in IBM Cognos ReportNet
5
1.1 Shared Secret
“Shared Secret” is a Cognos-specific method for handling SSO. The Cognos Portlets pick
up the enterprise portal’s User ID and sends it to the IBM Cognos ReportNet 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 the WebSphere portal) are the same as
those User IDs in the associated ReportNet 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 IBM Cognos
Series 7 Access Manager.)
• The IBM Cognos ReportNet 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 ReportNet are sharing the same namespace and the namespace is either
Active Directory or NTLM directory.
On the IBM Cognos ReportNet end, an additional second namespace (a Trusted Signon
Provider) is used to retrieve the encrypted information and pass it on to a full
namespace like LDAP, AD, NTLM or IBM Cognos Series7 which then does the actual
authentication.
1.2 LTPA Token
LTPA token is an SSO method implemented by the 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 only executes in the context of the IBM
WebSphere Application Server, IBM Cognos ReportNet server can execute in alternate
application servers.
If IBM Cognos ReportNet too is deployed in WebSphere then the only necessary step is
to put the ReportNet Dispatcher under WebSphere security to leverage the identity
passed in the LTPA token from the WebSphere Portal Server.
However by default, IBM Cognos ReportNet 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 there cases, where IBM Cognos ReportNet is deployed in
some other application server than WebSphere a dedicated IBM Cognos ReportNet
Servlet Gateway for exclusive use by the Cognos Portlets needs to be deployed in
WebSphere and protected by WebSphere security.
This protected Gateway in the WebSphere will then be able to pick up the LTPA token
and relay the identity contained in it to IBM Cognos ReportNet’s Content Manager in
some other variable/header which can be consumed by an IBM Cognos ReportNet
Namespace directly.
Cognos Proprietary Information
Enabling Single-Sign-On on WebSphere Portal in IBM Cognos ReportNet
6
1.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, Oblix, etc. It is 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.
2 Gateway considerations
Whenever there’s more than just one namespace configured in Cognos Configuration
upon authenticating to IBM Cognos ReportNet for the first time the user is prompted to
select a namespace to authenticate with. While this is reasonable for an interactive user
it’s not feasible for SSO scenarios as those require authentication to one specific
namespace only.
To resolve this ambiguity the easiest way is to go through a gateway which allows for
specifying a default namespace to use for authentication. For SSO with external 3rd party
portals this means to install an additional dedicated gateway just to handle the Portlet
requests to be able to force the authentication to a specific namespace. So while
interactive users would use Gateway1 which would either prompt or have a default
namespace set CPS requests are routed to a second gateway which specifies a different
namespace to use for SSO.
3 Installing a dedicated Gateway
The first step before enabling SSO is to install a dedicated IBM Cognos ReportNet
gateway to process all requests coming from Cognos portlets. This is mandatory only in
mixed use environments where you have users connecting to IBM Cognos ReportNet
directly as well as users coming through a portal. The second Gateway will allow for
having both existing next to each other.
If your use case involves portal only then one Gateway is all you need. You may have to
adjust configuration or switch the type of gateway depending on your setup though.
Whenever we refer to a dedicated gateway in the following just relate this to your
gateway.
Installing a dedicated gateway is very simple. Simply follow the steps as described in
Appendix A – Installing a Dedicated Gateway.
On Windows with IIS, we suggest setting up a CGI gateway for simplicity. However, the
ISAPI DLL is fully supported and may provide better performance. On UNIX or LINUX go
with a Apache2 Mod for good performance or CGI for simplicity.
If you are planning to use LTPA token as the SSO method, it is necessary to install a
IBM Cognos ReportNet Servlet Gateway and deploy that securely into WebSphere
Application server.
For more detailed instructions refer to “Deploy a secured IBM Cognos 8 MR1 Servlet
Gateway in WAS6.doc” on the ProvenPractice Website. Although written for IBM Cognos
8 the same steps apply, just use a IBM Cognos ReportNet Gateway.
Cognos Proprietary Information
Enabling Single-Sign-On on WebSphere Portal in IBM Cognos ReportNet
7
4 Setting up Shared Secret
Step 1 – Install and Configure an Alternate Gateway
An alternate gateway is mandatory when using Shared Secret.
1. Install the alternate gateway and configure your web server. (Refer to Appendix
A or the Cognos Installation Guide for more information on installing an alternate
gateway.)
2. Start Cognos Configuration for the alternate gateway
3. In the Environment section, set the following fields:
Internal Dispatcher = <address of your main Cognos Dispatcher>
External Dispatcher = <same dispatcher address as above>
Gateway namespace=CPSTrusted
4. Save and close Cognos Configuration.
Step 2 – Configure the Trusted Signon Namespace
On every installed instance of IBM Cognos ReportNet in your system which runs
Content Manager component open Cognos Configuration and adjust configuration
using the following steps.
1. Under Security/Authentication, add a new namespace with any name (for
example “SharedSecret”) of type Custom Java Provider.
Name = SharedSecret
Type = Custom Java Provider
Cognos Proprietary Information
Enabling Single-Sign-On on WebSphere Portal in IBM Cognos ReportNet
8
2. For the namespace properties, enter the following:
Namespace ID
= CPSTrusted
Java class name = com.cognos.cps.auth.CPSTrustedSignon
(Note: The values for id and class name are case sensitive and must be entered
as is whenever referred to)
3. Under Security > Authentication > Cognos, set “use anonymous access” to false.
4. Save the configuration and restart IBM Cognos ReportNet.
Step 3 – Configure CPS properties
On every installed instance in your system running the Dispatcher component adjust
CPS properties by following the steps outlined here.
1. Open
<install dir>/webapps/p2pd/WEB-INF/classes/cps_trustedsignon.properties
for editing in a texteditor and change the following values.
Cognos Proprietary Information
Enabling Single-Sign-On on WebSphere Portal in IBM Cognos ReportNet
9
namespace_id= <ID of your authentication namespace>
auth_cookie_name= cps_auth_user
cps_auth_secret= <The shared secret string>
•
•
Where:
<ID of your authentication namespace> is the ID of the namespace
associated with the IBM Cognos ReportNet namespace used to authenticate
users. It can be of type LDAP, IBM Cognos Series 7, NTLM or Active Directory.
Note: This is not the “CPSTrusted” namespace set above but the “target”
namespace which does the final authentication to IBM Cognos ReportNet.
<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 Cognos Portlets in WebSphere portal.
Note:
If your “target” namespace is of type LDAP, enable External User mapping. See
Appendix B – Enable External Identity Mapping for LDAP Namespace
for details.
If your “target” namespace is of type AD, enable Identity Mapping. See
Appendix C – Enabling Identity Mapping for AD Namespaces for details.
Step 4 – Configure the 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
Cognos portlet applications:
• Cognos BI Content Portlets
• Cognos Extended Applications Portlets
• Cognos Metric Manager Portlets
3. For each IBM Cognos application, set the following fields:
CPS Endpoint
cps_auth_secret
Active Credential Type
<connection server URI>
<The shared secret string>
(none)
Important: The connection server is to contain the URI to access the WSDL location
via a gateway. See Appendix D – The Connection Server URI to help determine
the proper value based on your Gateway type and the Portlet type.
Cognos Proprietary Information
Enabling Single-Sign-On on WebSphere Portal in IBM Cognos ReportNet
10
The Authorization secret must be the same as the one set in “Step 3” above. When
using Shared secret, it is a good idea to leave Active Credential Type as “(none)”.
Step 5 – 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 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 Cognos portlets actually show up.
5 Setting up LTPA Token
Using LTPA token as the main single signon mechanism between WebSphere Portal and
the Cognos portlets involves the user having administrator access rights to the
WebSphere Application Server running the IBM Cognos ReportNet server. If the IBM
Cognos ReportNet server does run in a WebSphere Application Server environment, you
must at least install the IBM Cognos ReportNet Servlet Gateway onto a WebSphere
Application Server.
For LTPA Token to work properly, the following conditions must be met:
• An IBM Cognos ReportNet Servlet Gateway must be installed as a secured
application in a WebSphere Application Server
• IBM Cognos ReportNet 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 WPS and the one
running IBM Cognos ReportNet Gateway/Dispatcher) are part of that same
domain.
Cognos Proprietary Information
Enabling Single-Sign-On on WebSphere Portal in IBM Cognos ReportNet
11
Step 1 – Deploy and Secure the Servlet Gateway as a WebSphere Application
An alternate gateway is mandatory when setting up SSO with LTPA token.
This step requires administration privileges in the WebSphere Application server.
1. Do a new Gateway component only install. Either install to the same server as
your other Gateway into some other directory or to another server.
2. On the alternate gateway, build a WAR or EAR file to deploy into the WebSphere
Application Server (as described in the IBM Cognos ReportNet Administration &
Security Guide).
3. Deploy the alternate gateway onto the WebSphere Web Application Server
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 ProvenPractice Website. Although written
for IBM Cognos 8 the same steps apply, just use a IBM Cognos ReportNet
Gateway.
4. Start Cognos Configuration for that alternate gateway.
5. In the Environment section, set the following fields:
Internal Dispatcher = <address of your main IBM Cognos ReportNet Dispatcher>
External Dispatcher = <same dispatcher address as above>
Gateway namespace=<your authentication namespace>
Where <your authentication namespace> is the ID of the namespace associated
with the Directory server to be used for looking up users accessing the IBM Cognos
ReportNet server via the portlets. This namespace can be of type LDAP, NTLM or IBM
Cognos Series 7.
6. Save and close Cognos Configuration.
7. Restart the Servlet Gateway application by restarting the WebSphere it has been
deployed in to.
Step 3 – Configure the Cognos Portlet Applications in WebSphere Portal
1. Login to WebSphere Portal as an administrator.
Cognos Proprietary Information
Enabling Single-Sign-On on WebSphere Portal in IBM Cognos ReportNet
12
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 IBM Cognos application, set the following fields:
CPS Endpoint
<connection server URI>
Active Credential Type
LtpaToken
Important: The connection server is to contain the URI to access the WSDL location
via a gateway. See Appendix D – The Connection Server URI to help determine
the proper value based on your setup and the Portlet type.
In this case, the Gateway has to be 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 or Active Directory namespace in ReportNet
Cognos Proprietary Information
Enabling Single-Sign-On on WebSphere Portal in IBM Cognos ReportNet
13
All request sent by the Cognos Portlets to the “CPS Endpoint” will carry the LTPA Token.
When receiving those requests aimed at a resource protected by Application Server
security, the 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 the Application Server,
i.e. an LDAP. Once authentication is successful the Application Server will populate
USER_PRINCIPAL and REMOTE_USER with the User ID of the authenticated user. Both
of those variables can be consumed by an LDAP namespace via the $environment{}
macro and are hence valid for SSO. IBM Cognos ReportNet will look up the users in the
LDAP again and if found authenticate the user for IBM Cognos ReportNet.
For the IBM Cognos ReportNet LDAP namespace to map user IDs correctly, external
user mapping needs to be enabled. See Appendix B – Enable External Identity
Mapping for LDAP Namespace for more details. For AD namespaces, see Appendix
C – Enabling Identity Mapping for AD Namespaces.
Cognos Proprietary Information
Enabling Single-Sign-On on WebSphere Portal in IBM Cognos ReportNet
14
Appendix A – Installing a Dedicated Gateway
This section provides a high-level overview of installing a dedicated gateway. Please
refer to the IBM Cognos Install & Configuration Guide for more details about dedicated
and alternate Gateways.
Installing a Gateway
1. Run the IBM Cognos ReportNet installation CD.
2. Select a server or folder for the new gateway. The gateway can be on the same
machine as the main IBM Cognos installation, but it is mandatory that you install this
dedicated gateway to a separate folder than the main IBM Cognos ReportNet
installation. (i.e. a new folder like “cpsgateway” will suffice).
Configuring a Gateway
The first step is to determine the type of Gateway required. There are four types of
gateways: CGI, ISAPI, MOD(2), and Servlet. The type of gateway to use depends on
your environment and preference. When SSO is performed by an application server,
such as in certain cases of SAP User Mapping and WebSphere LTPA token, a servlet
gateway must be installed. For brevity, the rest of this section will describe how to
setup a CGI gateway on IIS. This is the simplest gateway to configure, but the same
general principles apply to all other types of gateways. Please refer to the IBM Cognos
Installation & Configuration Guide for more information on how to configure these
other types of gateways.
Regardless of the type of Gateway used, it is important to run the instance of Cognos
Configuration used for this dedicated gateway. In Cognos Configuration, configure the
following fields:
Dispatcher URI for gateway = <same dispatcher URI as for your main IBM Cognos
ReportNet server>
Controller URI for gateway = <same controller URI as for your main IBM Cognos
ReportNet server>
Gateway Namespace = <ID of the target authentication namespace for portal
users>
The gateway namespace value should be the ID (and not the name) of the target
namespace.
If you are using the “Shared Secret” SSO method, then the gateway namespace needs
to be the ID of the Custom Java Provider or “Shared Secret” namespace.
Configure the Web Server
Cognos Proprietary Information
Enabling Single-Sign-On on WebSphere Portal in IBM Cognos ReportNet
15
This step does not apply when setting up a servlet gateway. The Web Server must be
configured to have three virtual directories to access the content of the dedicated
gateway, similar to the main gateway.
In IIS:
Step 1 – Create the Appropriate Virtual Directories:
1. Create a new virtual directory called “cpsgateway” and map this directory to
the <install dir>/webcontent folder.
2. Under cpsgateway virtual directory, create another virtual folder called cgibin. Map this folder to the <install dir>/cgi-bin folder. Make sure that this
virtual directory has Execute Permissions for Scripts and Executables.
3. Under cpsgateway virtual directory, create another virtual folder called help
and map this directory to the <install dir>/webcontent/documentation folder.
Step 2 – Set the appropriate directory security access on the cpsgateway
directory.
1. In IIS, right-click on cpsgateway and select Properties. Click on the Directory
Security tab and select “edit” under the “Anonymous access and authentication
control” heading.
2. The directory security depends on the type of SSO method used:
• For Shared Secret or SAP Logon Ticket, select “anonymous access”.
• For Basic Authentication with SAP User Mapping, select “Basic
authentication“. Click on “edit” and assign a compatible domain that contains
the namespace for the ReportNet Enterprise Portal users. In IIS, this can
only be set to NTLM or Active Directory namespace.
Cognos Proprietary Information
Enabling Single-Sign-On on WebSphere Portal in IBM Cognos ReportNet
16
Cognos Proprietary Information
Enabling Single-Sign-On on WebSphere Portal in IBM Cognos ReportNet
17
Appendix B – Enable External Identity Mapping for LDAP Namespace
Enabling External Identity Mapping is required if IBM Cognos ReportNet is using an
LDAP namespace. This is a namespace of type LDAP and not Series 7.
On every installed instance of IBM Cognos ReportNet in your system which runs Content
Manager component open Cognos Configuration and adjust configuration using the
following steps.
1. Open Cognos Configuration and locate your LDAP namespace.
2. Enable External Identity mapping by setting the following fields:
Use external identity
True
mapping
External identity mapping (uid=${environment("REMOTE_USER")})
or
(uid=${environment("USER_PRINCIPAL")})
Important: Do not forget the parentheses around the external identity mapping value.
Using USER_PRINCIPAL is kind of obsolete since REMOTE_USER is populated too but is
mentioned for the sake of completeness.
3. Save the Configuration and restart IBM Cognos ReportNet for these changes to
take effect.
Appendix C – Enabling Identity Mapping for AD Namespaces2
Enabling Identity Mapping is required if IBM Cognos ReportNet is using an AD
namespace. This is a namespace of type AD and not IBM Cognos Series 7 or LDAP.
2
Enabling Identity Mapping is available as of CRN 1.1.MR2 only
Cognos Proprietary Information
Enabling Single-Sign-On on WebSphere Portal in IBM Cognos ReportNet
18
On every installed instance of IBM Cognos ReportNet in your system which runs Content
Manager component open Cognos Configuration and adjust configuration using the
following steps.
1. Open Cognos Configuration and locate your AD namespace.
2. Under “Advanced Properties”, click edit.
Cognos Proprietary Information
Enabling Single-Sign-On on WebSphere Portal in IBM Cognos ReportNet
19
3. Type in “singleSignonOption” for the name and “IdentityMapping” for value.
4. Save the Configuration and restart IBM Cognos ReportNet for these changes to
take effect.
Appendix D – The Connection Server URI
The “Connection Server URI” is the server connection between the Enterprise Portal and
IBM Cognos ReportNet. This is the value to be set for each Cognos Portlet or iView in
the Portlet properties. The connection URI will differs depending on the type of
Gateway and the type of Portlet
Gateway Type
Connection Server URI
Example URI
CGI Gateway
http://<server:port>/<alias>/cgibin/cognos.cgi/cps2/nav
http://myserver/crngw2/cgibin/cognos.cgi/cps2/nav
MOD Gateway
http://<server:port>/<alias>/cgibin/mod_cognos.dll/cps2/nav
http://<server:port>/<alias>/cgibin/mod2_cognos.dll/cps2/nav
http://<server:port>/<alias>/cgibin/cognosisapi.dll/cps2/nav
http://<server:port>/<contextroot>/
cps2/nav
http://myserver/crngw2/cgibin/mod_cognos.dll/cps2/nav
http://myserver/crngw2/cgibin/mod2_cognos.dll/cps2/nav
http://myserver/crngw2/cgibin/cognosisapi.dll/cps2/nav
http://myserver:9080/ServletGat
eway/cp2/nav
MOD2 Gateway
ISAPI Gateway
Servlet Gateway
Cognos Proprietary Information
Enabling Single-Sign-On on WebSphere Portal in IBM Cognos ReportNet
20
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
End Point
Example
Cognos Navigator
/nav?
http://myserver/crngw2/cgi-bin/cognos.cgi/cps2/nav
/cmm?
http://myserver/crngw2/cgibin/cognos.cgi/cps2/cmm
http://myserver/crngw2/cgi-bin/cognos.cgi/cps2/sdk
Cognos Search
Cognos Viewer
Metric Manager
Watchlist
Cognos Extended
Applications
/sdk?
Appendix E – SSL enabled Connection Server URI
In some rare cases the Connection Server URI may be running HTTPS rather than HTTP, so the
Webserver hosting the Gateway is SSL enabled. Often only externally exposed Webservers get
SSL secured. It’s a bad practice to use an externally exposed Gateway for Portal SSO rather
than a dedicated internal one, which can be secured by firewalls against intrusion and fraud.
Though in some cases even internal Gateways get SSl enabled.
The Cognos Portlets can communicate with SSL enabled Connection Sevrer URIs and this is fully
supported. The reason why is simple, the Portlet doesn’t care if the Connection Server URI is
running HTTP or HTTPS. The transport layer is to be provided by the Portal Server, not by the
Portlet code.
This being said, it evolves, that establishing the necessary trust between the Portal Server and
the Webserver hosting the IBM Cognos Gateway is to be established within the Portal Server
and not in IBM Cognos Software. Hence this is a non-Cognos task and is not covered by IBM
Cognos Support, rather it’s a task for the Portal Server Administrator.
Cognos Proprietary Information
Enabling Single-Sign-On on WebSphere Portal in IBM Cognos ReportNet
21
The way this works is, that whenever the Portlets send a request to the Connection Server URI
the Portal Server will try to establish a connection to that URI. Since in the HTTPS case the
Websever will first initiate an SSL handshake by presenting its server certificate, the Portal
Server needs to be configured such that it “trusts” that certificate and hence can successfully
complete the SSL handshake.
For this to work, the CA which signed the Webserver certificate (self-signed certificates are a
bad practice and are hence discouraged, so there has to be a CA which signed this), needs to
be trusted. Since a Portal Server is just an application running inside an Application Server, this
falls back to the JRE used by the Application Server.
Each JRE has some truststore, a Java Keystore which contains a set of CA certificates which are
trusted by the JRE. For JREs provided by SUN this truststore is a file called “cacerts” which is
located in <JRE>/lib/security/ folder. We need to add the CA certificate which signed the
Webserver certificate to this keystore.
Any SUN JRE incorporates the keytool command line utility to manage keystores. The easiest
way to do this for WebSphere Portal however, is to use the “ikeyman” tool coming with
WebSphere Portal. This is a java based GUI allowing to manage keystores. You’ll find examples
for using both tools below.
Once the certificate has been added to the JRE’s truststore, restart the Portal Server and edit
the WSRP location (Connection Server URI) property of the Cognos Portlets to reflect the https
protocol. Save the changed properties and view the Portlets. Et voilá.
Use IKeyman to add the CA certificate to the WPS JRE truststore
•
•
Acquire a base64 ASCII encoded version of the CA certificate which signed the
Webservers certificate, either PEM or DER format is fine.
Start the IKeyman tool by executing <WPS_HOME>/AppServer/bin/ikeyman.bat
Cognos Proprietary Information
Enabling Single-Sign-On on WebSphere Portal in IBM Cognos ReportNet
22
•
Select open a keystore
Cognos Proprietary Information
Enabling Single-Sign-On on WebSphere Portal in IBM Cognos ReportNet
23
•
Find cacerts at <WPS_HOME>/AppServer/java/jre/lib/security by clicking “Browse” in
the file open dialog. Change the “Files of Type” filter to see it listed.
Click “Open”
•
Ensure “Key database type” is “JKS” and click “OK”
Cognos Proprietary Information
Enabling Single-Sign-On on WebSphere Portal in IBM Cognos ReportNet
24
•
You will get prompted for a password, by default this is “changeit” (without quotes)
Enter this and click OK.
•
You will now see a list of all the CA certificates the JRE trusts out of the box. If your
Webserver certificate was signed by one of the commercial entities in this list you’re
most probably done. If it doesn’t work then just import your CA anyway.
Click “Add”
Cognos Proprietary Information
Enabling Single-Sign-On on WebSphere Portal in IBM Cognos ReportNet
25
•
Find your CA certificate by browsing for it. The type depends on whether you got a PEM
(base64-encoded ASCII) or DER (binary DER) file. Click OK
•
The tool will prompt you for an alias name to assign to this certificate. Just choose any
but using the name of your company or the CA itself is a good practice like “Cognos CA”
or “MyCA”. Click OK.
•
You’ll now find your Certificate being listed. Done.
You can close the tool, no additional save needed.
Cognos Proprietary Information
Enabling Single-Sign-On on WebSphere Portal in IBM Cognos ReportNet
26
Use keytool add the CA certificate to the WPS JRE truststore
•
•
•
Acquire a base64 ASCII encoded version of the CA certificate which signed the
Webservers certificate, either PEM or DER format is fine. (So are PKCS#12 chains).
Open a shell/command window and change to
<WPS_HOME>/AppServer/java/jre/bin
Issue the following command (all on one line)
keytool –import –alias <AnAliasName> -file <absolute_path_to_cert>
-keystore ../lib/security/cacerts –storepass changeit
•
This will have added the certificate with the given alias. To check issue
keytool –list –keystore ../lib/security/cacaerts –storepass chageit
this will list all certificates with their alias and other information inside the keystore.
For reference to keytool see
http://java.sun.com/j2se/1.4.2/docs/tooldocs/windows/keytool.html
Cognos Proprietary Information
Fly UP