4
Using the PL/SQL HTTP Adapter

This chapter provides information about the PL/SQL HTTP Adapter and on how to use it to share portlets with other Oracle9iAS Portal instances. Specific topics in this chapter covered include:

4.1 About the PL/SQL HTTP Adapter

In this section we will describe the following:

4.1.1 Overview

The PL/SQL HTTP Adapter is a component of Oracle9iAS Portal which allows Oracle9iAS Portal instances to share their database portlets via the web portlet interface. It is a new tool that uses SOAP and HTTP to distribute database providers across database servers. The PL/SQL HTTP Adapter allows database providers to be accessed as though they were web providers.

In earlier versions 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 version 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

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 PL/SQL HTTP 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 PL/SQL HTTP 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.

4.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 PL/SQL HTTP 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' via the PL/SQL HTTP Adapter then a session will be created in 'PortalB' for 'UserA'. Typically this means that 'PortalA' and 'PortalB' would share the same as partner applications. However an alternative arrangement could be that they have separate Oracle9iAS Single Sign-On Servers but the Oracle9iAS Single Sign-On Servers share the same name server. An example could be two Oracle9iAS Single Sign-On Servers sharing the same OID instance.

4.1.3 Use of the PL/SQL HTTP Adapter

The use of the PL/SQL HTTP Adapter can be divided into three categories:

Table 4-1 Use of the PL/SQL HTTP Adapter

Parameter	Description
Oracle9iAS Portal Database Providers	Portal Database Providers created within Oracle9iAS Portal will have the necessary code to be run through the PL/SQL HTTP Adapter. This means that applications created containing forms, charts, reports etc. can be shown on any other portal instance.
Pages	Pages exposed as portlets can also be run through the PL/SQL HTTP Adapter. Regions within pages can contain portlets or items. Using the PL/SQL HTTP 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 PL/SQL HTTP Adapter as long as they are coded in accordance with the guidelines given in this chapter.

4.1.4 Security Issues

The PL/SQL HTTP Adapter creates a portal session in the remote portal based on the information passed in a SOAP message. This introduces a security issue since it may be possible to replicate these SOAP messages and create sessions for a 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 it can be decrypted by the previously shared key. Otherwise a PUBLIC session is created. Show messages do not send SOAP and are protected by the encrypted cookie, which is created by the initSession SOAP message. Using this method the PL/SQL HTTP 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 via the PL/SQL HTTP Adapter from other portal instances then security can be enhanced by configuring the listener to restrict access from machines other than the known portal instances. This is done by using the 'Allow' directive in the httpd.conf file.

4.1.5 PL/SQL HTTP Adapter related Portlet modifications

It should be noted that database providers written before Oracle9i Application Server will not work when accessed via the PL/SQL HTTP 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, i.e. 'http://host:port/images/foo.gif' rather than relative, '/images/foo.gif' when using the PL/SQL HTTP 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. Since database providers accessed via the PL/SQL HTTP Adapter are effectively web providers then 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 versions of Oracle9iAS Portal will be upgraded automatically to work with the PL/SQL HTTP Adapter. Pages exposed as providers can also be accessed via the PL/SQL HTTP Adapter.

4.2 Setting up the Environment to use the PL/SQL HTTP Adapter

To use the PL/SQL HTTP Adapter there are a few administrative steps that must be undertaken. These steps are:

4.2.1 Updating the DAD Name

All portals that are accessed via the PL/SQL HTTP Adapter must have different DAD names, and the cookie names must match the DAD names. If this is not the case, for example, if more than one portal has the default DAD name 'portal', then a new DAD entry has to be added to 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 create a new DAD entry, make a copy of an existing entry, and change the value of Location to, for example, /pls/portal2 and change the value for PlsqlSessionCookieName to portal2. The Location, or DAD name and the PlsqlSessionCookieName (the cookie name) must be the same. After saving the file, stop and restart the middle-tier using opmnctl.

After this, the Oracle9iAS Portal Configuration Assistant (OPCA) will have to be run in the MIDTIER mode. The example in Section 4.2.4, "Sharing an Oracle9iAS Single Sign-On Server and an OID Server" demonstrates how to update the DAD.

If, for example, the original schema and dad name was portal and the new dad name is portal2, the URL to access the adapter on the portal would be:

http://myApache.domain.com/adapter/portal2/portal

