Tip or Technique

Deploying a secured IBM Cognos 8 Servlet Gateway in IBM WebSphere 6

Product(s): IBM Cognos 8 BI, IBM WebSphere Area of Interest: Security, Infrastructure

Deploying a secured IBM Cognos 8 Servlet Gateway in IBM WebSphere 6 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 cscogpp@ca.ibm.com .

Cognos Proprietary Information

Deploying a secured IBM Cognos 8 Servlet Gateway in IBM WebSphere 6 3 Contents

1 1.1 1.2 1.3 2 2.1 2.2 2.3 2.4 3 3.1 3.2 3.3 3.4 3.5 INTRODUCTION ............................................................................................ 4 PURPOSE ............................................................................................................4 APPLICABILITY .....................................................................................................4 EXCLUSIONS AND EXCEPTIONS ..................................................................................4 PREFACE AND BACKGROUND ....................................................................... 5 SERVLET GATEWAY USE CASES ................................................................................5 WHY NOT SECURING P2PD ......................................................................................6 SSO BETWEEN APPLICATION SERVER SECURITY AND COGNOS 8 ...........................................7 SSO BETWEEN A 3RD PARTY PORTAL AND COGNOS 8 ........................................................7 DEPLOY A SECURED SERVLET GATEWAY...................................................... 9 PREPARE THE BUILD PROCESS ...................................................................................9 BUILD THE APPLICATION FILE .................................................................................. 12 DEPLOY THE SERVLET GATEWAY .............................................................................. 14 RETSTART WEBSPHERE......................................................................................... 19 TEST THE SERVLET GATEWAY ................................................................................. 21

APPENDIX A - ENABLE WAS SECURITY.................................................................. 22 APPENDIX B SECURE A SERVLET GATEWAY EAR FILE USING AST ..................... 29

Cognos Proprietary Information

Deploying a secured IBM Cognos 8 Servlet Gateway in IBM WebSphere 6 4

1 Introduction
1.1 Purpose This document describes the necessary steps to deploy an IBM Cognos 8 Servlet Gateway (SGW) to IBM WebSphere application server and secure it by WebSphere security. This is desirable whenever the goal is to achieve single signon between WebSphere security and IBM Cognos 8 directly or - more common for single signon between IBM WebSphere Portal and IBM Cognos 8. Applicability While for creation of this document IBM Cognos 8 BI MR2 and IBM WebSphere 6.0.2 were used the technique described in here applies to all versions of IBM Cognos 8. IBM WebSphere version 5.1 looks a bit different but basically the same steps apply as well. While other application servers may handle things different, the modifications to files shown here apply for any application server to which is deployed to. The operating system on which this is done does not impact the technique presented here.

1.2

1.3

Exclusions and Exceptions We will not touch on details about how to setup IBM WebSphere or parallel instances of WebSphere server. For information about setting this up refer to IBM WebSphere documentation. Further on, mind that it is impossible to deploy a Servlet Gateway into the same WebSphere server instance as IBM Cognos 8 BI or IBM Cognos ReportNet. Because of classloader collisions both cant coexist so a Servlet Gateway (SGW) must be deployed in a separate WebSphere server instance! We assume that the WebSphere instance being deployed to is security enabled (global security is enabled and a user registry is set up). Appendix A provides some quick guide on how to enable WebSphere security.

Cognos Proprietary Information

Deploying a secured IBM Cognos 8 Servlet Gateway in IBM WebSphere 6 5

2 Preface and background

