This document describes how you can integrate an external application with Oracle9iAS Portal. External applications have their own user identities and they are different from the identity of the user in Oracle Portal which is defined by the Single Sign-On (SSO) Server. These applications are integrated with the SSO Server as 'External Applications' and are integrated with Oracle Portal through the Web Provider Framework. In this document, we refer to this provider as the External Application Web Provider.

Once an application is registered as an External Application, the SSO Server stores the user name mapping, password and any other credentials required for the portal user. Oracle Portal has shared access to the SSO Server password store and hence, the mapped user name and the user credentials will be sent to the external application during the call to Provider's initSession.

This document uses the example application 'Flights of Fancy', which is implemented in Java, 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.

Note: The External Application functionality detailed here requires Oracle9iAS Portal version 3.0.8 or later. If you do not have a 3.0.8. installation, this sample will not work for you.

Related Documents

• Oracle9iAS Portal Documentation

• Oracle Single Sign-On Application Developer's Guide

EXTERNAL APPLICATION SAMPLE INSTALLATION

This section describes how to install the sample External Application Web Provider.

Contents

The External Application example consists of several Java source files, Java executables and this documentation.

Source Files

• samples.jar: Java executable for the sample. This file is located under the jpdk/lib directory.

• provider.xml: XML file used by the provider. This file is located under the jpdk/providers/externalApp directory.

• ApplicationLogin.java : Handles all functions dealing with user login, e.g. inspecting a request to determine is the user is logged in. This file is located under the jpdk/src/oracle/portal/sample/devguide/externalApp directory.

• ExternalProvider.java: Provider for the Fancy Flights Application. This file is located under the jpdk/src/oracle/portal/sample/devguide/externalApp directory.

• ExternalServlet.java : Performs required actions for the standalone Servlet. This file is located under the jpdk/src/oracle/portal/sample/devguide/externalApp directory.

• FlightDispatch.java : Performs all of the significant work, including request routing, list screen display, details screen display, etc. This file is located under the jpdk/src/oracle/portal/sample/devguide/externalApp directory.

• FlightRenderer.java: Renders the portlet content for the Fancy Flights provider. This file is located under the jpdk/src/oracle/portal/sample/devguide/externalApp directory.

Documentation

• integrating.external.provider.html:  This document.

Installation

This section contains installation instructions for the Flights of Fancy application. It covers how to set up the Server to run the Fancy Flights application and how to register the external application and provider with Oracle9iAS Portal.

Setting up the Server

Note: This section will update two Oracle HTTP Server configuration files jserv.properties and zone.properties. It is important to backup these files prior to making changes. jserv.properties is located at:  %ORACLE_HOME%\Apache\Jserv\conf on NT and $ORACLE_HOME/Apache/Jserv/etc on UNIX.  zone.properties is located at:%ORACLE_HOME%\Apache\Jserv\servlets on NT and $ORACLE_HOME/Apache/Jserv/etc on UNIX. This sample is required to be setup at the root zone which has a virtual path of "/servlets".

1. Stop your listener. If JPDK is not installed, install JPDK and for more information on installing the JPDK sample, please review the article Installing the PDK-Java Framework and Samples . Once JPDK is installed, verify that the provider.jar entry exists in the jserv.properties file. For example:

   wrapper.classpath=C:\jpdk\lib\provider.jar

2. In the jserv.properties file, add the following section containing the wrapper.classpath statements for the External Application. Please adjust if you have extracted to UNIX, or to different directories:

   wrapper.classpath=C:\jpdk\lib\samples.jar

3. Save and close the jserv.properties file.

4. Open the zone.properties file. In the zone.properties file add the complete path for the file 'samples.jar’ under the repositories section:

   repositories=C:\jpdk\lib\samples.jar

5. Under the Servlet Aliases section, add the alias that points to the Provider Adapter:

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

6. Under the Servlet Aliases section, add the alias that points to the Fancy Flights standalone servlet:

   servlet.flights.code=oracle.portal.sample.devguide.externalApp.ExternalServlet

7. 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 provider.xml location.

   servlet.flightsprov.initArgs=provider_root=C:\jpdk\providers\externalApp, sessiontimeout=180000

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

8. Save and close the zone.properties file.

9. Open the provider.xml file in the C:\jpdk\providers\externalApp directory. Edit the physicalRoot entry to point to your htdocs\jpdk area under the Oracle HTTP server. For example:

<!ENTITY physicalRoot "C:\iAS102\Apache\Apache\htdocs\jpdk\">

