Introduction

This document describes how to integrate a partner application with Oracle9iAS Portal.  A partner application is a Web based application which is integrated with the Single Sign-On SSO Server.  Such an application is integrated by creating a provider for it and registering it with Oracle Portal.

This document uses the example application Flights of Fancy, which is implemented as a Web based application, to describe how the 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.

Related Documents

Oracle9iAS Portal Documentation
Oracle Single Sign-On Application Developer's Guide
Oracle9iAS Portal Developer Kit - Installing the PDK-Java Framework and Samples

Partner Application Installation

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

CONTENTS

Files

samples.jar: The Java Jar file containing all the class files for this example. This file is located under the jpdk/lib directory.
 
PartnerServlet.java: The Java class that is the entry point to the "Flights of Fancy" application from outside the portal.  This file is located under the jpdk/src/oracle/portal/sample/devguide/partnerApp directory.
 
PartnerProvider.java: The Java class that is the entry point to the "Flights of Fancy" application when it is called from inside the portal.  This file is located under the jpdk/src/oracle/portal/sample/devguide/partnerApp directory.
 
FlightDispatch.java:  The Java class that contains the methods for displaying the "Flights of Fancy" application screens.  This file is located under the jpdk/src/oracle/portal/sample/devguide/partnerApp directory.
 
FlightRenderer.java:  The Java class that renders the "Flights of Fancy" portlet within the Portal.  This file is located under the jpdk/src/oracle/portal/sample/devguide/partnerApp directory.
 
PartnerSSOEnabler.java:  The Java class that contains the security methods for the "Flights of Fancy" application.  This file is located under the jpdk/src/oracle/portal/sample/devguide/partnerApp directory.
 
provider.xml: The provider.xml configured for the "Flights of Fancy" example.  This file is located under the jpdk/providers/partnerApp directory.
 
ReadMe.txt: Installation instructions for the "Flights of Fancy" application.  This file is located under the jpdk/providers/partnerApp directory.

integrating.partner.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 Server.

Step 1

Perform the required setup required by the SSO Server SDK. The SSO SDK can be downloaded from the PDK site on OTN.  The installation is detailed in the Install.txt in the SDK.

This SDK install includes:

• Loading the PL/SQL crypto packages (Database Server 8.1.6) 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.  This file is located in the packages directory under SSO.

• Adding your new Partner Application through the Portal UI. This is where you setup the Flights of Fancy Partner Application with the SSO Server.

  • You can do this by logging into Oracle Portal as an SSO Administrator.  For example:  portal30  Note:  portal30_sso may not see the Administer tab.

  • Click on the Administer tab, and choose the SSO Server Administration link.

  • You can then click on Administer Partner Applications and 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 SSO Server.  

     For example:  http://<Web Server>:<Port>/pls/portal30/

• 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>/servlets/flights.

• Note the Application Name, ID, Token, and Encryption Key for editing and running the regapp.sql script as directed. You will need to update the regapp.sql file with the following information.

  • p_listener_token : Listener token for your application.

    • Syntax : <application name>:<SSO webserver host name>:<port>

    • Example : Sample Partner Application:www.ssosvr.com:80

    • Description : This parameter is used to identify an Partner Application from configuration information. This name will be used inside  the sample application code.

  • p_site_token : Site token for your application.

    • Syntax:  <Token> 

    • Example:  DP41OCI51323

    • Description : This parameter will be supplied by Oracle Portal when creating a Partner Application.  This parameter may be supplied by the administrator

  • p_site_id : Site id for your application.

    • Syntax:  <ID>

    • Example:  1324

    • Description:  This parameter will be supplied by Oracle Portal when creating a Partner Application.  This parameter may be supplied by the administrator

  • p_login_url : Login URL of SSO Server

    • Syntax:  http://<Web Server>:<port>/pls/<Portal SSO DAD>/Portal Login URL

    • Example : http://www.ssosvr.com/pls/portal30_sso/portal30_sso.wwsso_app_admin.ls_login

    • Description : If you don't know the Login URL then you can click on the Login link in Oracle Portal. Once the Login Screen appears copy the URL from the browser window and use it as your SSO Server login URL.

  • p_cookie_version : Version of the SSO server cookie

    • Syntax:  v<version#>

    • Example:  v1.0

    • Description : The cookie version for this version of SDK will be v1.0

  • p_encryption_key : Encryption key for your application

    • Syntax:  <Encryption Key>

    • Example:  63a0fb15a89299a8

    • Description:  This parameter will be supplied by Oracle Portal when creating a Partner Application.  This parameter may be supplied by the administrator

  • p_ip_ckeck : IP address check flag for security purpose.

    • Syntax:  Boolean value

    • Example:  N

    • Description : Set it to Y for added security. Otherwise set it to N

     

