Oracle9iAS Portal Developer Kit (PDK)
Using PDK-Java and mod_osso to Integrate a Partner Application with Oracle9iAS Portal (V2)

Introduction

This document describes how you can use the PDK-Java and mod_osso to integrate a partner application with Oracle9iAS Portal. A partner application is a web based application that shares the same Single Sign-On (SSO) Server as Oracle9iAS Portal for its authentication. This means that when a user is already logged into Oracle Portal, their identity can be asserted to the partner application without them having to log in again.

For even tighter integration with Oracle9iAS Portal, a partner application can be exposed as a web provider using the PDK-Java, so that it may be accessed from a portlet on a Oracle Portal page. This document demonstrates this style of integration by looking at an example web application, "Flights of Fancy", and describing how its integration with Oracle Portal is performed.  The Flights of Fancy application displays a list of flights for a user and provides links to display the details of a flight.

The Flights of Fancy application consists of two pages, a summary page listing a number of flights and a detail page showing details of a specific flight. Clicking of the flight number takes you from the summary page to the detail page. When integrated with Oracle Portal the summary page is exposed as a portlet and clicking on the flight number in the portlet takes you from the portal to the Flight of Fancy application where the detailed page is displayed without requiring the user to login. This type of link that takes a user from Portal to an application is known as a "deep link".

The above image shows the summary page of the Flight of Fancy Applications.

Related Documents

• Overview of Portlet Security
• Overview of password authenticated applications
• Oracle9iAS Portal Developer Kit - Installing the PDK-Java Framework and Samples

Installation

This section contains instructions for installing the Flights of Fancy sample partner application.

Step 1: Installing and Configuring PDK-Java

• Follow the instructions in Installing the PDK-Java Framework and Samples to install PDK-Java in an Oracle 9iAS Oracle Home.

• Start Oracle HTTP Server

• Test your provider is configured correctly by trying to access its test page in a browser, through a URL of the form http://<host>:<port>/jpdk/providers/partner. If you do not see a web provider test page that mentions a single portlet called PartnerFlightPortlet, then carefully review all the previous configuration steps.

Step 2: Configuring mod_osso

• When registering mod_osso it is important to register mod_osso with the same Oracle Single Sign On Server that is being used by Oracle Portal.
  Register mod_osso as a Partner application to a SSO by running

  $ORACLE_HOME/sso/bin/ssoreg \
  -oracle_home_path <absolute_oracle_home_path> \
  -host <host> \
  -port 1521 \
  -sid <sid> \
  -schema <sso schema name> \
  -pass <sso schema passwd> \
  -site_name <host:port> \
  -success_url <protocol://host:port>/osso_login_success \
  -logout_url <protocol://host:port>/osso_logout_success \
  -cancel_url <protocol://host:port>/ \
  -home_url <protocol://host:port>/ \
  -config_mod_osso TRUE \
  -u <priv_user> \
  -ip_check FALSE\
  -sso_server_version v1.2

  where

  <absolute_oracle_home_path> the absolute path to the ORACLE_HOME e.g. /disk2/oracle/ora902 rather than ../ora902
  <host> is the host of the SSO
  <sid> is the sid of the SSO database
  <sso schema name> is the schema name of the SSO repository
  <sso schema passwd> is the schema password of the SSO repository
  <host:port> is the hostname:Port of the web provider eg "machine.com:7778"
  <protocol://host:port> is the Protocol://hostname:port of the web provider eg "http://machine.com:7778"
  <priv_user> Privilege user, use root or System if running on unix or NT

  ip checking should be switched off otherwise mod_osso will not allow access to url's if the portal user uses a proxy server from their browser.

  All the url's used in the mod_osso configuration need to be accessible for all portal users. May need to change httpd.conf etc. The home_url and cancel_url can be any url that a portal user can access. The -cancel_url is where the browser is redirected if the user presses cancel on the login screen. The -home_url is where the browser is redirected after the user has logged out.

• Ensure that the configuration file mod_osso.conf is being read by Oracle HTTP Server. Edit $ORACLE_HOME/Apache/Apache/conf/httpd.conf and make sure the following line is not commented out.

  include "$ORACLE_HOME/Apache/Apache/conf/mod_osso.conf"