10. Save and close the provider.xml file.

Testing the Sample Deployment

You can test that you have properly setup the sample.

1. Start your listener.

2. Execute the Fancy Flights Application from the listener. This refers to the Oracle HTTP listener where you configured your sample. For example:  http://myserver.mydomain.com:port/servlets/flights

3. You should receive a Login Page for the application.

4. Execute the Fancy Flights provider from the listener. For example:

   http://myserver.mydomain.com:port/servlets/flightsprov

5. You should receive a test page informing you that the provider worked. If you did not receive the test page, verify that you can execute standard servlets using Oracle9iAS.  Then, verify all the steps within the section Setting Up the Server.

Oracle Portal Setup: Registering the External Application

You need to set up the Fancy Flights application as an External Application in the SSO Server.

1. Enter the SSO Server either through the Administer tab (on Oracle Portal Home Page), or by logging into the SSO Server directly. If you have logged into the SSO Server directly, click on SSO Server Administration.

2. Click Administer External Applications.

3. Click Add External Application.

4. Fill out the External Application Registration form.

   • External Application Login:

     1. Application Name: Fancy Flights

     2. Login URL: http:// myserver.mydomain.com:port/servlets/flights?flightAction=performlogin (replace this with your URL)

     3. User Name/ID Field Name: FlightUser

     4. Password Field Name: FlightPass

   • Authentication Method:

     1. Type of Authentication Used: POST

5. Click OK and then click Close.

Portal Setup: Registering the Provider as an External Application Provider

When you register an External Application as a provider it is almost the same as registering a regular Web provider, except that you must also associate the Provider with it's corresponding External Application Registration ID.

1. Click the ‘Administer’ tab (on Oracle Portal Home Page).

2. Click ‘Add a Portlet Provider’ in the Provider portlet.

3. Fill out the form to create a Web Provider.

   1. Name:FancyFlights

   2. Display Name: Fancy Flights

   3. Timeout:100

   4. Timeout Message: Fancy Flights Application Timed Out

   5. Implementation Style: Web

   6. Provider Login Frequency: Once per User Session   
      Do not check the checkbox 'Require session specific information'.

   7. Register on Remote Nodes: No

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

   9. Do not check the checkbox 'Web provider in same cookie domain as the portal'.

   10. Check the following radio button: The user's identity needs to be mapped to a different name in the Web provider's application.

   11. Click the Browse icon to the right of the External Application ID field. From the pop-up window, choose ‘Fancy Flights’.

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

   13. Click OK.

Portal Setup: Setting up Mapped User Information

1. Log out completely from the current Oracle Portal session.

2. Login to Oracle Portal as <portal>/<portal>.

3. Click the 'Administrator' tab.

4. In the SSO Server Administration portlet, click 'Administer External Applications'.

5. Click the External Application Name 'Fancy Flights'.

6. In the Login screen, enter a valid user/password combination for the Fancy Flights application. For example, user1/pass1

7. Click ‘OK’. Now the <portal> user is mapped to the external application user that you typed in, say user1.

EXTERNAL APPLICATION IMPLEMENTATION

The sample Flights of Fancy application is an airline flight information system giving users information about flights in which they are interested. It requires a login name and password, and shows information to the user based upon who is logged in. The flight information system is built as a stand alone Java Servlet, and then converted to run as a Oracle Portal Provider.

Security

The security system consists of a set of users, passwords, and a cookie which is set up when login is successful. This cookie is used to determine if the user is logged in or not. The cookie contains the user name, and this is used to determine who is logged in. To be truly secure, the model would be much more complex, however for this example it is not necessary, nor does it change the scenario in any way.

The table below shows the valid users, passwords, and the cookies which are created upon successful login. Since this is an example, these users, and passwords are hard coded within the code base.

 

User Name	Password	Cookie
user1	pass1	flightcookie=user1
user2	pass2	flightcookie=user2
user3	pass3	flightcookie=user3
user4	pass4	flightcookie=user4
user5	pass5	flightcookie=user5

The table below explains the security model implemented.
 

If	Then
No cookie exists for the incoming request	Display the Login Screen.
A cookie exists, but the user in the cookie is invalid	Display the Login Screen.
A cookie exists, and the user is valid	Display the requested Screen.

Conceptual Application Layout

There are 3 classes in the example code. It was designed to allow for the least amount of changes necessary to complete the provider conversion, while not making assumptions about what would be needed to do the conversion. Therefore, the screens and actions were put into one class. The login routines, and login screen are in their own class, and the Servlet code is in its own class. The idea is that by separating these objects, they could be reused during the building of the provider.

