4
Distributed Oracle Portal Installations

In a distributed Oracle Portal configuration, there is a centralized Login Server, and two or more Oracle Portal nodes which all access the same Login Server for Single Sign-On authentication. Furthermore, each Portal node is on a separate database instance.

There are many benefits to such an environment, including the ability to share portlet provider information across all nodes as well as increased scalability, availability, and system throughput.

Specific topics covered include:

• What is a Node?

• Benefits of a Distributed Oracle Portal Environment

• Node Requirements

• Configuring a Distributed Oracle Portal Environment

See also: The following White Papers on the Oracle Technology Network (OTN): "Building Scalable and Performant Portal Solutions Using Oracle Portal" "Page Generation and Assembly Scalability in Oracle9iAS Portal" http://technet.oracle.com/products/iportal/listing.htm

The following diagram illustrates a distributed Oracle Portal environment showing the communication channels that exist between the nodes themselves, between each of the nodes and the Oracle HTTP Server powered by Apache, with the Login Server.

Figure 4-1 Distributed Oracle Portal installations topology

Text description of the illustration disti_2_.gif

4.1 What is a Node?

A distributed environment refers to several installations of Oracle Portal to create a multi-node environment. Each node is a complete Oracle Portal installation which resides in a separate database instance and is configured to operate in a distributed manner. Each node in the system may operate either independently of the other nodes or in conjunction with the other nodes.

The node containing the page that you are currently viewing is considered the local node. All other installations are considered remote nodes. However, a page in Oracle Portal can contain portlets that were created on either the local or remote nodes.

Node registration refers to associating nodes to each other so that they may be able to share information. Node registration is done by completing a set of configuration steps which are discussed later in this chapter.

4.2 Benefits of a Distributed Oracle Portal Environment

A distributed or multi-node Oracle Portal environment provides the following benefits over a single node environment.

4.2.1 Portlet Provider Information Shared Across Nodes

In a distributed Oracle Portal environment, provider information can be shared across nodes. During node registration, provider registration also occurs. When a provider is registered on a remote node, the portlets for that provider are populated in the node's portlet repository which allows you to build pages with portlets residing on remote nodes. In addition to sharing provider information, the distributed environment also lets you group providers accordingly.

4.2.2 Scalable Solutions

When provider registration occurs, the provider registry information is replicated on the remote node. Only the provider registry information is replicated, not the actual provider implementation. The provider implementation package resides only on the host node of that provider.

A page may consist of portlets from any number of nodes that participate in the distributed environment. When such a page is rendered, the portlets are executed on the host node of each of the portlet providers (the node where the provider implementation package reside).

For example, consider the following scenario which can be implemented in scalable environments:

A page consists of portlet 1 which resides on node a and portlet 2 which resides on node b. When the page is rendered, portlet 1 is executed on node a and portlet 2 is executed on node b.

Figure 4-2 Displaying portlets created on different nodes on a single page

Text description of the illustration disti_1_.gif

Such a scenario enables you to access multiple machines with increased performance and increased system throughput since the rendering of a page is distributed among several database instances. The execution of the portlets on the different databases is done in parallel.

The distributed environment provides high availability. If one node fails, the other nodes continue to process with full access except on portlets residing on the failed node.

4.3 Node Requirements

You must meet the following node requirements for configuring a distributed Oracle Portal architecture:

• Common Cookie Domain

• Oracle HTTP Server powered by Apache Configuration

• Common Cookie Name

• Common Login Server

• Symmetric Node Registration

• URLs in Portlets

4.3.1 Common Cookie Domain

The cookie domain for the Oracle Portal session cookie must be common for all nodes that participate in the distributed Oracle Portal environment. If the cookie domain is changed on one node, it must be changed on all other nodes. Otherwise, the Oracle Portal nodes in your environment fail in a distributed manner.

Cookies are scoped to the host which created them, unless they are specified to be scoped to a larger domain. By default, the Oracle Portal session cookies are scoped to the root path of the server that generated them. For more information, see "Login Server Configuration Table".

See: Section 4.4.1, "Step 1: Create Oracle Portal Nodes"

4.3.2 Oracle HTTP Server powered by Apache Configuration