This section will give some background on whats done and why to deploy a Servlet Gateway in a secured manner. The impatient may skip to Caution: you cannot deploy the SGW into the same server instance as p2pd application. You will experience classloader issues which are a result of IBM Cognos 8 not being completely J2EE compliant. This is not an issue but by design. To deploy a Servlet Gateway it is mandatory to use a server instance where no p2pd application is deployed. The rundown of steps is 1. Prepare the build process First the Servlet Gateway web application, an EAR or WAR file, needs to be build. There are some preparations to take to build the application file in the right fashion. 2. Build the actual application file 3. deploy the application file to WebSphere In the following sections bullet-point style instructions on the steps are provided Prepare the build process 2.1 Servlet Gateway use cases The Servlet Gateway is less commonly used compared to CGI or the web server specific implementations like ISAPI or MOD/MOD2. However its needed sometimes in more complex scenarios to achieve single sign-on (SSO). This is because this gateway implementation is a Servlet, like the p2pd application which constitutes IBM Cognos 8 contains two Servlets (Content Manager and Dispatcher) and thus needs to be deployed to a java application server like IBM WebSphere, BEA Weblogic or others. Since every application server offers its own security system the Servlets can be put under the umbrella of this application server security so that users trying to access these Servlets need to authenticate with the application server before their requests get served. In SSO scenarios IBM Cognos 8 will then leverage the authentication information available at the application server level which is passed to IBM Cognos 8s security and thus SSO can take place. Typical use cases for this can be classified in two categories SSO between application server security and IBM Cognos 8 SSO between a 3rd party portal and IBM Cognos 8

Cognos Proprietary Information

Deploying a secured IBM Cognos 8 Servlet Gateway in IBM WebSphere 6 6 2.2 Why not securing P2PD The skilled reader will pose the question on why not secure the p2pd application directly then since it consists of Servlets as well. Based on experience of many deployments heres an explanation on why using a Servlet Gateway is considered to be best practice in those cases. IBM Cognos 8 architecture knows three tiers: Gateway, application server tier components and Content Manager. Technically the Gateway could be seen as just a proxy interface to the logical construct of the BiBus on which all components sit. However, the Gateway offers many added values and is functionally most complete when it comes to handling SSO scenarios, authentication handshakes in general and serving static webcontent. In addition its performance is better compared to a multipurpose dispatcher which could take over as a logical Gateway. This is true in particular when using web servers where a mod/mod2 gateway delivers superior performance. So a Gateway is a good thing to use at all. When it comes to SSO scenarios including application servers though, the Servlet Gateway is the only Gateway which is feasible. Opposed to hitting the Dispatcher directly, which is never the less valid and supported, the SGW can be separated to a different instance of an application server and hence separate the load for serving portal navigation and static content from the main application server. This is similar to classic three tier architectures including a web server for this purpose. There are some rare scenarios, where a routing dispatcher, an application server tier + gateway install which solely runs the dispatcher service might look like valid alternative. This refers to setups which facilitate application server plug-ins which route requests to dispatchers directly. But still the argument about the load applies. The decision about either using a Servlet Gateway or a routing Dispatcher is to be discussed in detail and depends on many factors which are specific to the setup. As of IBM Cognos 8 MR2 there are fewer issues being discovered about SSO with Gateways than with Dispatcher in general. To sum it up, securing p2pd application itself by application server security is a valid option but bear in mind that you use a dispatcher as a Gateway and hence add the load for static content like Portal navigation and other stuff to the dispatching load. In addition, securing p2pd is slightly more complicated and can cause issues in multi node systems and for SDK access if screwed up. Generally speaking, using a Gateway is considered a best practice as it is the component designed for this purpose and hence is functionally most complete and robust.

Cognos Proprietary Information

Deploying a secured IBM Cognos 8 Servlet Gateway in IBM WebSphere 6 7 2.3 SSO between application server security and IBM Cognos 8 BI While this scenario is less frequent it may appear in enterprise deployments where the company policies involve security being established at the application server level. The principal technique used is similar for all application servers independent of its vendor. Once a user is authenticated by the application server security his identity, in java terms the principal, is put into some java specific environment variable called USER_PRINCIPAL. Code running in the same security domain can retrieve the users identity from there. So for the Servlet Gateway this means that the gateway code can actually find out about the user whos communicating with it. It then passes down this identity by proprietary means to Content Manager which hence can leverage USER_PRINCIPAL in LDAP Namespaces directly or through the trusted signon provider (TSP) for USER_PRINCIPAL (class com.cognos.cps.bseries.auth.CPSTrustedSignon_up) which still is provided with IBM Cognos 8 BI. This provider consumes USER_PRINCIPAL and transfers its content into REMOTE_USER which can be consumed by IBM Cognos 8 Namespaces like LDAP,Active Directory and IBM Cognos Series7. Its common though for application servers, that they populate REMOTE_USER automatically as well as USER_PRINCIPAL so the need for the USER_PRINCIPAL approach is diminished and as a best practice approach configuration should rely on REMOTE_USER instead as it requires no extra TSP and hence only one Namespace being configured.