The ExternalServlet class performs the required actions for a Servlet. It receives the request from the listener, and then calls the process routine in FlightDispatch. It can handle both Post and Get requests from the browser.

The FlightDispatch class performs all of the significant work for Flights of Fancy, which includes displaying both the List screen and the Details screen, and the routing of requests. This can be thought of as the main objective of the system. Anything that is done, routes through this class. It performs the following tasks:

• List Screen display
• Detail Screen display
• Argument parsing from the servlet request
• Login object creation
• Decision making based upon the arguments received

The ApplicationLogin class handles all functions dealing with user login, or inspecting a request to determine if the user is logged in. There are two main methods in this class. This first is the Display Login method which displays the login screen. The second is the perform login routine which checks user/password validity, and creates the login cookie.

EXTERNAL APPLICATION WEB PROVIDER IMPLEMENTATION

The overall approach to the Provider conversion was to make as few changes in the application as possible, while keeping the current stand alone servlet running. Creating new screens is also undesirable, as doing so would create two code bases to maintain, therefore it was important to be able to adapt the current screens to properly perform in both the provider environment, as well as the application environment.

Conversion Steps

Display a Portlet

The first task is to create a Web provider that displays a portlet. To accomplish this remove security from the servlet, and then set the Web provider up to display the List Screen. Any non secure screen can be used to display the portlet. This scenario uses the Default Provider model of the Web provider, as this required the least amount of coding, and would lend itself well to the security model used in this application. This part could be skipped, however it is helpful to get the portlet display created first, and then the External Application.

• Create an XML file matching the proper Default Provider syntax in the JPDK. (Below is the XML needed to display the Portlet) DefaultProvider, and DefaultPortlet are provided by the JPDK, and require no coding for displaying a simple portlet. FlightRenderer is required to render a portlet.

• Build a Portlet Renderer. In this case Flight Renderer. Since Flights of Fancy handles all of its own rendering, this routine does nothing but call the FlightDispatch, and some header and footer utilities provider by the JPDK.

• Register the Web provider using the Provider Registry screens in Portal. (Refer to the section 'Portal Setup: Registering the Provider as an External Application Provider')

• Test. Once you have displayed the desired portlet, we can add the security back in, and create the External Application.

Create the External Web Application Web Provider

The final step of creating an External Application Web provider involves creating an Application provider package, and registering the External Application with Oracle Portal. To support the security model, the example application will use the username and password sent in the ExternalPrincipal object during initSession() to perform the login.

• Extend the DefaultProvider to support logging in of the application. The initSession is the method which performs login. Simply extend the DefaultProvider and rewrite the initSession to perform the proper login. Since the Login routines for the example application are held in a separate class, this class can be used to perform the real login, and thus keeping the security localized to one object. Note: This example uses two cookies. One is the original application's cookie and the other is the Jserv cookie used to maintain the servlet session. Two cookies are required for this example because the original application does not use the servlet session. Instead it uses it's own cookie.  However, the JPDK requires a servlet session so a second cookie (for the servlet session) must be created.

• Change the XML file to account for the extended DefaultProvider. This is done by changing the value of the provider tag in the XML file. For the example, the ExternalProvider will now be called instead of the DefaultProvider.

• Add a routine to the ApplicationLogin called getApplicationCookie to retrieve the cookie for the user. This method uses the external application user mapping (user/password + form field names & values) to determine if the Oracle Portal user is allowed to access this application.

• Since for each screen to be displayed, the ApplicationLogin is used to check the login, the constructor needs to be overloaded to accept the PortletRenderRequest instead of the HTTPServletRequest, and HTTPServletResponse as it was designed in the stand alone method.

• Since Portal is communicating with the External Application Web Provider, it is Oracle Portal which is managing the cookie needed by the application. To establish sessions at the browser, the browser needs to login to the application. This is done through the SSO Server. To accomplish this, all of the links in the List screen (displayed as a portlet) are wrapped with a call to the SSO Server External Application Login processing routine. The SSO Server parameter sent by the Web Provider Framework is used to render this link. It must pass the URL name, and URL value expected as part of the link. The parameterizeLink (see JPDK API documentation for PortletRendererUtil) method can be used to put this link together. The code snippet here demonstrates the use.

// mPR is the PortletRenderRequest.

