11 Using the Federated Portal Adapter

11.1.1 Overview

The Federated Portal Adapter is a component of OracleAS Portal that allows OracleAS 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 OracleAS 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.

11.1.2 Differences Between Database Providers and Web Providers

The biggest 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.

11.1.3 Use of the Federated Portal Adapter

The use of the Federated Portal Adapter can be divided into three categories:

11.1.4 Security Issues

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.

11.1.5 Federated Portal Adapter Related Portlet Modifications

It should be noted that database providers written before Oracle Application Server 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 customizable.

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.

Customization is an issue because the processing of customization is different between database and Web providers. For Web providers the customization form is submitted to the Parallel Page Engine of the local portal, which in turn calls the portlet again and the customizations are saved and the page is redirected appropriately. Because database providers accessed through the Federated Portal Adapter are effectively Web providers, this method of customization 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 OracleAS 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.

11.2.1 Checking the PlsqlSessionCookieName Value

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 OracleAS 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 10g can be used to update the Session Cookie Name. To do this:

1. Navigate to the Application Server Control Console.

   Typically, http://<host>.<domain.com>:1812. See Section 7.2, "Using the Application Server Control Console" for more information.

2. Navigate to the Application Server instance where you would like to add the DAD.

3. Select HTTP Server from the System Components table.

4. Click Administration.

5. Click PL/SQL Properties.

6. To edit an existing DAD, click the DAD name in the DADs section.

7. Click Document, Alias and Session in the navigation area on the left.

8. Enter a new value for Session Cookie Name in the page, and click OK.

9. Restart the Oracle HTTP Server.

You can also manually change the PlsqlSessionCookieName value in the dads.conf file. This file is located under:

ORACLE_HOME/Apache/modplsql/conf/dads.conf

A typical entry in this file looks like this:

<Location /pls/portal>
    SetHandler pls_handler
    Order allow,deny
    Allow from All
    AllowOverride None
    PlsqlDatabaseUsername portal
    PlsqlDatabasePassword SomePassword
    PlsqlDatabaseConnectString myhost.domain.com:1521:mySID
    PlsqlDefaultPage portal.home
    PlsqlAuthenticationMode SingleSignOn
    PlsqlSessionCookieName portal
    PlsqlMaxRequestsPerSession 500
    PlsqlDocumentTablename portal.wwdoc_document
    PlsqlDocumentPath docs
    PlsqlDocumentProcedure portal.wwdoc_process.process_download
    PlsqlPathAlias url
    PlsqlPathAliasProcedure portal.wwpth_api_alias.process_download
    PlsqlFetchBufferSize 128
</Location>

To edit a DAD entry, change the value of PlsqlSessionCookieName to, for example, portal2. After saving the file, update the Oracle HTTP Server configuration and restart the middle tier as follows:

MID_TIER_ORACLE_HOME/dcm/bin/dcmctl updateconfig -ct ohs
MID_TIER_ORACLE_HOME/opmn/bin/opmnctl restartproc type=ohs

11.2.2 Federated Portal Adapter User Authentication Using HMAC

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.

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.

Setting the HMAC Keys

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.

In each case, sending and receiving refer to the SOAP message.

SQL> @proadsss
Enter provider portal PL/SQL Adapter URL:
http://<portalA_hostname>:<port>/adapter/<portalA_DAD>
Enter shared key:<shared key>
exit;

SQL> @proadssr
Enter provider portal PL/SQL Adapter URL:
http://<portalB_hostname>:<port>/adapter/<portalB_DAD>
Enter shared key:<shared key>
exit;

11.2.3 Setting the Cookie Domain

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/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/pls/portalA

• http://myhost2.mycompany.co.uk:4000/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/ctxckupd.sql and broaden the scope of the domain's cookies created by OracleAS 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.

11.2.4 Sharing an OracleAS Single Sign-On and an Oracle Internet Directory Server

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, you have to update the Portal Dependency Settings File (iasconfig.xml) and run the Portal Dependency Settings Tool (ptlconfig), as shown in Example 11-2.

11.4.1 Relative Links

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

11.4.2 Customization

The way customizations work when accessing portlets through the Federated Portal Adapter is now very similar to the method used by JPDK portlets. There are two main areas of the portlet code that need to be changed to make customization 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 customize mode. If the 'p_mode' is 'OK', 'APPLY' or 'RESET', then the customizations should be saved as appropriate.

• The <FORM> HTML tags generated for the customize 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 customization form is:

  1. 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 customized. The procedure wwpro_api_adapter.open_form is supplied to make the generation of this submission as simple as possible.

  2. The PPE then shows the customization 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 customizations should be saved and then there should be a redirect to the page containing the portlets.

     'APPLY' - In this case the customizations should be saved and the customization page is shown.

     'RESET' - In this case the default values for parameters are queried and the customization page is shown.

The database services provider is a sample provider in the Oracle Application Server Portal Developer Kit (PDK) that works with the Federated Portal Adapter. For more information, see the Portal Developer Kit on Oracle Technology Network, http://www.oracle.com/technology/.