• Add SSO authentication to servlet requests by modifying the file $ORACLE_HOME/Apache/Apache/conf/mod_osso.conf and add the following:

  <Location /jpdk/servlet/PartnerAppFlights>
  AuthType Basic
  require valid-user
  </Location>

  You may want to switch off IP checking for mod_osso to make access to the site easier if your
  customers use proxy settings in their browsers

  OssoIpCheck off

• Restart the Oracle HTTP Server

Step 3: Registering the Partner Application Provider with Oracle Portal

• From the Build tab on the Oracle Portal Home Page, click on Register a Portlet Provider within the portlet called Providers.

• Register with the following parameters:

  • Name: SamplePartnerProvider
  • Display Name: Sample Partner Provider
  • Timeout: 10
  • Implementation Style: Web
  • URL: http://<host>:<port>/jpdk/providers/
  • Service Id: urn:partner
  • Login Frequency: Once Per User Session

• Make sure the following radio button is selected:

  The user has the same identity in the Web providers application as in the Single Sign-On identity

• If you know that both the Oracle Portal and PDK-Java listeners are included in the same cookie domain you specified in step 4 then select.

  Web provider in same cookie domain as the portal

• Click Finish

• Add the provider's portlet to a page and view the page.

• The portlet should display a list of flights. When you click on one of the flight links, you are redirected to the stand alone version of the Flights of Fancy application. However, because it shares the same SSO server as the Oracle Portal, the application will trust your identity without requiring you to log in.

Step 4: Changing the cookie domain

This sample code uses a session cookie to share information between the portlet and the web application. By default OC4J sends the session cookies back to the caller with a cookie domain set to the machine that the PDK-Java was installed on. When the browser makes a request for a page it looks at the host from the request and sends all cookies whose cookie domain matches the host. The problem arises when Oracle Portal and the PDK-Java are on different machines, in this case a session created from the servlet will not be shared by Oracle Portal and vice versa. Consequently it is necessary to widen the cookie domain so that it encompasses both the PDK-Java host and the Oracle Portal host.

• If Oracle Portal and the PDK-Java are on the same machine and same port no action is required.

• If Oracle Portal and the PDK-Java are on different machines edit $ORACLE_HOME/j2ee/home/application-deployments/jpdk/jpdk/orion-web.xml. Add the following between the tags <orion-web-app...> and </orion-web-app>

  <session-tracking cookie-domain=".xxx.com" cookie-path="/">
  </session-tracking>

  where .xxx.com is a cookie domain that encompasses the PDK-Java host and the Oracle Portal host.

Implementation

This section takes a look at how the Flights of Fancy application is implemented.

Source Files

The complete Java source code for this example partner application is included in the PDK-Java distribution, under the directory src/oracle/portal/sample/v2/devguide/partnerApp. The files are:

• FlightDispatch.java:  This class contains the methods for displaying the "Flights of Fancy" application screens.
• PartnerServlet.java: This is the servlet entry point to the application, which allows it to function as a stand alone web application.
• PartnerProvider.java: This class extends the PDK-Java ProviderInstance class, and contains the functionality required to expose the application as a portlet in Oracle9iAS Portal.
• FlightRenderer.java:  This class renders the "Flights of Fancy" portlet within the Portal.

Code implementation

In a partner application, the application URLs that are considered secure should perform an application specific security check to determine whether a user has been authenticated.  This security checks are performed in two different ways. When the application is being called as a stand alone servlet and the deep links on the Flights of Fancy portlet are protected by mod_osso which checks if the user is logged on and if not prompts the user for a username/password. When a portlet is called the provider does a check is made to verify that the user is logged on.

The entry point to the "Flights of Fancy" application from outside the Oracle Portal is the PartnerServlet class. The entry point to the "Flights of Fancy" application when it is called from inside the Oracle Portal is the PartnerProvider class. Each of these call the process() methods which check handle the request and then displays the requested URL.

The class FlightDispatch does most of the work for this sample. In this class there are two equivalent methods called process which handle requests from Oracle Portal or a servlet request. The only real difference between these methods is how they extract information from the request.

process(HttpServletRequest req, HttpServletResponse res) a servlet request

• req.getRemoteUser() returns the user name logged into Oracle Single Sign On Server.
• No need to check if you are logged in as mod_osso protects this function from being called if the user is not logged in.
• A session gets created if not found in the request ServletProviderSession.getAttachedSession(req,true)

• pr.getUser().getName() returns the user name logged into Oracle Single Sign