Oracle9iAS Portal Developer Kit (PDK)
Integrating a Database Web-based Application as a Partner Application with Oracle9iAS Portal

Introduction

This document describes the step-by-step process in how to go about integrating a database web-based application as a partner application with the Oracle9iAS Portal.

This document uses the example application Flights of Fancy, which is implemented in PL/SQL, to describe how the integration with Oracle9iAS Portal is performed.  The Flights of Fancy is an application that displays a list of flights for a user and provides links to display the details of each of the listed flights.

Related Documents

Oracle9iAS Portal Documentation
Oracle Single Sign-On Application Developer's Guide

Contents

The sample used in this article contains the following files:

Source files

flapp.pks: Package specification for the main package of the application.
flapp.pkb: Package body for the main package of the application.  It contains the code that displays the Flights of Fancy application and details for each flight.
flsec.pks: Package specification that contains the security routines of the application.
flsec.pkb: Package body that contains the security routines of the application.  Logic behind the security check that the application makes.
flapppro.pks: Package spefication for the provider implementation package of the application (i.e. Flights of Fancy provider).
flapppro.pkb: Package body for the provider implementation package of the application (i.e. Flights of Fancy provider).
flapptl.pks: Package spefication for the portlet implementation package of the application (i.e. Flights of Fancy Overview portlet).
flapptl.pkb: Package body for the portlet implementation package of the application (i.e. Flights of Fancy Overview portlet).
1. flinstal.sql: Installation script that compiles the portlet and provider packages. Called internally by install.sql
2. flreg.sql: Installation script that is called internally by install.sql for registering the Flights of Fancy provider. This must be run in the Oracle Portal schema.
3. install.sql: Main installation script that installs this sample. Prompts the user for 8 parameters - Oracle SID, Oracle Portal schema, Oracle Portal password, Provider schema, Provider schema password, Web Server, port, DAD, and the application name used to register the application with the Login Server.

Documentation

flappdb.html:  This document.

Integration for Flights of Fancy with Oracle9iAS Portal Login Server

This section describes the steps that have been taken to integrate the Flights of Fancy application as a partner application with Oracle9iAS Portal Login Server.

Setup Overview

Perform the setup steps described in the file SSO SDK ReadMe.txt.  These steps create the schema where the partner application is implemented and install the Login Server APIs in the application schema.  One of the steps is to execute the regapp.sql script which initializes the enabler APIs in the partner application schema and it requires some information which is obtained from the Login Server.  The partner application must be registered with the Login Server in order for this information to be available.

The Flights of Fancy application is implemented in the Partner Provider schema you choose.  The package name is flights_of_fancy and it exists in the files flapp.pks (package spec) and flapp.pkb (package body).

Secure application URLs

The application URLs that are considered secure should perform an application specific security check to determine whether a user has been authenticated.  This security check usually involves the generation of an application cookie.  If the application cookie exists then the URL is processed by the application.  If the application cookie does not exist then the browser redirects the user to the Login Server for authentication.  The Flights of Fancy application uses the flights_session cookie for security check.  The flights_session cookie contains the username of the currently logged on user.

The procedure check_privilege performs a check for the existence of the flights_session cookie.  All the protected URLs call this procedure first.  The entry point to the Flights of Fancy application is the show_flights procedure which also calls the check_privilege as the first step.  If the application cookie does not exist then the browser redirects the user to the Login Server for authentication.  Once the user is successfully authenticated the Login Server redirects back to the Flights of Fancy application executing a procedure that the application has specified when it was registered with the Login Server.  In this case the procedure executed is called process_success.  This procedure receives information about the authenticated user from the Login Server (through the urlc parameter) and creates the flights_session cookie.  It then displays the requested URL.

These steps are summarized in the following list:

1. Determine if the flights_session cookie exists.  If so, it is an indication that user authentication has already been performed by the Login Server.
2. If the cookie does not exist it redirects to the Login Server for authentication.
3. Once the Login Server completes user authentication it redirects back to the application.
4. The URL redirected to by the Login Server is the success URL specified in the Login Server for the Flights of Fancy application which is process_success(urlc in varchar2).  This URL creates the Flights of Fancy application cookie.
5. After the application cookie is created the requested URL is displayed.