2.4

SSO between a 3rd party portal and IBM Cognos 8 BI For SSO scenarios with portal servers Servlet Gateways can offer a bridge between portal security, which is integrated with application server security most of the time, and IBM Cognos 8. So a users identity is passed from the portal to an application sever where a Servlet Gateway can be deployed to fetch it for use with IBM Cognos 8. By putting the Servlet Gateway under the application server security again the users identity is provided in USER_PRINCIPAL or/and REMOTE_USER. The Servlet Gateway will either read USER_PRINCIPAL or pass REMOTE_USER depending on configuration and thus proxy the user to IBM Cognos 8.

Cognos Proprietary Information

Deploying a secured IBM Cognos 8 Servlet Gateway in IBM WebSphere 6 8 The most common appliance for this scenario is in the WebSphere world, where the WebSphere Portal security is closely interweaved with WebSphere security. WebSphere offers a proprietary security token which can be used to pass identities from one WebSphere server to another called LTPA token and thus enables SSO between multiple WebSphere servers. IBM Cognos 8 cannot leverage LTPA tokens directly since theres no way to decrypt those tokens without a proper API provided by IBM which is not part of Cognos 8. Following the approach above however, its still possible to leverage LTPA tokens indirectly by grabbing the users identity on an IBM WebSphere application server through the use of a Servlet Gateway, regardless of which WebSphere instance actually did the authentication.

Cognos Proprietary Information

Deploying a secured IBM Cognos 8 Servlet Gateway in IBM WebSphere 6 9

3 Deploy a secured Servlet Gateway

Caution: you cannot deploy the SGW into the same server instance as p2pd application. You will experience classloader issues which are a result of IBM Cognos 8 not being completely J2EE compliant. This is not an issue but by design. To deploy a Servlet Gateway it is mandatory to use a server instance where no p2pd application is deployed. The rundown of steps is 4. Prepare the build process First the Servlet Gateway web application, an EAR or WAR file, needs to be build. There are some preparations to take to build the application file in the right fashion. 5. Build the actual application file 6. deploy the application file to WebSphere In the following sections bullet-point style instructions on the steps are provided 3.1 Prepare the build process Go to C8_INSTALL/war/gateway directory and open a shell. (IBM Cognos 8 MR1 release only) The batch file to build the Servlet application file has a flaw resulting in the build to fail, it still references to the java version used previously. This is fixed as of the IBM Cognos 8 MR2 release! Simply edit the build.bat/.sh to read
@echo off ..\..\bin\jre\1.3.1\bin\java -classpath "../../bin/ant.jar;../../bin/xml-apis.jar;../../bin/xercesImpl.jar" org.apache.tools.ant.Main %*

Instead of
@echo off ..\..\bin\jre\1.4.2\bin\java -classpath "../../bin/ant.jar;../../bin/xml-apis.jar;../../bin/xercesImpl.jar" org.apache.tools.ant.Main %*

Edit the build.xml file to minimize the war/ear file size by excluding some unneeded or misplaced content. This refers to the webcontent/samples directory which contains DB

Cognos Proprietary Information