See also:

4.2.2 PL/SQL HTTP Adapter User Authentication using HMAC

PL/SQL HTTP 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 a shared Oracle9iAS Single Sign-On Server using the Partner Application feature, but may also be achieved with a shared name server (e.g. OID), 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.

4.2.2.1 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 the 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 wwc directory

Table 4-2 SQL Scripts for maintaining the key store

Script	Description
proadsss.sql	Sets the key at the sending end.
proadssr.sql	Sets the key at the receiving end.
proadsds.sql	Removes the key at the sending end.
proadsdr.sql	Removes the key at the receiving end.

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

Example 4-1 Setting the HMAC Keys:

In the example mentioned above, 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 (e.g. 'Portal A' exposes providers to 'Portal B' and 'Portal C') and separate keys can be set up between each of the portal instances.

4.2.3 Setting the Cookie Domain

Normally cookie domains are restricted to a single machine. This can be widened by running a script on each portal, and then checking the 'Web provider in same cookie domain as the portal ' box on provider registration. Once this is done 'deep link' functionality can be achieved.

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

Since 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 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' onto '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 wwc/ctxckupd.sql and broaden the scope of the domain's cookies created by Oracle9iAS 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.

4.2.4 Sharing an Oracle9iAS Single Sign-On Server and an OID Server

Portal session information is passed to the remote portal which uses the PL/SQL HTTP Adapter to create a session. All portals you want to create private sessions on must share the same OID server and the same Oracle9iAS Single Sign-On Server.

For example if a user 'JSMITH' displays a page on one portal and a portlet on that page is being sourced from the PL/SQL HTTP Adapter on a remote portal, then a session is created on the remote portal for user 'JSMITH'. If the two portals do not share a Oracle9iAS Single Sign-On Server then 'JSMITH' may be the username for 'John Smith' on one portal and 'Jane Smith' on the other. Typically, this is solved by sharing a Oracle9iAS Single Sign-On Server between the two portal instances (i.e. they are partner applications). If the portlets being shown are 'public' then there is no need to share the Oracle9iAS Single Sign-On Server and a public portal session will be created at the remote portal instance.

In order to set up Oracle9iAS Single Sign-On Server sharing you have to run OPCA in the MIDTIER mode as shown in the following example, which updates the DAD name to portal2, sets the SSO Server and the OID Server.

Note:

You run OPCA by invoking the ptlasst.bat, or ptlasst.csh script. Refer to Section 3.1.2, "Using OPCA in Stand-alone mode" for information on how to use OPCA in Stand-alone mode.

Example 4-2 OPCA MIDTIER mode for sharing a Single Sign-On Server

ptlasst.csh -i custom -mode MIDTIER -s portal -sp portal -c
myhost.domain.com:1521:mySID -sdad portal2 -o orasso -op orasso -odad orasso
-host myApache.domain.com -port 7777 -sso_c myhost.domain.com:1521:mySID
-sso_h myApache.domain.com -sso_p 7777 -pa orasso_pa -pap orasso_pa -ps
orasso_ps -pp orasso_ps -pd myPwdDBLink -p_tns orasso_ps -s_tns portal
-iasname myIAS -ldap_h myOID.domain.com -ldap_p 4032 -ldap_d cn=orcladmin
-ldap_w welcome1 -pwd welcome1 -verbose

See Also:

Section 3.2.2, "MIDTIER OPCA Mode"

4.3 Registering A Provider Using The PL/SQL HTTP Adapter

Registering a provider through the PL/SQL HTTP Adapter is like registering any web provider. You must perform the following steps:

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'.
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"
Check the 'Web provider in same cookie domain as the portal' check box. 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 above.
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 PL/SQL HTTP 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'.
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.

4.4 Writing Custom Portlets using The PL/SQL Http Adapter

There are two main areas of code that need special attention when writing database providers that are accessed through the PL/SQL HTTP Adapter. They are:

4.4.1 Relative Links

Any links within portlets that are accessed through the PL/SQL HTTP Adapter should absolute rather than relative. If links are relative then they will not work since 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'.

4.4.2 Customization

The way customizations work when accessing portlets through the PL/SQL HTTP 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 PL/SQL HTTP 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 (e.g. _providerid, _dad, p_action, etc.) as well as 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 re-direct 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.

4 Using the PL/SQL HTTP Adapter