Integration for Flights of Fancy with Oracle9iAS Portal provider API interface

A partner application is integrated with Oracle9iAS Portal provider API interface by creating a provider for it.  The provider should implement portlets for the application that display information about the application and also provide links to drill down to the application.

The provider for the Flights of Fancy application is implemented as a database provider in the package flights_of_fancy_provider.  The flights_of_fancy_provider contains one portlet which is implemented in the package flights_overview_portlet.  The flights_overview_portlet displays an overview of the flights displayed by the Flights of Fancy application.  In addition, it provides various links to drill down to the Flights of Fancy application.

The provider framework allows provider implementations to define a do_login() method which providers may use to create application specific browser cookies.  The do_login() method of the Flights of Fancy provider creates the flights_session cookie.  When an Oracle Portal page is displayed that contains the flights_overview_portlet the do_login of flights_of_fancy_provider is called generating the flights_session cookie.  When the user drills down to the application by accessing one of the links on the flights overview portlet no further user authentication is needed by the application since the application cookie (i.e. flights_cookie) exists.

Installation for Flights of Fancy Partner Application

This section describes the instructions for installing the Flights of Fancy application.  This includes a step to install the Single Sign-On (SSO) SDK which is required in order to enable a Partner Application to work with the SSO Login Server.

Step 1

The first step in installing this sample involves the installation of the SSO SDK.  This is a required step in order to enable an application to be a partner application with Oracle9iAS Portal.

Perform the required setup required by the Login Server SDK (i.e. ReadMe.txt). The SSO SDK can be downloaded from the Oracle9iAS Portal Developer Kit (PDK) site on OTN.  The installation is detailed in the Install.txt in the SDK.

In summary the installation of SSO SDK includes the following items:

• Creating your application schema (also referred as provider schema) where the SSO SDK will be loaded. In this schema the PL/SQL packages related to the provider for the application are also installed.
• Running loadsdk.sql in the application schema you created to load the SDK PL/SQL packages.
• Adding your new Partner Application via Oracle9iAS Portal. This is where you register the Flights of Fancy Partner Application with the Login Server.
• You can do this by logging into Oracle Portal, clicking the Administer tab, and choosing the Login Server Administration link.
• You can then administer Partner Applications to add a new Partner Application.
• Choose an application name for your Partner Application. Note the Application name you choose, for use later on.
• For the Home URL, you can choose to use the Portal Home URL since this will be invoked if you press 'Cancel' while logging in with the Login Server.
• For the Success URL, you need to invoke the process_success procedure of the flights_of_fancy package. So the URL will be of the following format:

   http://<Web Server>:<Port>/pls/<DAD>/<Partner Provider Schema>.flights_of_fancy.process_success
• For the Logout URL, you need to invoke the process_logout procedure of the flights_of_fancy package.  So the URL will be of the following format:

   http://<Web Server>:<Port>/pls/<DAD>/<Partner Provider Schema>.flights_of_fancy.process_logout
• Editing and running the regapp.sql script as directed, connected as the partner schema.

Important! One of the instructions in ReadMe.txt (SSO SDK installation) is about installing the partner application packages.  This is described in the next 2 steps.

Example

On the Create Partner Application screen enter the following values:

Name: Flights_of_Fancy
Home URL: http://portalstudio.oracle.com:3000/pls/portal30
Success URL: http://portalstudio.oracle.com:3000/pls/portal30/flights.flights_of_fancy.process_success
Logout URL: http://portalstudio.oracle.com:3000/pls/portal30/flights/flights_of_fancy.process_logout

Note: The DAD used is the same as the one used to access the portal.

When running the regapp.sql script enter the following values:

Listener_Token: flightsapp:my.oracle.com:3000
Site_ID: 1326
Site_Token: 27OE91MH1326
Login_URL: http://portalstudio.oracle.com:3000/pls/portal30_sso/portal30_sso.wwsso_app_admin.ls_login
Encryption_Key: D903ECAE1C1FF377
IP_Check: Y