Deploying a secured IBM Cognos 8 Servlet Gateway in IBM WebSphere 6 10 sample data and sample models which are just misplaced in the WAR/EAR file as they are not needed to run the gateway in any form. Further on you can exclude documentation completely (for in house testing or development boxes) or strip languages you dont need like Japanese or German and thus dramatically reduce the size of the WAR file which is about to be created and thus speed up the deployment. As of release IBM Cognos 8 MR2 there are new options provided in the Application file build wizard of Cognos Configuration which aim for the same purpose. However you can only either exclude documentation and samples completely or leave them in as a whole. So the author suggests applying the modifications described for best results. To exclude uneeded/unwanted files from the web application file add the following at line 76 inside the <fileset> element. (the blanks before the closing / are intentional !)
<war warfile="temp/war/ServletGateway.war" webxml="war/gateway/web.xml"> <fileset dir="webcontent"> <exclude name="index.html"/> <exclude name="default.html"/> <!-- exclude Samples subfolder since it doesn't belong here anyway--> <exclude name="samples/" /> <!-- minimize war/ear file size by excluding unneeded documentation and online-help languages. Just uncomment the resective line to exclude the subdirectory named there --> <!--exclude name="documentation/" /--> <exclude name="documentation/ja/" /> <exclude name="documentation/de/" /> <!--exclude name="documentation/en/" /--> <exclude name="documentation/fr/" /> </fileset>

Edit the web.xml file to include a security constraint for the Servlet. To put the Servlet under application server security a security constraint for the web resource (the URL to access the Servlet) has to be defined. The syntax is defined as part of the Servlet specification from SUN. The File web.xml contains the declaration of all the Servlets in the web application which is to be build based on it, implying a WAR file is used. If for some reason it has to be an EAR file, which would be absolutely equivalent regarding functionality, see Appendix B on how to do this. Since the EAR file requires modifications to an additional file and involves the use of a 3rd party tool the author suggests sticking with the war file. The web.xml should look like this (additions are marked red)
<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE web-app PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN" "http://java.sun.com/dtd/web-app_2_3.dtd"> <web-app> <display-name>Cognos 8 Servlet Gateway</display-name> <description>The Cognos 8 Servlet Gateway</description> <servlet> <servlet-name>ServletGateway</servlet-name>

Cognos Proprietary Information

Deploying a secured IBM Cognos 8 Servlet Gateway in IBM WebSphere 6 11

<!-- CUSTOM CLASSLOADER RELATED CONFIGURATION.DO NOT CHANGE --> <servletclass>com.cognos.pogo.isolation.ServletWrapper</servlet-class> <init-param> <param-name>servlet-class</param-name> <param-value>com.cognos.servletgateway.Gateway</param-value> </init-param> <init-param> <param-name>classLoaderName</param-name> <param-value>SGVeryOwnClassLoader</param-value> </init-param> <!-- END OF CUSTOM CLASSLOADER RELATED CONFIGURATION --> <init-param> <!-- Should the gateway encrypt passwords? --> <param-name>encryptPassword</param-name> <!-- "true" or "false" --> <param-value>true</param-value> </init-param> <init-param> <!-- The maximum number of connections in the pool --> <param-name>maxPoolSize</param-name> <!-- A non-zero positive integer --> <param-value>20</param-value> </init-param> <init-param> <!-- The number of seconds between pings to dispatcher --> <param-name>pingPeriod</param-name> <!-- A non-zero positive integer --> <param-value>180</param-value> </init-param> <init-param> <!-- The number of seconds between checking the startup file for changed dispatchers --> <param-name>fileCheckPeriod</param-name> <!-- A non-zero positive integer --> <param-value>30</param-value> </init-param> <init-param> <!-- Tell CAF that this is the gateway --> <param-name>cafintegration</param-name> <param-value>gateway</param-value> </init-param> <init-param> <!-- Should the Gateway URL decode incoming cookies? Use 'true' if you're running iPlanet or Sun ONE webserver and 'false' otherwise --> <param-name>urldecodeCookies</param-name> <!-- "true" or "false" --> <param-value>false</param-value> </init-param> <init-param> <!-- Should the status page be available via "/status" PATH_INFO? --> <param-name>enableStatusPage</param-name> <!-- "true" or "false" --> <param-value>false</param-value> </init-param> <!-- Override the dispatcher URL for debugging purposes <init-param> <param-name>dispatcherURLOverride</param-name> <paramvalue>http://localhost:9300/p2pd/servlet/dispatch</param-value> </init-param>