A Portlet Provider that resides on a node may be accessed by any other node that exists in the network and for which a communication path has been established. The Oracle HTTP server powered by Apache is responsible for establishing a communication path and for displaying portlets for each node.

Choose either of the following scenarios in your distributed environment:

• Have multiple Oracle HTTP Servers powered by Apache running, one for each node

• Have a single Oracle HTTP Server powered by Apache running and accessible by all nodes

When communicating between browsers, the Oracle Portal session cookie is sent to each portlet execution request. Also, the cookie domain consists of the <host.domain:port>.

When using multiple Oracle HTTP Servers, this results in a different <host.domain:port>. Only one node has the same cookie domain as the Login Server. Thus, in this case, when the user tries to access a node by clicking a portlet's URL, the Oracle Portal session cookie is not sent by the browser.

To resolve this situation, a common cookie domain name is required. To do this, run the ctxckupd.sql script on all nodes in your distributed environment.

See: Section 4.4.2, "Step 2: Create Same Cookie Domain"

4.3.3 Common Cookie Name

In an Oracle Portal distributed environment, each Oracle HTTP Server powered by Apache must have a Database Access Descriptor (DAD) configuration for each of the portal nodes that participate in the distributed system. Also, the Session Cookie Name field in the DAD configuration must be the same across nodes.

See: Section 4.4.3, "Step 3: Edit Oracle Portal DADs"

4.3.4 Common Login Server

All the nodes that participate in the distributed Oracle Portal environment must use the same Login Server. Otherwise, you may encounter a runtime error if a node that is registered to participate in the distributed Oracle Portal environment is not using the same Login Server as the other nodes. In this case, you would fail to log onto the Oracle Portal node via Single Sign-On (SSO) and not have access to the portlets on that node.

See: Section 4.4.4, "Step 4: Associate Nodes with the Same Login Server"

4.3.5 Symmetric Node Registration

All nodes included in the distributed architecture must be symmetrically registered between themselves. For example, if the distributed Oracle Portal environment consists of three nodes (a, b, and c), make sure that the following registrations exist.

• Node a is registered on b and c

• Node b is registered on a and c

• Node c is registered on a and b

See: Section 4.4.7, "Step 7: Register Nodes Between Themselves"

4.3.6 URLs in Portlets

If you are creating your own custom portlets using the Oracle Portal Development Kit (PDK), use absolute URLs (not relative URLs) for portlets destined to be run in a distributed Oracle Portal environment.

See: The Oracle Portal Development Kit on the Oracle Technology Network at: http://technet.oracle.com/products/iportal/ Click the Portal Development Kit (PDK) link to access the latest PDK software and documentation.

4.4 Configuring a Distributed Oracle Portal Environment

You must have the required privileges on the node and on the Login Server to perform the steps in this section:

• Full Administrator privileges on the Login Server to change any of its settings.

• Oracle Portal Administrator privileges to access the Administer tab on the Oracle Portal home page.

See: The Oracle Portal Online Help Content Area Help topics: What is the Login Server and Single Sign-On? How does security work?

This section describes the process for setting up a distributed Oracle Portal environment. For the purpose of the following example, the environment consists of two nodes, named node a and node b.

The steps include the following:

• Step 1: Create Oracle Portal Nodes

• Step 2: Create Same Cookie Domain

• Step 3: Edit Oracle Portal DADs

• Step 4: Associate Nodes with the Same Login Server

• Step 5: Create a User on the Login Server with Administrator Privileges

• Step 6: Discover the Name of Each Node

• Step 7: Register Nodes Between Themselves

• Step 8: Refresh the Portlet Repository for Each Node

• Step 9: Create Additional Nodes

4.4.1 Step 1: Create Oracle Portal Nodes

As stated earlier, a node is an Oracle Portal installation. To configure a distributed Oracle Portal environment, you must have at least two Oracle Portal installations, one for node a and the other for node b.

To create a node, install Oracle Portal as instructed in the "Oracle9i Application Server Installation Guide" for your particular operating system.

After creating the first node, additional nodes can be created without associated Login Server schemas. The -nosso parameter creates only an Oracle Portal schema. For more information, see "Manually Installing Oracle Portal with the winstall Script".

You must perform an installation of Oracle Portal for each node you want to have in your distributed environment.