Step 2

Follow the Installing the JPDK and Samples article to install the JPDK on the partner applications listener.

Step 3

• Stop your Oracle HTTP Server if still running.

• This section assumes that you have extracted the PartnerApplication.zip in the following directory:  C:\FancyFlightsPartner

• In the jserv.properties file add the following section containing the wrapper.classpath statements. 

  wrapper.classpath=C:\FancyFlightsPartner\samples.jar

•  Save and close the jserv.properties file. 

• In the zone.properties file, Under the Servlet Aliases section, add the alias that points to the Provider Adapter: Note, you must use "flightsprov" as the alias.

  servlet.flightsprov.code=oracle.portal.provider.v1.http.HttpProvider 

• Now in the same section, add the alias that points to the SSOSignOnServlet.  Note, you must use "flights" as the alias.

  servlet.flights.code=oracle.portal.sample.devguide.partnerApp.PartnerServlet 

• Under the Aliased Servlet Init Parameters section, add the initial arguments needed by the sample. This points the Adapter (sample) to the location of the provider.xml file. Make sure to modify the directory to point to the correct location of the provider.xml file. 

  servlet.flightsprov.initArgs=provider_root=C:\FancyFlightsPartner, sessiontimeout=1800000

  Note: the sessiontimeout must match the session.timeout setting located in the zone.properties of your Apache listener. Both settings are specified in milliseconds. 

