This chapter provides information about the Federated Portal Adapter, previously known as the "PL/SQL HTTP Adapter". It describes how it can be used to share portlets with other Oracle Portal instances.
This chapter contains the following sections:
In this section, we will describe the following:
The Federated Portal Adapter is a component of Oracle Portal that allows Oracle Portal instances to share their database portlets through the Web portlet interface. It is a tool that uses SOAP and HTTP to distribute database providers across database servers. The Federated Portal Adapter allows database providers to be accessed as though they were Web providers.
In earlier releases of Oracle Portal, all database providers accessed from a portal instance had to be on the same physical database server that contained the portal instance.
In Oracle Portal release 3.0.9, it was possible to distribute database portlets across database servers. To do this the user had to register each portal 'node' with each other which created a database link between the 'nodes'. These portal nodes would not function beyond a firewall. Furthermore the registration of the portal nodes was symmetric, which made the registration of multiple nodes hard to manage
Oracle Portal already had the concept of Web providers where the communication between the portal and the provider is done with the open protocols HTTP and SOAP. The PDK-Java services allow users to easily develop providers in Java that receive SOAP messages and respond accordingly.
The Federated Portal Adapter is a module written in the portal instance (in both Java & PL/SQL) that receives the SOAP messages for a Web provider, parses the SOAP and then dispatches the messages to a database provider as PL/SQL procedure calls. In effect, the Federated Portal Adapter makes a database provider behave exactly the same way as a Web provider. This allows users to distribute their database providers across database servers. All remote providers can now be treated as Web providers, hiding their implementation from the user and effectively replacing the distributed portal installations.
A significant difference between database providers and Web providers is that typically database providers use a portal session within the code, so that as part of the Federated Portal Adapter a portal session is created on the remote portal instance. The SOAP messages were extended to contain enough information to create a session on the remote portal instance, which means that the user in the remote portal must be the same user as in the local portal. For example, if 'UserA' is running in 'PortalA' and is using a provider on 'PortalB' through the Federated Portal Adapter then a session will be created in 'PortalB' for 'UserA'. Typically this means that 'PortalA' and 'PortalB' would share the same Oracle Application Server Single Sign-On, as partner applications. However an alternative arrangement could be that they have separate OracleAS Single Sign-Ons but the OracleAS Single Sign-Ons share the same name server. An example could be two OracleAS Single Sign-Ons sharing the same Oracle Internet Directory instance.
The use of the Federated Portal Adapter can be divided into three categories:
Table 12-1 Use of the Federated Portal Adapter
| Category | Description |
|---|---|
|
Oracle Portal Database Providers |
Portal DB Providers created within Oracle Portal will have the necessary code to be run through the Federated Portal Adapter. This means that applications created containing forms, charts, reports, and so on, can be shown on any other portal instance. |
|
Pages |
Pages exposed as portlets can also be run through the Federated Portal Adapter. Regions within pages can contain portlets or items. Using the Federated Portal Adapter these can now be accessed from any portal instance. |
|
User Created Providers |
Users may wish to create their own PL/SQL providers. You will be able to expose these providers through the Federated Portal Adapter as long as they are coded in accordance with the guidelines given in this chapter. |
The Federated Portal Adapter creates a portal session in the remote portal based on the information passed in an initSession SOAP message. This introduces a security issue because it may be possible to replicate these SOAP messages and create sessions for any user on a portal and then access the portal as that user. To avoid this, an encryption key is shared between the two portals and part of the SOAP message is encrypted using that key. The requested private portal session can only be created if the previously shared key can decrypt it. Otherwise a PUBLIC session is created. The request to display a portlet is made with a Show message that is protected by the encrypted cookie which is created by the initSession SOAP message. The use of an encryption key means that the Federated Portal Adapter can safely trust the incoming SOAP message and create portal sessions in the portal instance without opening the portal to hackers.
If it is known that the portal instance will only be accessed through the Federated Portal Adapter from other portal instances, then security can be enhanced by configuring the listener to restrict access from computers other than the known portal instances. This is done by using the 'Allow' directive in the httpd.conf file.
It should be noted that database providers written before Oracle Fusion Middleware 10g (10.1.4) will not work when accessed through the Federated Portal Adapter if one of the following conditions is true:
The portlet contains relative links
The portlet is personalizable
All links within a portlet should be absolute links, that is, http://<host>:<port>/images/foo.gif rather than relative, /images/foo.gif when using the Federated Portal Adapter. This is because the request is processed by the Parallel Page Engine on the local portal instance. Relative links will therefore be interpreted as relative to the local portal and not to the portal containing the portlet.
Personalization is an issue because the processing of personalization is different between database and Web providers. For Web providers the personalization form is submitted to the Parallel Page Engine of the local portal, which in turn calls the portlet again and the personalizations are saved and the page is redirected appropriately. Because database providers accessed through the Federated Portal Adapter are effectively Web providers, this method of personalization should be undertaken for these providers. A public API is provided (WWPRO_API_ADAPTER) to do this.
Portal Database Portlet Providers developed in previous releases of Oracle Portal will be upgraded automatically to work with the Federated Portal Adapter. Pages exposed as providers can also be accessed through the Federated Portal Adapter.
To use the Federated Portal Adapter there are a few administrative steps that must be undertaken. These steps are:
DADs must have a unique PlsqlSessionCookieName value for all the portals accessed by the Federated Portal Adapter.
For example,
portal1 can have the schema name portal, the DAD name portal and the PlsqlSessionCookieName value portal1.
portal2 can have the schema name portal, the DAD name portal, but must have a different PlsqlSessionCookieName value, like portal2.
|
Note: In previous releases of Oracle Portal, the DAD name had to be the same as the schema name, and the DAD name was always the same as the name of the session cookie created. This is no longer the case. You can now specify the name of the cookie created when portal is accessed by the DAD, and the schema name does not have to be the same as the DAD name. |
Oracle Enterprise Manager 11g Fusion Middleware Control can be used to update the Session Cookie Name. To do this:
Navigate to the Portal Home page in the Oracle Enterprise Manager 11g Fusion Middleware Control.
For details, see Section 8.1, "Using Oracle Enterprise Manager 11g Fusion Middleware Control".
From the Portal menu, select Settings, and then Database Access Descriptor.
The Configure Database Access Descriptor page is displayed.
To edit an existing DAD, select the DAD name and click Edit.
The Edit Database Access Descriptor page is displayed.
In the Edit Database Access Descriptor page, under Security, Document, Alias and Session section enter a new value for Session Cookie Name.
Click OK.
Restart the managed server (WLS_PORTAL).
Federated Portal Adapter functionality will support the registering of remote Database providers between geographically dispersed portals. Database providers are registered as if they were Web providers residing at a special URL on the remote portal.
|
Note: If you are only rendering public content in the remote portlets, you can ignore this section. |
In order that more than just public content can be rendered in the remote portlets we require that in some way we can guarantee that user A on one portal is the same as user A on another portal. This will typically be achieved by using a shared Oracle Application Server Single Sign-On using the partner application feature, but may also be achieved with a shared name server (for example, Oracle Internet Directory), synchronized name servers or a manual process.
If this environment can be achieved, then using the Hash Message Authentication Code (HMAC) authentication mechanism, private sessions can be initiated on a remote portal to render private content of remote portlets.
If the administrator of portal A wishes to permit users of portal B to create private sessions on portal A, a private 'key' will have to be stored on each portal. This key is used to encode and decode portions of each SOAP request sent between them. If a key is missing or they are different on each portal, only PUBLIC sessions will be created.
A key must be at least 10 characters long, and one administrator should inform the other administrator of its value in a suitably secure way.
SQL scripts are provided to perform the task of maintaining the key store - all are found in the ORACLE_HOME\portal\admin\plsql\wwc directory.
Table 12-2 SQL Scripts for Maintaining the Key Store
| Script | Description |
|---|---|
|
|
Sets the key at the sending end (portal instance on which the page with the remote portlets is created). |
|
|
Sets the key at the receiving end (portal instance on which the portlets are created). |
|
|
Removes the key at the sending end (portal instance on which the page with the remote portlets is created). |
|
|
Removes the key at the receiving end (portal instance on which the portlets are created). |
In each case, sending and receiving refer to the SOAP message.
Example 12-1 Setting the HMAC Keys:
In the example mentioned earlier, portal B is the sender (sending SOAP and show requests) and portal A is the receiver of those requests. The portal administrator of portal B must connect to SQL*Plus as the portal owner and run:
SQL> @proadsss Enter provider portal PL/SQL Adapter URL: http://<portalA_hostname>:<port>/adapter/<portalA_DAD> Enter shared key:<shared key> exit;
The portal administrator of portal A must connect to SQL*Plus as the portal owner and run:
SQL> @proadssr Enter provider portal PL/SQL Adapter URL: http://<portalB_hostname>:<port>/adapter/<portalB_DAD> Enter shared key:<shared key> exit;
If sharing of providers is required both ways, then this will need to be repeated the other way round, possibly with different shared keys. It should also be noted that a portal can expose its providers to several other portal instances (for example, 'Portal A' exposes providers to 'Portal B' and 'Portal C') and separate keys can be set up between each of the portal instances.
Normally cookie domains are restricted to a single computer. This can be widened by running a script on each portal, and then selecting the Web provider in same cookie domain as the portal option on provider registration. Once this is done, 'deep link' functionality can be achieved. This means that when you click a link in a portlet rendered by the Federated Portal Adapter, the browser renders the referred page (typically from the remote portal). The session context that has already been established is also maintained.
Cookies received by a browser, or other HTTP client, are sent to servers if the domain of the cookie matches the server's host name. So cookies with the domain '.co.uk' and 'mycompany.co.uk' will be sent with a request to 'http://mycompany.co.uk/portal/pls/etc/etc'. By default the scope of cookies created by portal is restricted to the host name of the middle-tier computer.
Because communication to the portlets is done in the middle tier by the Parallel Page Engine (PPE) and not the browser, the session cookie for the remote portal will, by default, not be sent to the remote portal when links are followed within the portlet.
This can be solved by widening the scope of the cookies created by portal and making sure that the cookies received by the PPE are sent back to the browser. Widening the scope of the cookies created by portal is achieved by running the SQL script ctxckupd.sql in the ORACLE_HOME\portal\admin\plsql\wwc directory.
For example, there are two portals:
http://myhost1.mycompany.co.uk:3000/portal/pls/portalA
http://myhost2.mycompany.co.uk:4000/portal/pls/portalB
and a provider is registered from 'Portal B' on 'Portal A'.
When showing a page on 'Portal A' that contained a portlet from 'Portal B' by default a portal session cookie for 'Portal B' whose domain is 'myhost2.mycompany.co.uk:4000' would be created, and sent to the PPE. If the 'Web provider in same cookie domain as the portal' property is checked on the provider registration page then this cookie will be sent back to the browser, but the domain of the cookie will then be 'myhost1.mycompany.co.uk:3000' because that is where it is being sent from, because the PPE is at 'myhost1.mycompany.co.uk:3000').
If a link is followed from within the portlet the cookie is not sent with the request, because the domain of the cookie does not match with that of the host of the request.
To solve this, connect to SQL*Plus as the portal owner of each portal and run ORACLE_HOME\portal\admin\plsql\wwc and broaden the scope of the domain's cookies created by Oracle Portal so each portal is in the same domain. Once this is done, the scope of the cookie domains created by any of the portals will be broad enough to be sent back to the browser. Links within the portlet will then work correctly.
|
Note: Having only one dot in the host.domain name of the middle-tier server is not an Oracle tested configuration. To avoid unexpected results, configure the middle tier servers with a multiple part domain name. This will provide more than one dot in the host.domain name of the middle tier. |
The benefits of single sign-on can be maximized, by utilizing a common Identity Management server. portal session information is passed to the remote portal, which uses the Federated Portal Adapter to create a session. It is recommended that all portals on which you want to create private sessions, share the same Oracle Internet Directory server and the same OracleAS Single Sign-On.
For example, if a user 'JSMITH' displays a page on one portal and a portlet on that page is being sourced from the Federated Portal Adapter on a remote portal, then a session is created on the remote portal for user 'JSMITH'. If the two portals do not share OracleAS Single Sign-On then 'JSMITH' may be the user name for 'John Smith' on one portal and 'Jane Smith' on the other. To avoid this sort of problem, ensure that all the portals participating in the Federated Portal are configured to use a single Oracle Identity Management. They should all use the same OracleAS Single Sign-On for authentication. However, if the portlets being shown are 'public' then there is no need to share the OracleAS Single Sign-On and a public portal session will be created at the remote portal instance.
If you currently have two portals using distinct OracleAS Single Sign-On servers, you may first need to consolidate the OracleAS Single Sign-On servers. To do this, refer to the information on consolidating multiple servers in the Oracle Application Server Single Sign-On Administrator's Guide.
Consolidating the servers means that you will be decommissioning one of the servers and identifying the other as the common server for both portals to use. Then you'll need to configure the portal that was configured to use the decommissioned OracleAS Single Sign-On to the consolidated one. To do this, do the following:
Sharing an OracleAS Single Sign-On and an Oracle Internet Directory Server
You have two portals, portal1 and portal2. You decide to decommission the SSO server for portal2 and configure portal2 to use the SSO server for portal1. To do this, perform the following steps:
Change the OIDDependency element for portal2 to point to the same OIDComponent that portal1 by performing the following steps:
Navigate to the Portal Home page in the Oracle Enterprise Manager 11g.
From the Portal menu, select Settings, and then Wire Configuration.
The Portal Wire Configuration page is displayed.
Enter the OID details for portal1 under Oracle Internet Directory (OID) section.
Re-register the Oracle HTTP Server for portal2, by invoking ssoreg.sh located in ORACLE_HOME/sso/bin (Unix) from your Identity Management instance as shown in the following example:
$ORACLE_HOME/sso/bin/ssoreg.sh -site_name portal2.example.com:8090 -config_mod_osso TRUE -mod_osso_url http://portal2.example.com:8090 -update_mode MODIFY -remote_midtier -config_file config_file_path
On Windows, you must run ssoreg.bat instead.
Update the Portal Metadata Repository for portal2 by logging into the Portal schema and update the GUID column of the WWSEC_PERSON$ table to set a placeholder GUID so that it will pick up the new GUIDs from the newly associated OID server:
SQL> update wwsec_person$ set guid = ':'||id; SQL> commit;
Registering a provider through the Federated Portal Adapter is like registering any Web provider. You must perform the following steps:
Log in to your Oracle Portal.
The Portal Builder page is displayed.
Click the Administer tab and then the Portlets subtab.
Click Register a Provider in the Remote Providers portlet.
In the Provider Information page, enter the Name, Display Name, Timeout, and Timeout Message as you would normally. Ensure that the Implementation Style is set to Web. Although the provider is actually written in PL/SQL, all communication to it is as a Web provider and not a database provider so it is important to set the Implementation Style to Web.
In the General Properties page enter the URL of the adapter service. The syntax for the URL should be:
http://host:port/adapter/dad/schema
If the DAD and the schema are the same you can just use:
http://host:port/adapter/dad
where the host, port, DAD and schema locate the remote portal instance. You can verify that this is the correct URL by pasting it into a browser.
If the URL is correct you should get to a page with the message "Congratulations - you got to the adapter test page"
Select the Web provider in same cookie domain as the portal option. This will ensure that cookies generated from the provider will be sent back to the browser. Note that it may be necessary to broaden the scope of the cookies created by portal as described earlier.
Enter the 'Service Id'. This should be in the form 'urn:<provider name>'. Where provider name is the name of the provider on the remote portal instance, this is case sensitive and will be upper case. This is the information that the Federated Portal Adapter uses to locate the specific provider at the remote portal.
Note that for page groups exposed as providers, the name of the provider will be something like 'MYPAGE970D272EBE9D2D0FE034080020F7DA4B' it is important that you specify this 'Name' rather than the 'Display Name'. The name and display name can be accessed from the Remote Providers portlet, available in the Portlets subtab under the Administer tab in Oracle Portal. Clicking the Browse Providers icon displays the names of all the providers.
In the User/Session Information section, select the User radio button and set the Login Frequency to be Once Per User Session. These settings make sure that information is sent with the request to allow a portal session to be created on the remote portal instance.
|
Note: When you create or register a new provider, a page is created in the Portlet Repository under Portlet Staging Area to display portlets for that provider. This page is not visible to all logged in users. It is only visible to the user who published the provider, and the portal administrator. The publisher or portal administrator can change the provider page properties to grant privileges to appropriate users and groups, as required. |
There are two main areas of code that need special attention when writing database providers that are accessed through the Federated Portal Adapter. They are:
Any links within portlets that are accessed through the Federated Portal Adapter should absolute rather than relative. If links are relative then they will not work because they will be relative to the local middle tier rather than the remote middle tier. For example, links should be of the form 'http://myhost.mycompany/etc/etc' rather than '/etc/etc'.
The way personalizations work when accessing portlets through the Federated Portal Adapter is now very similar to the method used by PDK-Java portlets. There are two main areas of the portlet code that need to be changed to make personalization work through the Federated Portal Adapter:
The show call of the portlet needs additional logic to show the portlet in edit_defaults mode, or, if the parameter 'p_mode' is null, in personalize mode. If the 'p_mode' is 'OK', 'APPLY' or 'RESET', then the personalizations should be saved as appropriate.
The <FORM> HTML tags generated for the personalize page should be created using the procedure wwpro_api_adapter.open_form. This will ensure that the action for the form is correct, and that the correct parameters are passed upon page submission. The sequence of events when submitting the personalization form is:
The page submits to the 'local' PPE. There are several standard parameters that need to be sent with this submission (for example, _providerid, _dad, p_action, and so on) and the parameters that are being personalized. The procedure wwpro_api_adapter.open_form is supplied to make the generation of this submission as simple as possible.
The PPE then shows the personalization page again. However the 'p_action' parameter will now be set so that during the show_portlet call of the portlet it will be one of the following settings:
'OK' - In this case the personalizations should be saved and then there should be a redirect to the page containing the portlets.
'APPLY' - In this case the personalizations should be saved and the personalization page is shown.
'RESET' - In this case the default values for parameters are queried and the personalization page is shown.
The database services provider is a sample provider in the Oracle Fusion Middleware Portal Developer Kit (PDK) that works with the Federated Portal Adapter. For more information, see the Portal Developer Kit on the Oracle Technology Network (OTN), http://www.oracle.com/technology/products/ias/portal/pdk.html.
There are some known restrictions showing page portlets with the Federated Portal Adapter.
The Show Details mode does not work, that is, the portlet name cannot be displayed as a link that shows additional information about the portlet.
If the page portlet contains tabs, then clicking a tab is a 'deep link' and the rendered page takes over the whole page, that is, it is not shown within the original page as a portlet.
The rendering of navigation pages, which includes the page banner, does not work properly when pages are displayed through the Federated Portal Adapter. For example, the Personalize link in a regular page portlet displays personalization options for the container page, but this is not the case in a remote page portlet. Also, page portlets shown through the Federated Portal Adapter do not display the banner of the container page, whereas the banner is displayed in the case of regular page portlets.
If the page portlet has a navigation page portlet that has a sub page region in it, the sub page region will not be displayed on the page portlet when it gets rendered through the Federated Portal Adapter. For a non-remote page portlet, the region shows the sub pages of the container page holding the portlet.
When you export and import Federated Portal Adapter portlets, the portlets are not shown on the target instance if you have not performed the following tasks on the target portal instance:
Configure the target portal instance to use the PL/SQL adapter running on the source portal instance.
Grant the View permission to the target portal instance for the Federated Portal Adapter Web Provider page in the source portal instance.