Cognos Proprietary Information

Deploying a secured IBM Cognos 8 Servlet Gateway in IBM WebSphere 6 12

--> <load-on-startup>1</load-on-startup> <!-- Add Security Role reference here for the Servlet to be protected --> <security-role-ref> <role-name>cps_user</role-name> <role-link>cps_user</role-link> </security-role-ref> </servlet> <servlet-mapping> <servlet-name>ServletGateway</servlet-name> <url-pattern>/servlet/Gateway/*</url-pattern> </servlet-mapping> <servlet-mapping> <servlet-name>ServletGateway</servlet-name> <url-pattern>/servlet/Gateway</url-pattern> </servlet-mapping> <session-config> <session-timeout>30</session-timeout> </session-config> <security-constraint> <web-resource-collection> <web-resource-name>C8MR1gateway</web-resource-name> <url-pattern>/servlet/Gateway/*</url-pattern> <http-method>GET</http-method> <http-method>POST</http-method> </web-resource-collection> <auth-constraint> <role-name>cps_user</role-name> </auth-constraint> </security-constraint> <login-config> <auth-method>BASIC</auth-method> <realm-name>Cognos 8 MR1 Servlet Gateway</realm-name> </login-config> <security-role> <role-name>cps_user</role-name> </security-role> </web-app>

Basically the elements given here define a role called cps_user which is granted access to the protected resource C8MR1gateway which is defined by an URL pattern /servlet/Gateway/*. The URL pattern corresponds to the pattern in the servlet-mapping element. This pattern is appended to the context root of the application. The <web-resource-name> is irrelevant, but dont mess up the role name and references to it. If absolutely needed, always adjust all the occurrences of cps_user. So effectively only users belonging to the cps_user role are granted access to the Servlet resource. Since theres most probably no group of that name defined in the application server security there will be some mapping between existing groups in the application server security and the role defined in that file. The mapping is simply defined as part of the deployment process later.

3.2

Build the application file

Cognos Proprietary Information

Deploying a secured IBM Cognos 8 Servlet Gateway in IBM WebSphere 6 13 Still in the shell at C8_INSTALL/war/Gateway call the build script and have the WAR file build. You can use Cognos Configuration to build the application file as well after you modified the build.bat/.sh file but be sure to select WAR file. If you want to use an EAR or change context root use the command line parameters specified in the build scripts comments.

Cognos Proprietary Information

Deploying a secured IBM Cognos 8 Servlet Gateway in IBM WebSphere 6 14

3.3

Deploy the Servlet Gateway In the WebSphere Admin console go to Applications -> Install new Application. Depending of the location of the EAR/WAR you build select local or remote file system and browse to the EAR/WAR file you created in Step 3.2 above. If you built a WAR file specify the context root as ServletGateway (without the quotation), otherwise leave empty.

Press Next IBM WebSphere will now read the file and check for errors. If errors occur, check the web.xml file again and make sure it has no typos. On the second screen just press Next, unless you know exactly what you do

Cognos Proprietary Information

Deploying a secured IBM Cognos 8 Servlet Gateway in IBM WebSphere 6 15

Ignore the possible security warning on the next screen (depends on IBM WebSphere configuration) by pressing continue. Now you will be presented with a 5 step wizard. You start at step 1 now. If step 4 is missing you need to go back and check the modifications of the web.xml in Step 3.1 as this obviously didnt work. - You may edit the Application Name to anything you want. - Uncheck the Create MBeans for resources option as we dont use Beans at all. - Dont uncheck Distribute application even if you run a single server install of WebSphere.

Press Next.

On Step 2 press Next unless you know exactly what you do.

Cognos Proprietary Information

Deploying a secured IBM Cognos 8 Servlet Gateway in IBM WebSphere 6 16 On Step 3 press Next unless you know exactly what you do.

Cognos Proprietary Information

Deploying a secured IBM Cognos 8 Servlet Gateway in IBM WebSphere 6 17 On Step 4, IBM WebSphere will now map the users and groups it knows to the role we defined for our application by editing the web.xml file in Step 3.1 of this guide. The role we defined was called cps_user and we need to map some IBM WebSphere roles/users to it. For simplicity the author recommends to just check the All Authenticated option here, which will grant access to the Servlet to all users which were successfully authenticated by IBM WebSphere security. Other settings are possible though, mileage may vary depending on how familiar you are with IBM WebSpheres user/role security concept. In principal simply check the box in the Select column and check the All Authenticated option and press Next.

Cognos Proprietary Information

Deploying a secured IBM Cognos 8 Servlet Gateway in IBM WebSphere 6 18 Press finish on the summary given in Step5 and wait for the deployment to finish.

You will see a progress page where messages continue to come up. As soon as the deployment is finished you should see something like this at the end of the page.

Cognos Proprietary Information

Deploying a secured IBM Cognos 8 Servlet Gateway in IBM WebSphere 6 19 Press Save to Master Configuration and Save in the following dialog again. This may take some minutes to complete. Once finished, youll be returned to the homepage of the WebSphere Admin console. 3.4 Update environment setting for SGW Even though as of IBM Cognos 8 the deployed p2pd application doesnt require any special settings for the Java part, it still depends on one single environment setting for JNI which needs to be set. Whats required still is to append the /bin directory of IBM Cognos 8 to the Operating Systems library path. This will be PATH Windows LD_LIBRARY_PATH Solaris,LINUX LIBPATH AIX SHLIB_PATH HP-UX Best approach to do this is to specify this addition in IBM WebSphere directly, so only processes spawned from the java application see this setting, not interfering with settings made on the Operating System level in general. To do this go to the WebSphere administration console, click on Application Servers and next chose your application server instance, which hosts the Servlet Gateway.

In the appearing screen, expand Java and Process management topic in the right menu column and click Process Definition.

Cognos Proprietary Information

Deploying a secured IBM Cognos 8 Servlet Gateway in IBM WebSphere 6 20

Then click on Environment Entries. In the upcoming dialog, if not yet existent, create a new entry for the variable which corresponds to your operating system. As a value specify the <COGNOS_ROOT>/bin directory.

This value will be appended to the variable which is set in the environment being used whenever the Application Server spawns a process though JNI. Apply and click OK. The WebSphere console will prompt you to save your changes to the master configuration, dont forget to do so.

Cognos Proprietary Information

Deploying a secured IBM Cognos 8 Servlet Gateway in IBM WebSphere 6 21 3.5 Restart IBM WebSphere Now after the application file has been deployed we need to restart the WebSphere instance. This restart is mandatory, just starting the newly deployed application will not work because of the classloader being introduced. Stop the WebSphere server instance you deployed to. Wipe all log files from WebSphere instance, found at WAS_ROOT/profiles/default/logs/server1 for example (vanilla WAS 6 install) and the IBM Cognos 8 install used to build the Servlet Gateway. Start the WebSphere instance again You should see entries in WebSpheres SystemOut.log now reflecting the start of the ServletGateway application. 3.6 Test the Servlet Gateway Try hitting http://<server>:<port>/ServletGateway/servlet/Gateway You should get prompted by IBM WebSphere security now, actually the browser will prompt since we used BASIC authentication, which uses the browser to prompt for credentials. Use one of the WebSphere users defined in its User registry.

Cognos Proprietary Information

Deploying a secured IBM Cognos 8 Servlet Gateway in IBM WebSphere 6 22

Appendix A - Enable WAS security

Open WebSphere Administration console, default address would be http://<server>:9060/admin. When prompted to login, notice that if there is no security enabled yet there will be only one prompt-control instead of two. In addition some text hint will inform you, that currently no security is active. If security is enabled already, youre already setup and can leave this section, If not enter any name you want and press enter. Go to Security -> Global Security

Now configure a User registry. We use Iplanet LDAP in this example. To do this click on LDAP under the User registries on the top right column.

Cognos Proprietary Information

Deploying a secured IBM Cognos 8 Servlet Gateway in IBM WebSphere 6 23

Now you need to specify two user/passwords pairs. The first is a user from the LDAP which is used to run IBM WebSphere. It logically defines the identity WebSphere is using to run the instance. This will become our admin account. The second user is the bind user used to bind to the LDAP for searches, if left empty anonymous bind to the LDAP is used. In addition specify the host, port and BaseDN as well as the type of LDAP to use. You dont need to touch any of the other properties unless using SSL in which case you would have to select the proper SSL configuration from the dropdown. Press OK when done.

Cognos Proprietary Information

Deploying a secured IBM Cognos 8 Servlet Gateway in IBM WebSphere 6 24

Cognos Proprietary Information

Deploying a secured IBM Cognos 8 Servlet Gateway in IBM WebSphere 6 25 Now you will be returned to the Global security Page. On this page now set the checkbox for enable global security. This will automatically enable Enforce Java2 Security but you must uncheck this otherwise IBM Cognos applications wont start. Set the active Authentication mechanism to LTPA and select LDAP as the active User registry. Then press OK.

WARNING: If you havent configured LTPA setting before then some warning will appear and ask for some LTPA password. Just specify Cognos twice and press Apply and generate Keys. Once done, press OK to be returned to the Global security page again. You have to reapply the setting there as this page resets every time its loaded, so re-select LTPA and LDAP user registry. Press OK now.

Cognos Proprietary Information

Deploying a secured IBM Cognos 8 Servlet Gateway in IBM WebSphere 6 26 The Global Security Page will reload but the header will contain some information like this

Click on Save and in the next dialog on save again.

Now stop IBM WebSphere, wipe all WebSphere log files and start it again. When you try to access the WAS Admin console now, you will be redirected to some SSL protected URL which will present you with a SSL certificate which you need to trust. Further on, you will get prompted for authentication whey trying to login to WAS Admin console now.

Cognos Proprietary Information

Deploying a secured IBM Cognos 8 Servlet Gateway in IBM WebSphere 6 27

Cognos Proprietary Information

Deploying a secured IBM Cognos 8 Servlet Gateway in IBM WebSphere 6 28

Cognos Proprietary Information

Deploying a secured IBM Cognos 8 Servlet Gateway in IBM WebSphere 6 29

Appendix B Secure a Servlet Gateway EAR file using AST

The following will describe how to secure a pre-build EAR file using the WebSphere Application assembly tool (AST) Version 6. The assembly tool does not come with IBM WebSphere Application Server. It is on a CD called Application Server Toolkit or you can download it from the web (part number is C819CML). Using this toolkit, which is Eclipse behind the scenes, its possible to build the EAR files for p2pd or a Servlet Gateway through Cognos Configuration and adjust them for secured deployment later. As mentioned before, there is no functional difference to WAR files and the technique used in the document which involves editing the web.xml file manually. So using AST is just a more convenient way if achieving the same goal.

Start AST and if not already opened, open the J2EE perspective.

Click on Window...Open Perspective...Other, Select J2EE and press OK

Cognos Proprietary Information

Deploying a secured IBM Cognos 8 Servlet Gateway in IBM WebSphere 6 30

Click on FileImport and select ear file. Click Next.

In the upcoming Import Dialog, browse for your EAR file

Cognos Proprietary Information

Deploying a secured IBM Cognos 8 Servlet Gateway in IBM WebSphere 6 31 Once done, specify a project name which is different from ServletGateway and press Next.

On the next screen, ensure the ServletGateway.war is checked and press Finish

Cognos Proprietary Information

Deploying a secured IBM Cognos 8 Servlet Gateway in IBM WebSphere 6 32

Now back in the main window, expand the Dynamic WebProjects node and right-click on the Deployment Descriptor <somename> element. Choose open with -> Deployment Descriptor Editor.

Cognos Proprietary Information

Deploying a secured IBM Cognos 8 Servlet Gateway in IBM WebSphere 6 33 In the right pane, the Web deployment Descriptor editor will display. Find the tab selectors at the bottom of this pane and switch to the security tab.

Find the security Roles section in the upper left of the security tab. Click Add.

Cognos Proprietary Information

Deploying a secured IBM Cognos 8 Servlet Gateway in IBM WebSphere 6 34 In the dialog popping up specify the name of a Role which will be granted access to the resource we are about to protect. Make it comprehendible, though it wont be visible anywhere later. Press Finish.

Cognos Proprietary Information

Deploying a secured IBM Cognos 8 Servlet Gateway in IBM WebSphere 6 35 Youll be returned to the Deployment Descriptor Editor again. Now find the Security Constraint section right beneath the Security Roles on the left. Click Add.

Cognos Proprietary Information

Deploying a secured IBM Cognos 8 Servlet Gateway in IBM WebSphere 6 36 Another dialog pops up. Enter some name for the security constraint. No rules apply here, just choose something you can recognize later. Press Next.

Cognos Proprietary Information

Deploying a secured IBM Cognos 8 Servlet Gateway in IBM WebSphere 6 37 Now youll be presented with the Add Webresource dialog. Here you have to specify a name for the web resource first. Some warning message will appear in the top of the frame which you can ignore as we will specify the patterns in the second step. So first enter some resource name, any name will do. Then select the chekboxes for GET and POST only. Next, click on Add next to the Pattern box.

Enter the URL exactly like seen here (respect upper/lower case!).

Cognos Proprietary Information

Deploying a secured IBM Cognos 8 Servlet Gateway in IBM WebSphere 6 38 Press Add again and add a second pattern like this (same as before just append /*.

Your dialog should look like this now. Check with the screenshot and when verified, click Finish.

Cognos Proprietary Information

Deploying a secured IBM Cognos 8 Servlet Gateway in IBM WebSphere 6 39 Youre back in the Deployment Descriptor Editor again. Now as a final step to complete our security settings we add a reference to the role created previously to the constraint just defined. Find the Authorized Roles section in the lower right and click Add.

In the Define Authorization Constraint dialog which comes up specify a name (arbitrary) and check the checkbox next to the role defined earlier. Press Finish when done.

Cognos Proprietary Information

Deploying a secured IBM Cognos 8 Servlet Gateway in IBM WebSphere 6 40

This finishes the declaration of the web application security constraint. Now we need to extend this to the whole enterprise application, as we plan to build an EAR file. This will result in already pre-populated dialogs when deploying the EAR file to WebSphere later. Now find the element representing your EAR files Application Deployment Descriptor under the Enterprise Applications element and select it. You will see the Application Deployment Descriptor pane on the right. Under Security Roles click Details.

Cognos Proprietary Information

Deploying a secured IBM Cognos 8 Servlet Gateway in IBM WebSphere 6 41

On the security Tab press Gather. This will automatically retrieve the role name we defined for the web application already.

Youll see the Role name appearing there. Now just go over to WebSphere bindings and check the all authenticated users checkbox. This will predetermine the mapping of the role we defined to all users who successfully authenticated to IBM WebSphere.

Cognos Proprietary Information

Deploying a secured IBM Cognos 8 Servlet Gateway in IBM WebSphere 6 42 Were done. All thats left now is to export the EAR file. Go to File -> Export and select EAR file as the desired format. In the dialog appearing select you select your EAR project and browse to a location to export the EAR file to. Its a good idea to NOT overwrite the existing EAR but rather specify a new file for it. Click Finish when done

In the Save resources dialog make sure both, web and application deployment descriptors are marked selected. When verified, press OK to finally export the EAR file

Congratulations, you have now created an EAR file which contains all the necessary constraints to deploy the Servlet Gateway under IBM WebSphere security.

Cognos Proprietary Information