Note: Be sure that the two nodes are created on two different databases since the distributed Oracle Portal functionality is not supported on nodes that exist on the same database.

4.4.2 Step 2: Create Same Cookie Domain

Note: This step applies only if your distributed Oracle Portal environment is running multiple Oracle HTTP Servers powered by Apache. If you are running only one Oracle HTTP Server, skip this step.

To resolve the issue of a different <host.domain:port> configuration for each node, the same cookie domain must exist across nodes in a distributed Oracle Portal environment in order for the Oracle Portal session cookie to be sent successfully by the browser. The solution is to run the ctxckupd.sql script on all the nodes in your distributed Oracle Portal environment.

To create the same cookie domain on all nodes:

1. If you have an Oracle HTTP Server powered by Apache running on the computer on which your node is located, stop the server by entering the following command from a command prompt:

   <ORACLE_HOME>/Apache/Apache/bin/apachectl stop 
   
   
   
   
   
   
   
   Note:
   
   
   
   On Windows NT/2000, stop the HTTP Server from the System Control Panel as instructed. 
   
   
   
   
   
   
   
   
   
   

2. On the database where your node is installed, log on to SQL*Plus with the appropriate username and password. For example:

         sqlplus nodea/nodea
   
   

3. Enter the following command:

   @ctxckupd.sql
   
   

4. When prompted, enter the domain name for the session cookie as required.

   Note: Note this name as you need to enter the same cookie domain name for all remote nodes.

5. Repeat the above steps for all other remote nodes in your distributed Oracle Portal environment.

See: "Modifying the Scope of the Portal Session Cookie"

4.4.3 Step 3: Edit Oracle Portal DADs

A distributed Oracle Portal environment requires that each node has a separate Database Access Descriptor (DAD) for each Oracle HTTP Server powered by Apache. Also, the Session Cookie Name field in the DAD configuration must be the same across nodes.

Upon installation, a DAD is created for each node. This step requires you to edit the DAD on each node and specify a common cookie name across nodes.

Note: In a distributed Oracle Portal environment, make sure there is only one installation of the Login Server.

4.4.3.1 Access DAD Configuration Page

DADs are created from the Database Access Descriptor configuration page in Oracle Portal which you can access in the following ways:

• In the Services portlet, click Listener Gateway Settings. By default, the Services portlet is located on the Oracle Portal home page's Administer tab.
  1. Click Gateway Database Access Descriptor Settings.

  2. In the Edit/Delete Database Access Descriptors section, click
     Text description of the illustration pobreg.gif next to the node's DAD entry. The DAD configuration page is displayed.

• In your browser, enter the following:
  1. http://<hostname.domain>:<port>/pls/admin_/dadentries.htm

  2. In the Edit/Delete Database Access Descriptors section, click
     Text description of the illustration pobreg.gif next to the node's DAD entry. The DAD configuration page is displayed.

4.4.3.2 Configuration

To provide the same cookie name for Oracle Portal nodes in your distributed environment:

1. From the appropriate node's Database Access Descriptor configuration page, edit the DAD for node a.

   In the Session Cookie Name field, enter a name.

   Example:

   dist_portal_session_cookie

2. From the appropriate node's Database Access Descriptor configuration page, edit the DAD for node a.
   1. In the Session Cookie Name field, enter the same cookie name you entered for node b.

Example

dist_portal_session_cookie

Note: It is important that the Session Cookie is the same for both (all) DADs in your distributed environment, except for the Login Server. The cookie is used by the Oracle Portal security subsystem to perform session establishment and authentication during Single Sign-on.

3. From the Login Server's Database Access Descriptor configuration page, edit the DAD for the Login Server of node a. A Login Server DAD is appended with _SSO in its name.

   In the Session Cookie Name field, enter a cookie name that is different from the name given for node a and node b.

Example:

dist_portal_sso_session_cookie

Note: It is important to use a different name for the Session Cookie because the Login Server uses its own cookie. If the same name was used as that of Oracle Portal, the Oracle Portal session cookie would be overwritten by the Login Server resulting in Oracle Portal authentication failures.

4.4.4 Step 4: Associate Nodes with the Same Login Server

Important: Performing this step ensures that all nodes in your distributed Oracle Portal environment share the same Login Server. When installing Oracle Portal with the Oracle Universal Installer (OUI), each node is installed with its own Login Server. Therefore, when installing multiple nodes, they do not, by default, share the same Login Server.

