Skip Headers
Oracle® Application Server Portal Configuration Guide
10g Release 2 (10.1.4)
B19305-03
  Go To Documentation Library
Home
Go To Product List
Solution Area
Go To Table Of Contents
Contents
Go To Index
Index

Previous
Previous
Next
Next
 

11 Using the Federated Portal Adapter

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 OracleAS Portal instances.

This chapter contains the following sections:

11.1 About the Federated Portal Adapter

In this section, we will describe the following:

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:

Table 11-1 Use of the Federated Portal Adapter

Category Description

OracleAS Portal Database Providers

Portal DB Providers created within OracleAS 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.


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 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 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 Setting Up the Environment to Use the Federated Portal Adapter

To use the Federated Portal Adapter there are a few administrative steps that must be undertaken. These steps are:

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 Oracle Enterprise Manager 10g Application Server Control Console.

    For details, see Section 7.2.1, "Accessing the Application Server Control Console".

  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 and OC4J_Portal.

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 process-type=HTTP_Server
MID_TIER_ORACLE_HOME/opmn/bin/opmnctl restartproc process-type=OC4J_Portal


See Also:

Section 4.5.3, "Configuring a Portal DAD" for instructions on how to configure a DAD by using Application Server Control Console


Note:

It is recommended that you edit the dads.conf file using Application Server Control Console.

If you manually edit the dads.conf file, then you must add the necessary mod_rewrite and mod_oc4j directives to the httpd.conf and mod_oc4j.conf files respectively. To do this, perform the steps mentioned in Section E.2, "DAD Configuration File (dads.conf)" using the Application Server Control Console.


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.


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.

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.

Table 11-2 SQL Scripts for Maintaining the Key Store

Script Description

proadsss.sql

Sets the key at the sending end (portal instance on which the page with the remote portlets is created).

proadssr.sql

Sets the key at the receiving end (portal instance on which the portlets are created).

proadsds.sql

Removes the key at the sending end (portal instance on which the page with the remote portlets is created).

proadsdr.sql

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

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

Example 11-2 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:

  1. Update the iasconfig.xml file and change the OIDDependency element for portal2 to point to the same OIDComponent that portal1 refers to, as shown in the following sample iasconfig.xml file:

    <IASConfig XSDVersion="1.0">
       <IASInstance Name="iAS-1" Host="abc.company.com">
          <WebCacheComponent ListenPort="3002" InvalidationPort="3003" InvalidationUsername="invalidator" InvalidationPassword="welcome1" SSLEnabled="false"/>
          <EMComponent ConsoleHTTPPort="1814" SSLEnabled="false"/>
       </IASInstance>
    
       <IASInstance Name="iAS-2" Host="xyz.company.com">
          <OIDComponent AdminPassword="welcome1" AdminDN="cn=orcladmin" SSLEnabled="false" LDAPPort="3002"/>
       </IASInstance>
    
       <PortalInstance DADLocation="/pls/portal1" SchemaUsername="portal1" SchemaPassword="welcome1" ConnectString="db1">
          <WebCacheDependency ContainerType="IASInstance" Name="iAS-1"/>
          <OIDDependency ContainerType="IASInstance" Name="iAS-2"/>
          <EMDependency ContainerType="IASInstance" Name="iAS-1"/>
       </PortalInstance>
    
       <PortalInstance DADLocation="/pls/portal2" SchemaUsername="portal2" SchemaPassword="welcome1" ConnectString="db2">
          <WebCacheDependency ContainerType="IASInstance" Name="iAS-1"/>
          <OIDDependency ContainerType="IASInstance" Name="iAS-2"/>
          <EMDependency ContainerType="IASInstance" Name="iAS-1"/>
       </PortalInstance>
    </IASConfig>
    
    

    You can remove the OIDComponent element that portal2 was earlier using, if it is not being referenced by any other PortalInstance element in the file.

  2. Run the ptlconfig tool, as shown in the following example:

    ptlconfig -dad portal2 -oid -sso
    

11.3 Registering a Provider Using the Federated Portal Adapter

Registering a provider through the Federated Portal Adapter is like registering any Web provider. You must perform the following steps:

  1. On the first page of the Register Provider screen enter the Name, Display Name, Timeout, and Timeout Message as you would normally. Make sure 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.

  2. On the second 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"

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

  4. 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 OracleAS Portal. Clicking the Browse Providers icon displays the names of all the providers.

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

11.4 Writing Custom Portlets Using the Federated Portal Adapter

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:

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 Personalization

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:

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

More on OTN

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 the Oracle Technology Network (OTN), http://www.oracle.com/technology/products/ias/portal/pdk.html.

11.5 Troubleshooting Federated Portal Adapter

There are some known restrictions showing page portlets with the Federated Portal Adapter.