...

Enabling SSO between IBM Cognos 8 BI and Plumtree Portal Guideline

by user

on
Category: Documents
3

views

Report

Comments

Transcript

Enabling SSO between IBM Cognos 8 BI and Plumtree Portal Guideline
Guideline
Enabling SSO between IBM Cognos 8
BI and Plumtree Portal
Product(s): IBM Cognos 8 BI
Area of Interest: Security
Enabling SSO between IBM Cognos 8 BI and Plumtree Portal
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 SSO between IBM Cognos 8 BI and Plumtree Portal
3
Abstract
This document provides step-by-step instructions on how to enable Single Signon (SSO)
with IBM Cognos Portal Services (CPS) in Plumtree Corporate Portal 5.0. Although this
document was written specifically for configuring SSO between Plumtree Portal and IBM
Cognos 8 MR1, many of the same principles apply to previous versions of both Plumtree
and IBM Cognos.
Contents
1
Determining the Proper SSO Method...................................................................... 4
Shared Secret ................................................................................................................................................4
1.1
HTTP Basic .......................................................................................................................................5
1.2
Alternate methods.............................................................................................................................5
2
Gateway considerations .......................................................................................... 5
3
Setting up Shared Secret ......................................................................................... 6
4
Setting up HTTP Basic ........................................................................................... 11
Appendix A – Enable External Identity Mapping for LDAP Namespace ................... 16
Appendix B – Enabling Identity Mapping for AD Namespaces.................................. 16
Appendix C – The Connection Server URI................................................................... 18
Cognos Proprietary Information
Enabling SSO between IBM Cognos 8 BI and Plumtree Portal
4
1 Determining the Proper SSO Method
IBM Cognos Portal Services (CPS) provides two commonly used methods for enabling SSO
with Plumtree portal: Shared Secret or HTTP Basic. The method to use depends on the
authentication sources you are using with both Plumtree and Cognos. The following
diagram depicts different scenarios and the proper SSO method to use:
“Shared Secret” or “HTTP Basic”
Plumtree
Portal
Cognos
Any Authentication Source (LDAP,
NTLM, or Active Directory)
Plumtree
Portal
Cognos
Both authentication sources must
have matching UIDs (can have
different pwds)
Alternatively, the following decision tree can be used:
If (cannot use Shared Secret for any reason)
then HTTP Basic
else
If (Portal userIDs) equal to (userIDs in a Cognos8 namespace)
then Shared Secret.
else alternate method
Shared Secret
“Shared Secret” is an 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:
Cognos Proprietary Information
Enabling SSO between IBM Cognos 8 BI and Plumtree Portal
5
The Portal User ID (used to log into the Plumtree 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 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.
On the IBM Cognos 8 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 Series7 which then does the actual authentication.
•
1.1 HTTP Basic
HTTP Basic is a native Plumtree SSO method. The method is quite simple and can work
with IBM Cognos 8 portlets. Most of the same requirements for HTTP Basic are the same
as those for Shared Secret, namely:
• The Plumtree Portal User IDs are the same as those User IDs associated with the
IBM Cognos 8 namespace. If the IBM Cognos namespace is a IBM Cognos Series 7
namespace, the User IDs must be the same or the portal User IDs must be mapped
to the user entries using 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.
A security drawback of HTTP Basic is that user IDs and passwords are sent from Plumtree
Portal to the IBM Cognos 8 server in plain text – meaning that the user’s credentials are
not encrypted when transmitted. To combat this drawback, an HTTPS secure connection
can be established between the two servers.
1.2 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
IBM 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 8 BI 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.
Cognos Proprietary Information
Enabling SSO between IBM Cognos 8 BI and Plumtree Portal
6
To resolve this ambiguity the easiest way is to go through a gateway which allows to
specify a default namespace to use for authentication. For SSO with external 3rd party
portals this usually meant to install an additional gateway 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 were routed to a
second gateway which specified a different namespace to use for SSO.
As of IBM Cognos 8 MR1 it’s no longer mandatory to facilitate a dedicated Gateway for
exclusive use by CPS to achieve this. There is a new property which can be configured for
the Portlets and a new setting in the Gateway configuration exposed in Cognos
Configuration which allow for using just one shared Gateway or no Gateway at all for
routing the Portlets’ requests. Actually though technically possible to go without a Gateway
at all it’s considered mandatory and in-line with product documentation to use at least one
Gateway. So all the requests from Portlets have to go through a Gateway as of now.
The properties are
• cps_auth_namespace – Portlet property
If this property is set to a valid namespace ID in a Portlet’s configuration inside the
Portal Server it will pass this Namespace ID with any request sent by the Portlets. It
can override a default namespace defined in a Gateway’s configuration if “Allow
Namespace override” is set to true (see next)
• Allow Namespace override – Cognos Configuration
If this new Gateway setting is set to “true” it allows for cps_auth_namespace to
override any default namespace possibly set at the Gateway.
So now one can choose to either set up a separate gateway and specify the default
namespace there or override by cps_auth_namespace property or just sent CPS
requests to Dispatcher directly in conjunction with the cps_auth_namespace setting.
If you use a version of IBM Cognos 8 prior to MR1 you don’t have a choice anyway and
have to set up a dedicated Gateway to resolve the ambiguity in any case.
3 Setting up Shared Secret
Step 1 – Configure the Trusted Signon Namespace
On every installed instance of IBM Cognos 8 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 SSO between IBM Cognos 8 BI and Plumtree Portal
7
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 Environment, open the Portal Services section.
Cognos Proprietary Information
Enabling SSO between IBM Cognos 8 BI and Plumtree Portal
8
Set the following fields:
Trusted Signon NamespaceID
Shared Secret
•
•
= <ID of your authentication namespace>
= <The shared secret string>
Where:
<ID of your authentication namespace> is the ID of the namespace
associated with the IBM Cognos 8 Namespace used to authenticate 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) but the
“target” namespace which does the final authentication to IBM Cognos 8.
<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.
Note:
If your “target” namespace is of type LDAP, enable External User mapping. See
Appendix A – Enable External Identity Mapping for LDAP Namespace for
details.
If your “target” namespace is of type AD, enable Identity Mapping. See Appendix
B – Enabling Identity Mapping for AD Namespaces for details.
4. Under Security > Authentication > Cognos, set “use anonymous access” to false.
5. Save the configuration and restart IBM Cognos 8.
Cognos Proprietary Information
Enabling SSO between IBM Cognos 8 BI and Plumtree Portal
9
Step 2 – Set “Allow Namespace Override”
On every installed instance in your system running the Gateway component adjust
configuration by following the steps outlined here.
1. In Cognos Configuration, go to Local Configuration > Environment.
2. Under the Gateway settings find “Allow Namespace Override”, set this to “true”, as
shown below. This allows for specifying the namespace to target for SSO in the
Portlets rather than in the configuration of the Gateway and hence enables dual use
of a Gateway.
3. Save this configuration and restart.
Step 3 – Configure the IBM Cognos Remote Gadget Server
The IBM Cognos remote gadget server for Plumtree needs to be configured to contain
the “shared secret” string.
On every installed instance in your system running the Gateway component adjust
configuration by following the steps outlined here.
1. Open
<install_dir>/cps/plumtree/webapps/gadgets/WEB-INF/classes/cpspt.properties
for editing in a textedior
Cognos Proprietary Information
Enabling SSO between IBM Cognos 8 BI and Plumtree Portal
10
2. Within this file is a parameter called “cps_auth_namespace=” to include the CPS
Trusted namespace, as such cps_auth_namespace=CPSTrusted. (This is the ID of
the namespace that we configured in the previous section.)
3. Within this file is a parameter called “cps_auth_secret”. Add the Shared Secret
string value from Step 2 into this file, as such: cps_auth_secret=secret. (This is the
string that we configured in the previous section.)
4. Rebuild the gadget server war file should by executing the build batch file from the
following location:
5. <install dir>\cps\plumtree\build.bat (in Windows)
6. <install dir>\cps\plumtree\build.sh (in UNIX or Linux)
7. The cps-pt.war file will be updated in the following directory <install
dir>\cps\plumtree\gadgets\cps-pt.war.
8. Deploy this war file.
• In Tomcat, you simply need to copy the war file into an active /webapps
folder. If you are using the Tomcat with the default installation, simply copy
cps-pt.war into the <install dir>/webapps folder. If there is a folder
named cps-pt within this directory, delete it. Within a few minutes, Tomcat
will automatically expand the war file and start the gadget server.
• With other Application Servers, follow the normal steps as described in your
app server administration guide to deploy the cps-pt.war file.
Step 4 – Configure the Cognos Portlets in Plumtree portal
1. Login to Plumtree as an administrator
2. Go into Administration and locate the IBM Cognos 8 Remote server.
3. Bring up the Remote Server’s properties and make sure that the Base
Authentication Type is set to None.
Cognos Proprietary Information
Enabling SSO between IBM Cognos 8 BI and Plumtree Portal
11
4 Setting up HTTP Basic
Using Plumtree’s HTTP Basic authentication method is also fairly simple to configure. It is
important to note that this option will not work if the users log in to Plumtree without
typing a password, such as using SSO to get into the portal, using “Remember Me”, or
“Remember My Password”. In these instances, the password is not available to the portal.
With HTTP Basic, the User ID and password are sent to the IBM Cognos 8 BI server as part
of every Cognos portlet request in the form of a standard HTTP Basic Authentication
header. IBM Cognos 8 BI does not directly support HTTP Basic authentication, but most
Web Servers and Application Server do. Security on this gateway must be configured in
the administration console of the Web Server and be associated with the virtual directories
that are setup to access that alternate gateway. For simplicity, only an example using
Microsoft IIS will be used, but the same configuration steps can be configured on any other
Web Server.
Cognos Proprietary Information
Enabling SSO between IBM Cognos 8 BI and Plumtree Portal
12
Step 1 – Set “Allow Namespace Override”
On every installed instance in your system running the Gateway component adjust
configuration by following the steps outlined here.
1. In Cognos Configuration, go to Local Configuration > Environment.
2. Under the Gateway settings find “Allow Namespace Override”, set this to “true”, as
shown below. This allows for specifying the namespace to target for SSO in the
Portlets rather than in the configuration of the Gateway and hence enables dual use
of a Gateway.
3. Save this configuration and restart.
Open the cpspt.properties file (<install_dir>/cps/plumtree/webapps/gadgets/WEBINF/classes/cpspt.properties). Modify the parameter “cps_auth_namespace=” to include
the CPS Trusted namespace, as such cps_auth_namespace=CPSTrusted.
Step 2 – Configure the Cognos Remote Gadget Server
The Cognos remote gadget server for Plumtree needs to be configured to use the
proper namespace.
Cognos Proprietary Information
Enabling SSO between IBM Cognos 8 BI and Plumtree Portal
13
On every installed instance in your system running the Gateway component adjust
configuration by following the steps outlined here.
1. Open
<install_dir>/cps/plumtree/webapps/gadgets/WEB-INF/classes/cpspt.properties
for editing in a textedior
2. Within this file is a parameter called “cps_auth_namespace=” to include the CPS
Trusted namespace, as such cps_auth_namespace=CPSTrusted. (This is the ID of
the namespace that we configured in the previous section.)
3. Rebuild the gadget server war file should by executing the build batch file from the
following location:
4. <install dir>\cps\plumtree\build.bat (in Windows)
5. <install dir>\cps\plumtree\build.sh (in UNIX or Linux)
6. The cps-pt.war file will be updated in the following directory <install
dir>\cps\plumtree\gadgets\cps-pt.war.
7. Deploy this war file.
• In Tomcat, you simply need to copy the war file into an active /webapps
folder. If you are using the Tomcat with the default installation, simply copy
cps-pt.war into the <install dir>/webapps folder. If there is a folder
named cps-pt within this directory, delete it. Within a few minutes, Tomcat
will automatically expand the war file and start the gadget server.
• With other Application Servers, follow the normal steps as described in your
app server administration guide to deploy the cps-pt.war file.
Step 3 – Configure the Web Server or Application Server to Accept HTTP Basic
Authentication
This step depends entirely on the combination of Web server, Web application server
(WAS) and Authentication directory server used and can be very different depending on
the customer environment. Since the IBM Cognos 8 BI server does not process HTTP Basic
Authentication tokens, the authentication needs to be performed by either the Web Server
(Apache, IIS, IBM HTTP Server, etc.) or the WAS (WebSphere, Bea, Tomcat, NetWeaver,
etc.) via a secured servlet gateway. By convention, upon authentication, the Web
server (or WAS) generates the REMOTE_USER HTTP variable for the User ID which gets
“trusted” by IBM Cognos 8 Access Manager and looked up into the associated namespace.
The Web server or WAS must be able to use the same Directory Server as the IBM Cognos
system. With Windows and IIS, HTTP basic is simple to setup, but can only be used to
authenticate against an integrated Windows authentication scheme like Active Directory or
NTLM. LDAP and Series 7 directories are not supported by IIS. If you must authenticate
against LDAP, setup a secured gateway in the Web application server.
Web Server
Cognos Proprietary Information
Enabling SSO between IBM Cognos 8 BI and Plumtree Portal
14
All popular web servers support HTTP Basic. HTTP Basic authentication should be enabled
on the Alternate gateway. The virtual directories should be enabled for HTTP Basic
authentication and a CGI, ISAPI or NSAPI gateway should be used. To configure HTTP
Basic authentication in IIS:
1. Open the IIS administration console
2. Select the virtual directory associated with the alternate gateway
3. Right-click and select Properties.
4. Under Directory Security, set up basic authentication and specify the proper
domain. The domain should also be setup as a namespace in your IBM Cognos 8
BI server (the namespace used for mapping portal User IDs in IBM Cognos 8).
Any access to this virtual directory will require a valid HTTP Basic authentication token. If
the user does not have a valid HTTP authentication token, the user will be prompted to
enter their credentials. The IBM Cognos portlets will not prompt the user for their
credentials, if authentication fails. Instead, an error message will be returned.
Step 4 – Configure the Cognos Portlets in Plumtree
1. Login to Plumtree as an administrator.
2. Go into Administration and locate the Cognos 8 Remote server.
3. Bring up the Remote Server’s properties and make sure that the Base
Authentication Type is set to User’s Basic Authentication Information.
Cognos Proprietary Information
Enabling SSO between IBM Cognos 8 BI and Plumtree Portal
15
4. Consult the Plumtree Administration guide about any other necessary changes to
Plumtree’s config.xml file to enable HTTP Basic authentication.
Cognos Proprietary Information
Enabling SSO between IBM Cognos 8 BI and Plumtree Portal
16
Appendix A – Enable External Identity Mapping for LDAP Namespace
Enabling External Identity Mapping is required if IBM Cognos 8 is using an LDAP
namespace. This is a namespace of type LDAP and not IBM Cognos Series 7.
On every installed instance of IBM Cognos 8 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:
True
Use external identity
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 8 for these changes to take effect.
Appendix B – Enabling Identity Mapping for AD Namespaces
Enabling Identity Mapping is required if IBM Cognos 8 is using an AD namespace. This is a
namespace of type AD and not Series 7 or LDAP.
On every installed instance of IBM Cognos 8 in your system which runs Content Manager
component open Cognos Configuration and adjust configuration using the following steps.
Cognos Proprietary Information
Enabling SSO between IBM Cognos 8 BI and Plumtree Portal
17
1. Open Cognos Configuration and locate your AD namespace.
2. Under “Advanced Properties”, click edit.
3. Type in “singleSignonOption” for the name and “IdentityMapping” for value.
Cognos Proprietary Information
Enabling SSO between IBM Cognos 8 BI and Plumtree Portal
18
4. Save the Configuration and restart IBM Cognos 8 for these changes to take effect.
Appendix C – The Connection Server URI
The “Connection Server URI” is the server connection between the Enterprise Portal and
IBM Cognos 8. 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/wsrp/cps4/portlets/nav
?wsdl&b_action=cps.wsdl
http://myserver/c8gw2/cgibin/cognos.cgi/wsrp/cps4/portlets/n
av?wsdl&b_action=cps.wsdl
MOD Gateway
http://<server:port>/<alias>/cgibin/mod_cognos.dll/wsrp/cps4/portlet
s/nav?wsdl&b_action=cps.wsdl
http://<server:port>/<alias>/cgibin/mod2_cognos.dll/wsrp/cps4/portl
ets/nav?wsdl&b_action=cps.wsdl
http://<server:port>/<alias>/cgibin/cognosisapi.dll/wsrp/cps4/portlets
/nav?wsdl&b_action=cps.wsdl
http://<server:port>/<contextroot>/s
ervlet/Gateway/wsrp/cps4/portlets/na
v?wsdl&b_action=cps.wsdl
http://myserver/c8gw2/cgibin/mod_cognos.dll/wsrp/cps4/portl
ets/nav?wsdl&b_action=cps.wsdl
http://myserver/c8gw2/cgibin/mod2_cognos.dll/wsrp/cps4/por
tlets/nav?wsdl&b_action=cps.wsdl
http://myserver/c8gw2/cgibin/cognosisapi.dll/wsrp/cps4/portle
ts/nav?wsdl&b_action=cps.wsdl
http://myserver:9080/ServletGatew
ay/servlet/Gateway/wsrp/cps4/portl
ets/nav?wsdl&b_action=cps.wsdl
MOD2 Gateway
ISAPI Gateway
Servlet Gateway
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/c8gw2/cgibin/cognos.cgi/wsrp/cps4/portlets/nav?wsdl&b_actio
n=cps.wsdl
/cmm?
http://myserver/c8gw2/cgibin/cognos.cgi/wsrp/cps4/portlets/cmm?wsdl&b_acti
on=cps.wsdl
http://myserver/c8gw2/cgibin/cognos.cgi/wsrp/cps4/portlets/sdk?wsdl&b_actio
n=cps.wsdl
Cognos Search
Cognos Viewer
Metric Manager
Watchlist
Cognos Extended
Applications
/sdk?
Cognos Proprietary Information
Enabling SSO between IBM Cognos 8 BI and Plumtree Portal
19
Cognos Proprietary Information
Fly UP