For the purpose of our example, we must make node a and node b share the same Login Server.

Otherwise, any node that is not sharing the same Login Server as the other nodes in the distributed environment fail when performing any type of distributed functionality.

1. Associate node a with the Login Server of node a.

   Note: By default, the OUI installs the first node and associates it to the appropriate Login Server. It is safe to skip this step unless you intend on editing the default Login Server association.

   1. Start a command line prompt.

   2. Change to the <ORACLE_HOME>/portal30/admin/plsql/ directory in which Oracle Portal for node a is installed.

   3. Run the ssodatan script to associate a node to the Login Server.

      See: For parameter descriptions, see "Configuring a New Oracle Portal Instance and Login Server with the ssodatan Script".

   4. Enter the script parameters as you would if node a were to function in a single node environment.

2. Register node b as a Partner Application to the Login Server of node a.
   1. In the Services portlet, click Login Server Administration. By default, the Services portlet is located on the Oracle Portal home page's Administer tab.

   2. Click Administer Partner Applications.

   3. Click Add Partner Application.

   4. Enter the following information on the Partner Application page:

      Table 4-1 Partner Application Configuration Example

      Field	Example Entry
      Name	Oracle Portal Note: This registers node b as a Partner Application.
      Home URL	http://OraclePortalsvr.us.oracle.com:<port>/pls/ <node b>/<node b>.home
      Success URL	http://OraclePortalsvr.us.oracle.com:<port>/pls/ <node b>/<node b>.wwsec_app_priv.process_signon

Note:: Specify the DAD name <node b> in lowercase characters.

3. Click Apply.

   The Edit Partner Application page displays.

4. On the page that appears, copy exactly (cut and paste) the displayed information which you will require to run the script in the next step. For example:
   • ID: 1323

   • Token: G06U7W36

   • Encryption Key: a21255e6b139ca34

5. Associate node b with the Login Server of node a.
   1. Start a command line prompt.

   2. Change to the <ORACLE_HOME>/portal30/admin/plsql/ directory in which Oracle Portal for node a is installed.

   3. Run the ssodatax script to associate a node to a specific Login Server:

      See: For parameter descriptions, see "Updating an Existing Portal Instance with the ssodatax Script".

   4. Enter the script parameters as required. For example, let's use the information generated by the example for registering a Partner Application to the Login Server of node a described above in step 4. This example also assumes that node b is installed on the database named "w816dev5" and node a is installed on the database named "w816dev6".

      ssodatax -i 1323 -t G06U7W36 -k a21255e6b139ca34 -w 
      http://OraclePortalsvr.us.oracle.com:5000/pls/<node b>/ -l 
      http://OraclePortalsvr.us.oracle.com:5000/pls/<node_A_SSO>/ -s node_B -v 
      v1.0 -o node_A_SSO -c w816dev5
      
      

You have completed this step. Node a and node b are associated to the same Login Server.

4.4.5 Step 5: Create a User on the Login Server with Administrator Privileges

In this step, you need to create a user on the Login Server with full administrator privileges on node b. This user must be the schema owner of node b.

1. In the Services portlet, click Login Server Administration. By default, the Services portlet is located on the Oracle Portal home page's Administer tab.

2. Click Administer Users.

3. Click Create New Users.

4. Enter the configuration information as required.

   Table 4-2 Login Server Create New User Example

   Parameter	Sample Entry
   User Name	<schema_of_node_b>
   Password	<schema_of_node_b>
   Confirm Password	<schema_of_node_b>

5. Click Create.

   A new user for the Login Server is created.

   See also: Oracle Portal Online Help content area topics: "What is a Login Server administrator?" Assigning a Login Server administrator"

4.4.6 Step 6: Discover the Name of Each Node

You must have the name of each node if you plan on registering the node.

1. In Oracle Portal, log on to node a as required by entering the username and password.

2. In the Node portlet, click Edit the Local Node. By default, the Node portlet is located on the Oracle Portal home page's Administer tab.

3. Write down the name of the Local Node.

4. Close all open browser windows.

Note: You must close all browser windows before accessing node b. The Oracle Portal session cookie that was created by node a must expire and perform authentication on the appropriate node (node b).