• Also in the Aliased Servlet Init Parameters section, add the initial arguments needed by the sample to connect with the partners database and the SSO server. The parameters need to be set up for both the flightsprov (partner code used with portal) and the flights (partner servlet used independent of the portal). Make sure to modify the the arguments to suit your environment.

  • servlet.flightsprov.initArgs=listenerToken=flights:portal30_sso:5000

  • servlet.flightsprov.initArgs=requestedUrl=http://flights.oracle.com/servlets/flights

  • servlet.flightsprov.initArgs=onCancelUrl=http://flights.us.oracle.com

  • servlet.flightsprov.initArgs=partnerAppCookieName=SSO_PAPP_SERVLET_ID

  • servlet.flightsprov.initArgs=partnerAppCookieDomain=oracle.com

  • servlet.flightsprov.initArgs=partnerAppCookieScope=/

  • servlet.flightsprov.initArgs=partnerAppCookieDesc=SSO application cookie

  • servlet.flightsprov.initArgs=dbSchema=scott

  • servlet.flightsprov.initArgs=dbPassword=tiger

  • servlet.flightsprov.initArgs=dbhost=flightsdb.oracle.com 

  • servlet.flightsprov.initArgs=dbport=1521

  • servlet.flightsprov.initArgs=dbsid=orcl 

  • servlet.flights.initArgs=listenerToken=flights:portal30_sso:5000

  • servlet.flights.initArgs=requestedUrl=http://flights.oracle.com/servlets/flights

  • servlet.flights.initArgs=onCancelUrl=http://flights.oracle.com

  • servlet.flights.initArgs=partnerAppCookieName=SSO_PAPP_SERVLET_ID

  • servlet.flights.initArgs=partnerAppCookieDomain=oracle.com

  • servlet.flights.initArgs=partnerAppCookieScope=/

  • servlet.flights.initArgs=partnerAppCookieDesc=SSO application cookie

  • servlet.flights.initArgs=dbSchema=Scott

  • servlet.flights.initArgs=dbPassword=tiger

  • servlet.flights.initArgs=dbhost=flightsdb.oracle.com 

  • servlet.flights.initArgs=dbport=1521 

  • servlet.flights.initArgs=dbsid=orcl 

     

  • The following outlines the syntax for these variables:
    • listenerToken - Listener token for your application. This argument is used to identify the partner application's configuration information located in the partner database's SSO tables . This should be the same as the listenerToken used in the regapp.sql file.

      syntax - <application name>:<SSO Webserver host name>:<port>

      For example:  Sample Partner Application:www.ssosvr.com:80

    • requestedUrl - The URL to the partner application. This is the URL that the SSO server redirects the user to after the user has succesfully logged in. This will be the URL that executes the portlet.

      For example:  http://host.domain:port/servlets/flights

    • onCancelUrl - The URL to the partner application's public page. This is the URL that the SSO server redirects the user to after the user fails to succesfully log in.  This may be your Oracle Portal Home Page.

      For example:  http://host.domain:port/pls/PORTAL30/

    • partnerAppCookieName - The partner application cookie name. You should be able to leave the default cookie name given.

    • partnerAppCookieDomain - The partner application cookie domain.  This is the domain you were authenticated on for Oracle Portal.  For example, if the URL to contact Portal is http://myserver.oracle.com/pls/portal30/.  Your domain is oracle.com and your CookieDomain should also be oracle.com.

    • partnerAppCookieScope - The partner application cookie scope. You should be able to leave the default cookie scope given.

    • partnerAppCookieDesc - The partner application cookie description. You should be able to leave the default cookie description given.

    • dbSchema - Partner schema where the Oracle Web Single Sign-On SDK is installed.

      For example:  partner

    • dbPassword - Password to partner schema.

      For example:  partner

    • The next three entries are used to connect to your database. Provider the server name, database server port number, and database SID name.

      • dbhost -The host address used for the database.

      • dbport - The host port used for the database.

      • dbsid - The host service name used for the database. 

  • Save and close the zone.properties file. 

Step 4

• Re-start your Oracle HHTP Server.
• Register the Provider.

  After setting up the Partner example with the Oracle HTTP Server, you must now register the Partner Provider with Oracle Portal before adding the partner portlet(s) to your page.

  • Under the Administer tab on the Oracle Portal Home Page, click on Add a Portlet Provider within the portlet called Provider.

  •  Fill out Provider information for the Sample.

    1. Name: SamplePartnerProvider

    2. Display Name: Sample Partner Provider

    3. Timeout: 20

    4. Timeout Message: Partner Provider Timed Out

    5. Implementation Style: Web

    6. Provider Login Frequency: Once per User Session

    7. Register on Remote Nodes: No

    8. URL: http://myserver.mydomain.com:port/servlets/flightsprov (replace this with your URL)

    9. Check the following radio button: The user has the same identity in the Web providers application as in the Single Sign-On identity. 

    10. Proxy:  No (As long as no proxy is required to contact the Provider Adapter).

  • Click OK.

Step 5

To view the Partner Application, make sure to logout of Oracle Portal.  Go to the following URL in the browser.

http://<web_server>:<port>/servlets/flights

You should notice that because you are not authenticated with the Oracle Portal, you are also not authenticated with this partner application. Login to the Partner Application and view the "Flights of Fancy" application.  You should also be able to change your URL to the Oracle Portal URL and go directly with the Home Page without having to login again.  You can also add this partner application as a portlet within Oracle Portal.

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 portal.

Setup

Perform the setup steps described in the file SSO SDK Install.txt.  These steps create the schema where Oracle Web Single Sign-On SDK is installed. One of the steps, the regapp.sql script initializes the enabler APIs in the schema and it requires some information which is obtained from the SSO Server.  The partner application must be registered with the SSO Server in order for this information to be available.

The Flights of Fancy application is implemented on the listener you choose.  The provider for the "Flights of Fancy" application is implemented as a Web provider in samples.jar.  The "Flights of Fancy" provider contains one portlet as defined in provider.xml.

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 SSO Server for authentication.  The Flights of Fancy application uses the sso_papp_servlet_id cookie for security check.  The sso_papp_servlet_id cookie contains the encrypted username of the currently logged on user.

