Introduction

This document describes how to integrate a partner application with the Oracle9iAS Portal. A partner application is a Web based application which is integrated with the Login Server. Such an application is integrated with the Oracle9iAS Portal by creating a provider for it and registering it with 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 application displays a list of flights for a user and provides links to display the details of a flight.

Related Documents

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

Partner Application Installation

This section gives an overview of the steps involved in installing this partner application.

CONTENTS

Files

flapptl.pks: Contains detailed comments and headers for the Flights of Fancy Overview Portlet.
flappptl.pkb: Logic behind Flights of Fancy Overview Portlet.
flapppro.pks: Contains detailed comments and headers for the Flights of Fancy Provider.
flapppro.pkb: Logic behind Flights of Fancy Provider.

flapp.pks: Contains headers for showing the Flights of Fancy application and details for each flight.

flapp.pkb: Logic behind showing the Flights of Fancy application and details for each flight.

flsec.pks: Contains headers for the security check that the application makes.

flsec.pkb: Logic behind the security check that the application makes.

flinstal.sql: Script that compiles the portlet and provider packages. Called internally by install.sql

flreg.sql: Called internally by install.sql for registering the Flights of Fancy provider. This needs to be run in the Oracle Portal schema only.

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.

flappdb.html:  This document.

Instructions for installing the Flights of Fancy application.  This includes a step to install the Single Sign-On (SSO) SDK since a Partner Application works along with the SSO Login Server.

Step 1

Perform the required setup required by the Login Server SDK. 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.

This includes:

• Loading the PL/SQL crypto packages and the OWA packages if not already loaded in your database.
• Creating your Provider schema where the SSO SDK will be loaded. In this schema the provider and portlets implemented for the application are also installed.
• Loading SSOHash.class using loadjava for the Provider schema you created.
• Running loadsdk.sql in the Provider schema you created.
• 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.
• Editing and running the regapp.sql script as directed, connected as the partner schema.

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

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

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

exec papp_reg(p_listener_token => 'flightsapp:portalstudio.oracle.com:3000', p_site_token => '193W7Q051323', p_site_id => '1323', p_login_url => 'http://portalstudio.oracle.com:3000/pls/portal30_sso/portal30_sso.wwsso_app_admin.ls_login', p_cookie_version => 'v1.0', p_encryption_key => 'BCA3A66CC1CF1381', p_ip_ckeck => 'Y'
);

Important!

You can find the instructions on how to edit the regapp.sql file in the install.txt of the SSOSDK.

Step 2

Enable the Provider schema created earlier, to be used as as Partner Application schema.  Run the provsyns.sql script for the provider schema.  This file exists in the wwc directory.  Instructions in running this script exist inside the script.

Step 3

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.

The Partner Application name described above must match the Application name segment of the listener_token parameter, 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

Partner Application Implementation

This section gives an overview of the steps involved in implementing a partner application.  It is not the purpose of this document to describe how to implement partner applications.  However, this overview is given in this section in order to facilitate the description of how to perform the integration with the Oracle9iAS Portal.

Setup

Perform the setup steps described in the file SSO SDK Install.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, the regapp.sql script 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.

A partner application is integrated with Oracle9iAS Portal 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.

Flights of Fancy Execution Scenarios

The following execution scenarios show the integration of the Flights of Fancy application with Oracle9iAS Portal and the Login Server.

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.