5. Open a new browser window and repeat the above steps for node a by logging onto node b.

4.4.7 Step 7: Register Nodes Between Themselves

1. While on node b, register node a to node b.
   1. In the Nodes portlet, click Add a Remote Node. By default, the Nodes portlet is located on the Oracle Portal home page's Administer tab.

   2. Enter the configuration information for node a as required on the configuration page.

   Table 4-3 Node a to node b registration information

   Field	Example Entry
   Remote Node Name	Name of the remote node (node a) obtained in the Section 4.4.6, "Step 6: Discover the Name of Each Node".
   Oracle Portal Database User	The schema owner for node a.
   Oracle Portal Database Password	The schema password for node a.
   Database Link Name	Oracle recommends that you leave this field blank. The default name is used when the database link is created on this page. Note that the default name is not displayed on this page.
   TNS Name	The TNS Names alias (connect string) for the database on which node a is installed. Example: w816dev6
   Remote Oracle Portal DAD	The DAD for node a created in Section 4.4.3, "Step 3: Edit Oracle Portal DADs".
   Remote Listener URL	The machine name on which the Oracle HTTP Server powered by Apache is installed. Example: OraclePortalsvr.company.com
   Remote Listener Port	The port on which the Oracle HTTP Server powered by Apache is running for that node. Example: 5000

2. Click OK.

3. Quit all the browser windows.

Note: You must close all browser windows before accessing node a in order for the Oracle Portal session cookie that was created by node b to expire and perform authentication on the appropriate node (node a).

4. Repeat the above steps to register node b to node a.

When this step is completed successfully, the Oracle Portal nodes are fully configured to operate in the distributed environment.

4.4.8 Step 8: Refresh the Portlet Repository for Each Node

The providers for each node that is configured for a distributed Oracle Portal environment, can be used by the other node. However, the Portlet Repository needs to be refreshed on each node to see the providers and portlets created on remote nodes.

To refresh the portlet repository:

1. From the Oracle Portal home page, click
   Text description of the illustration pobexp.gif from the shortcut bar to access the Navigator.

2. In the Navigator, click the Content Areas tab.

3. In the Name column, click Portlet Repository.

   The Portlet Repository Content Area is displayed.

4. Click Refresh in the upper right corner of the page.

   Note: This operation may take a few minutes to complete because the Portlet Repository is refreshed for all the providers that are registered on the node.

   Once this step is completed, the distributed portlets appear in the Portlet Repository. The providers that are not local (i.e. remote) are easily identifiable by their names which are prefixed with the name of the node to which they belong.

   The distributed portlets are now displayed on the Add Portlets page and can be used when creating a page.

5. Repeat the above steps for each node in your distributed Oracle Portal environment.

4.4.9 Step 9: Create Additional Nodes

You can always create additional nodes to participate in the distributed Oracle Portal environment. For example, to register node c, complete the following steps in the order presented:

Table 4-4 Creating additional nodes for distributed environment

Step	For more information, see...
Create node c on a different database from that of node a and node b.	Section 4.4.1, "Step 1: Create Oracle Portal Nodes"
Create a DAD for node c.	Section 4.4.3, "Step 3: Edit Oracle Portal DADs"
Associate node c with the Login Server used by node a and node b.	Section 4.4.4, "Step 4: Associate Nodes with the Same Login Server"
Create a user for node c on the Login Server.	Section 4.4.5, "Step 5: Create a User on the Login Server with Administrator Privileges"
Register node c on node a.	Section 4.4.7, "Step 7: Register Nodes Between Themselves"
Register node c on node b.	Section 4.4.7, "Step 7: Register Nodes Between Themselves"
Register node a on node c.	Section 4.4.7, "Step 7: Register Nodes Between Themselves"
Register node b on node c.	Section 4.4.7, "Step 7: Register Nodes Between Themselves"
Refresh the portlet repository on node a, b, and c.	Section 4.4.8, "Step 8: Refresh the Portlet Repository for Each Node"

The registration of nodes must be symmetric. In addition, it is important to register the new node, in this case node c, on an existing node, either node a or node b, before registering an existing node on the new node. This is required to maintain the cookie encryption key used by the other nodes of the distributed environment.