Login to Oracle Portal as a portal user that has a mapping stored in the SSO Server.
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.
Oracle9iAS Portal Developer Kit
Using PDK-Java to Integrate an External Application with Oracle9iAS Portal (V2)
This document describes how you can use the PDK-Java to integrate an external application with Oracle9iAS Portal. External applications are stand alone web applications, which typically have their own concept of a user's identity. This identity does not necessarily map directly to the same user's identity in Oracle Portal, as defined by the Single Sign-On (SSO) Server. Such applications are integrated with the SSO Server as 'External Applications'. For each user, the SSO Server stores user name mappings, passwords and any other credentials required to authenticate the user in each external application. This allows Portal to hand a user over to an external application transparently, without requiring them to log in themselves.
For even tighter integration with Oracle9iAS Portal, an external application can be exposed as a web provider using the PDK-Java, so that it may be accessed from a portlet on a 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.
Related Documents
Oracle9iAS Portal Documentation
Oracle Single Sign-On Application Developer's Guide
Oracle9iAS Portal Developer Kit - Installing the PDK-Java Framework and Samples
THE FLIGHTS OF FANCY APPLICATION
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/externalApp. The files are:
FlightDispatch.java: This class contains the methods for displaying the "Flights of Fancy" application screens.
ApplicationLogin.java: This class handles all functions dealing with user login, e.g. inspecting a request to determine whether the user is logged in.
ExternalServlet.java: This is the servlet entry point to the applicaton, which allows it to function as a stand alone web application.
ExternalProvider.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.
Installation
This section contains instructions for installing the Flights of Fancy sample external 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.
Step 1: Installing and Testing PDK-Java
If the PDK-Java is not installed, please follow the article Installing the PDK-Java Framework and Samples.
Make sure OC4J is running.
In a browser, test that the stand alone version of the application is working, through the following URL:
You should see a login page for the application.
In a browser, test that the web provider version of the application is working, through the following URL:
You should see a web provider test page that mentions a single portlet called FlightPortlet
Step 2: Registering the External Application on the SSO Server
Log into Oracle Portal as an SSO Administrator.
Click on the Administer tab
To add a new External Application, click on Administer External Applications link in the SSO Server Administration portlet, then click Add External Application.
In the External Application Login section, enter values for the following fields (where <host> and <port> are the domain name and port number of the listener on which PDK-Java is installed). Note that all values are case sensitive.
Select POST as the Authentication Method.
Click OK.
In the Edit/Delete External Application section, click on the name of the flights application you just registered. This will cause the SSO server to try to log you into the external application for the first time.
A login screen will apear. Enter the following:
Make sure the following checkbox is checked:
Remember My Login Information For This Application
You should now see a screen of flight information generated by the Flights of Fancy application. The SSO Server has logged you in, and will remember this user name and password for the current portal user, so that they can be logged in automatically in subsequent sesssions.
Step 3: Registering the External 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:
Make sure the following radio button is selected:
The user's identity needs to be mapped to a different name in the Web provider's application, and/or the Web provider requires an external application login for establishment of a browser session.
For External Application ID, Select the flights application you registered with the SSO server in Step 2.
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 through the SSO server. Because the SSO server should already have login details for your portal user, it will log you in transparently, and you should see full-screen flight details in your browser.
EXTERNAL APPLICATION 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.
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 initSession() is called depending on the setting of the login 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/jpdk/servlet/ExternalAppFlights?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 the SSO user. 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 the SSO user. 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.
IMPLEMENTATION
This section takes a look at how the Flights of Fancy application is implemented and how it internally handles the above execution scenarios.
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 taken when exposing the application as a web provider was to make as few changes to the application as possible, and to make sure the application still ran as a stand alone servlet. Creating new screens was 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. The following subsections examine this conversion process in more detail.
Displaying 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. Once you have displayed the desired portlet, you can add the security back in, and create the External Application.
In this case, the task was simple. Since Flights of Fancy handles all of its own rendering, the portlet renderer, FlightRenderer, does nothing more than call FlightDispatch, and some header and footer utilities provided by the PDK-Java.
Creating 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 ProviderInstance to support logging in of the application. initSession() is the method which performs logging in. Simply extend ProviderInstance and rewrite 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 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 PDK-Java requires a servlet session so a second cookie (for the servlet session) must be created.
Change the XML file to account for the extended ProviderInstance. This is done by changing the value of the providerInstanceClass tag in the XML file. For this example, the ExternalProvider will now be called instead of ProviderInstance.
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 API documentation for PortletRendererUtil)
method can be used to put this link together. The code snippet here demonstrates the use.
// pr is the PortletRenderRequest.
///server is the External Applications URL.
if (pr != null)
{
String loginURL=pr.getRenderContext().getLoginServerURL();
String str1 = PortletRendererUtil.parameterizeLink(loginURL,
"p_url_name=" + FLIGHTDEST);
hrefValue = PortletRendererUtil.parameterizeLink(str1,
"p_url_value=" +
PortletRendererUtil.encodeParameter(server.toString(), pr));
}
|
Revision History:
January 18, 2002. First V2 revision.