///server is the External Applications URL.

   if (mIsWebProvider)

   {

     String loginURL=mPR.getLoginServerURL();

     PortletRendererUtil pru = new PortletRendererUtil();

     String str1 = pru.parameterizeLink(loginURL,"p_url_name= FlightDest");

     server.append("/servlets/flights?Flightaction=details&FlightId="+id);

     hrefValue = pru.parameterizeLink(str1,"p_url_value="+URLEncoder.encode(server.toString()));

   }

Note: p_url_name and p_url_value are required arguments of the URL used to link to the SSO Server.

• p_url_name holds the name of the destination that the external application is expecting.

• p_url_value holds the value of the destination that the external application is expecting.

FLIGHTS OF FANCY EXECUTION SCENARIOS

The following execution scenarios show the integration of the Fancy Flights application with Oracle Portal and the SSO Server. All these scenarios assume that the Web Provider has been registered in Oracle Portal with the external application ID associated with it and a page with a portlet from this provider exists.

Scenario 1 - User views a page with a portlet from an external app web provider. Username, Password mapping exists for this user.

• Login to Oracle Portal as a portal user that has a mapping stored in the SSO Server. For example <portal>/<portal>

• Create a page with a portlet from the Fancy Flights provider.

• When the user views the page, the Fancy Flights portlet is displayed with the flight information.

• The following is the process flow that is involved as depicted in the above diagram.

• Oracle Portal sees that it needs to communicate with a provider that requires a user name mapping. It calls an API that retrieves the user name, password and other credentials from the SSO Server.

• The SSO Server contains Single Sign On (SSO) user name mappings to external application user names. It provides an interface to query this mapped user information. If a mapping exists, then the SSO Server returns the user name, password and other credentials, otherwise it returns an exception that there is no current mapping for that SSO user.

• Oracle Portal then calls the provider's initSession method over HTTP, sending the mapped user name, password and other credentials for the user.

• The initSession method implementation of the provider establishes a session cookie that will be used by the Parallel Page Engine for Oracle Portal requests. The provider establishes any local session information necessary, other than the cookie. Note that the initSession is called depending on the setting of the invocation frequency.

• Oracle Portal takes the cookie that has been sent and sets it in the page metadata along with the page layout information. The page metadata has the mapped user name.

• The gateway sends the page through the Parallel Page Engine and the Parallel Page Engine invokes the portlet show method of the External Application Provider and sends along the cookie that it had previously set along with the mapped user name.

• The provider renders the portlet according to the authorization embodied in the cookie. An important point here now, is that all the links on the portlet that require authenticated access must be wrapped with a call to the SSO Server's External Application Login processing routine. The Parallel Page Engine sends along the information necessary to do this wrapping, as provided by the Portal. Basically,each link is of the format:

  "http://loginserver.domain.com/pls/ls/ls.wwsso_app_admin.fapp_process_login?p_app_id=103&p_url_name=FlightDest&p_url_value="http://myserver.com/flights/flightAction=details" 

  Here, 'p_app_id' is the application ID registered in the SSO Server, 'p_url_name' is the parameter name recognized by the External Application's Login URL as a URL that should be redirected to after a successful authentication. 'p_url_value' is the URL location that is requested.

• The portlet content is sent back to the Parallel Page Engine which constructs the completed page

• The completed page is presented to the browser. If a user clicks on any of the links wrapped in the external application Login URL, then the call will be redirected through the SSO Server to establish the provider session at the browser.

Scenario 2 - User creates a page with a portlet from an external application web provider. User name, password mapping does not exist for this user.

• Login to Oracle Portal as a different user to that of Scenario 1, for example <portal_sso>/<portal_sso>. The mapping for this user does not exist in the SSO Server.

• Since the user does not have a mapping stored, a null user name and password is sent to the Web Provider.

• The Web Provider raises an exception in that call and Oracle Portal traps the exception and sets the do_login status as a failure.

• An error message is displayed in the portlet that the user mapping is not found after checking the do_login status. A link to the SSO Server UI to create the mapping is displayed along with the error message.

Scenario 3 - User sets up Login information in the SSO Server for an external application web provider

• Login to Oracle Portal as a different user to that of Scenario 1, for example <portal_sso>/<portal_sso>. The mapping for this user does not exist in the SSO Server.

• An error message is displayed by in the portlet that the user mapping is not found. A link to the SSO Server UI to create the mapping is displayed along with the error message.

• Click the link to the Login page.

• Enter a user name and password for the external application, for example user2/pass2 and click 'OK'. Note: If an invalid user/password combination is entered, the portlet will still display the error message.

• The page with the Fancy Flights portlet is displayed with the flights information.