The process() methods performs a check for the existence of the sso_papp_servlet_id cookie.  All the protected URLs call these methods.  The entry point to the "Flights of Fancy" application from outside the portal is the PartnerServlet class. The entry point to the "Flights of Fancy" application when it is called from inside the portal is the PartnerProvider class. Each of these call the process() methods which check for the existence of the sso_papp_servlet_id cookie as the first step.  If the application cookie does not exist then the browser redirects the user to the SSO Server for authentication.  Once the user is successfully authenticated the SSO Server redirects back to the Flights of Fancy application executing a procedure that the application has specified when it was registered with the SSO Server. When the process() method receives information about the authenticated user from the SSO Server (through the urlc parameter), it creates the sso_papp_servlet_id cookie.  It then displays the requested URL.

These steps are summarized in the following list:

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

After the application cookie is created the requested URL is displayed.

A partner application is integrated with the 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 Web provider in the samples.jar. The Flights of Fancy provider contains one portlet as defined in provider.xml.  The portlet displays an overview of flights.  In addition, it provides links to drill down into the Flights of Fancy application.

The Flights of Fancy application extends the default provider and replaces the calls to: initSession and init.

The provider framework allows Web provider implementations to define a initSession() method that providers may use to create application specific browser cookies. The initSession() performs all session and login work. The initSession() method for the Flights of Fancy provider creates the sso_papp_servlet_id cookie.  When a portal page is displayed that contains the Flights of Fancy portlet the initSession() of the Flights of Fancy provider is called, generating the sso_papp_servlet_id cookie.  When the user drills down to the application by accessing one of the links in the portlet, no further user authentication is needed by the application since the sso_papp_servlet_id cookie exists.

The exception to this is if the portal and the partner application exist in separate cookie domains. If this is the case, then selecting a link in the Flights of Fancy portlet will have the same effect as if the Flights of Fancy application was called directly. It will redirect the user to the SSO Server, the SSO Server will see that the user is already authenticated and will redirect the user back to the requested link. At this point, the Flights of Fancy application will create a new sso_papp_servlet_id cookie. In this scenario, if a partner application tracks session information and has the Portal and the partner application in different cookie domains then there is the potentially for two partner application sessions to be created. To avoid this partner applications that track session information should place their application in the same cookie domain as the Portal.

Flights of Fancy Execution Scenarios

The following execution scenarios show the integration of the flights of fancy application with the Oracle Portal and SSO Server.

Scenario 1 - Access the Flights of Fancy application

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

http://<host>:<port>/servlets/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 SSO Server for user authentication.  Once the user logs on the SSO Server redirects back to the application displaying the requested page.  Before the page is displayed the application generates the sso_papp_servlet_id cookie.

Scenario 2 - Access the Portal and then the Flights of Fancy application

Access the Portal and click on the login link.  This causes a redirect to the SSO Server.  Once the user logs on, the SSO 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 from outside the portal (as in Scenario 1).  Since the sso_papp_servlet_id cookie does not exist a redirect is made to the SSO Server.  The SSO Server determines that the user has already been authenticated because of earlier login operation requested by the portal.  As a result the SSO Server performs an immediate redirect back to the flights of fancy application.  This causes the sso_papp_servlet_id cookie to be created without requiring an additional user authentication by the SSO Server.

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

Access the Portal and click on the login link.  This causes a redirect to the SSO Server.  Once the user logs on the SSO Server redirects back to the portal displaying the home page.  Create a page with the Flights of Fancy portlet and display the page.  When the page is displayed the sso_papp_servlet_id cookie is created because the initSession() method of the Flights of Fancy provider is called.  Access the Flights of Fancy application from outside the portal (as in Scenario 1).  This does not cause a redirect to the SSO Server.  This is so because the Flights of Fancy application sees the sso_papp_servlet_id cookie (which has been created by the initSession() method) and does not perform the redirect to the SSO Server.

You could also add the Flights of Fancy 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.