Important! You can find the instructions on how to run the regapp.sql script in the file ReadMe.txt of the SSOSDK.

Step 2

Enable the application schema created earlier, to be used as as portal provider schema.  This is necessary because this sample in addition to being a partner application it is also a database provider. Run the provsyns.sql script for the application schema.  This file exists in the wwc directory.  Instructions in running this script exist inside the script.

Step 3

Install the partner application packages provided with this sample.

In sqlplus, in the PORTAL schema, run install.sql :
SQLPLUS> @install.sql

This script asks for the following information:

• Oracle SID
• Portal schema
• Portal password
• Provider schema
• Provider schema password
• Web Server
• Port Number
• DAD name
• Partner Application name used to register the application with the Login Server in step 1.

Important!  The Partner Application name described above must match the Application name segment of the listener_token parameter that was specified when running the regapp.sql script of the SSOSDK.

If the listener_token is flightsapp:my.oracle.com:3000 then the Partner Application name should be flightsapp for the install.sql.

Example

...portal_sid:            s817dev7
...portal_schema:         portal30
...portal_password:       *************
...prov_schema:           flights
...prov_password:         *************
...listener_server:       portalstudio.oracle.com
...port_number:           3000
...dad_name:              portal30
...app_name:              flightsapp

Step 4

The main screen for accessing the partner application is:
http://<web_server>:<port>/pls/<dad>/<provider_schema>.flights_of_fancy.show_flights

Example

http://portalstudio.oracle.com:3000/pls/portal30/flights.flights_of_fancy.show_flights

Execution Scenarios for Flights of Fancy

The following execution scenarios show the integration of the Flights of Fancy application with Oracle9iAS Login Server and provider API interface.  Prior to executing each of the execution scenarios it is very important to quit all the browser windows.

Scenario 1: Access the Flights of Fancy application

Access the Flights of Fancy show_flights application.  The URL for doing this is the following:

http://<host>:<port>/pls/<dad>/<provider_schema>.flights_of_fancy.show_flights

Since this is a secure URL it performs a security check to determine if the application cookie exists.  Since the application cookies does not exist yet it redirects to the Login Server for user authentication.  Once the user logs on the Login Server redirects back to the application displaying the requested page (i.e. flights_of_fancy.show_flights page).  Before the page is displayed the application generates the flights_session cookie.

Scenario 2: Access Oracle9iAS Portal and then the Flights of Fancy application

Access Oracle9iAS Portal and click the Login link.  This causes a redirect to the Login Server.  Once the user logs on, the Login Server redirects back to the Oracle Portal Home Page.  Before displaying a page that contains the flights overview portlet, access the Flights of Fancy application by displaying the show_flights screen (as in Scenario 1).  Since the flights_session does not exist a redirect is made to the Login Server.  The Login Server determines that the user has already been authenticated because of earlier Login operation requested by Oracle9iAS Portal.  As a result the Login Server performs an immediate redirect back to the flights of fancy application.  This causes the flights_session cookie to be created without requiring an additional user authentication by the Login Server.

Scenario 3: Access the Flights of Fancy application through the Flights of Fancy provider

Access Oracle9iAS Portal and click the Login link.  This causes a redirect to the Login Server.  Once the user logs on the Login Server redirects back to Oracle9iAS Portal displaying the Home Page.  Create a page with the flights overview portlet and display it.  When the page is displayed the flights_session cookie is created because the do_login() method of the flights_of_fancy provider is called.  Access the Flights of Fancy application by displaying the show_flights screen (as in Scenario 1).  This does not cause a redirect to the Login Server.  This is so because the show_flights screen sees the flights_session cookie (which has been created by the do_login() method) and does not perform the redirect to the Login Server.

You could also add the Flights of Fancy Overview portlet to your own pages and access it directly.

Note for executing the above scenarios:  Each of the above scenarios must be executed in a new browser session.  This is accomplished by quitting all browser windows and restarting the browser before executing each of the scenarios.

 

Revision History:

Revision No Last Update 1.0 August 22, 2002