6
Distributed Oracle Portal Installations

A distributed environment refers to several installations of Oracle Portal to create a multi-node environment. 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

• Setting up a Distributed Oracle Portal Environment

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 6-1 Distributed Oracle Portal installations typology

Text description of the illustration disti_2_.gif

6.1 What is a node?

In a distributed Oracle Portal environment, each node is a complete Oracle Portal installation which resides in a separate database instance and is configured appropriately 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 will be discussed later in this chapter.

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

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

6.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 6-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 significantly 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 would continue to process with full access except on portlets residing on the failed node.

6.3 Node requirements

You must meet the following node requirements for a 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

6.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 will not function in a distributed manner.

See: Section 6.4.1, "Step 1: Create Oracle Portal nodes"

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

You can 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 Servers 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 will have 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 will not be sent by the browser.

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

See: Section 6.4.2, "Step 2: Create same cookie domain"

6.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 6.4.3, "Step 3: Edit Oracle Portal DADs"

6.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 6.4.4, "Step 4: Associate nodes with the same Login Server"

6.3.5 Symmetric node registration

All nodes included in the distributed architecture must be symmetrically registered between them. 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 6.4.7, "Step 7: Register nodes between themselves"

6.3.6 URLs in Portlets

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

See: Oracle Portal Development Kit on the Oracle Technology Network at http://technet.oracle.com/.

6.4 Setting up a Distributed Oracle Portal Environment

Ensure that you have the required privileges on the node and on the Login Server before performing the following steps:

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

• You must be an Oracle Portal Administrator to access the Administer tab of 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 will consist of two nodes: 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

6.4.1 Step 1: Create Oracle Portal nodes

As stated earlier, a node is an Oracle Portal installation. To participate in 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 Sun Sparc Solaris."

You will need to 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.

6.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, you can 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, you can stop the HTTP Server from the System Control Panel. For more information, see "Using the PL/SQL Gateway" guide included with the Oracle9i Application  Server documentation set.  
   
   
   
   
   
   
   
   
   
   

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

6.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, there should be only one installation of the Login Server.

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

6.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.
   1. 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 b.
   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 very 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.
   1. 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 very 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.

   6.4.4 Step 4: Associate nodes with the same Login Server

   Important: This step must be performed to ensure 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 will 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 /src directory in which Oracle Portal for node a is installed.

      3. Enter the following command to associate a node to the Login Server:

         ssodatan <-w portal_url> <-l login_server_url> <-s portal_schema> <-p 
         portal_password> <-o sso_schema> <-d sso_password> <-c portal_connect_
         string>
         
         

      Example

      ssodatan -w http://server.oracle.com:3000/pls/portal/ -l 
      http://server.oracle.com:3000/pls/portal_sso/ -s portal30 -p portal30 -o 
      portal30_sso -c orcl
      
      

      where

      Table 6-1 ssodatan parameters

      Parameter	Description
      -w portal_url	URL that points to the Oracle Portal node DAD. Include the full domain name with the host, http:// prefix in your URL, and end the URL with a forward slash (/). Note: If you are not using the default port number (for example, 80), you must specify it in the Oracle Portal URL.
      -l login_server_url	URL that points to the Login Server host and DAD. Include the full domain name with the host, http:// prefix in your URL, and end the URL with a forward slash (/). Note: If you are not using the default port number (for example, 443), you must specify it in the Login Server URL.
      -s portal_schema	Oracle database schema containing the Oracle Portal installation (database objects). Default = portal30
      -p portal_password	Oracle database password for the Oracle Portal schema. Default = <portal_schema>
      -o sso_schema	Oracle database schema for Login Server objects. Default = <portal_schema>_SSO
      -d sso_password	Oracle database password for Login Server schema. Default = <sso_schema>
      <-c portal_connect_string>	Connect string for the database in which the Oracle Portal schema is installed. You need to provide the connect string only if the Oracle Portal schema is located on a remote database. Default = null

   2. 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 6-2 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:: The DAD name <node b> must be specified in lowercase characters.

3. Click Apply.

   The Edit Partner Application page displays.

4. On the page that appears, you'll need to 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 /src directory in which Oracle Portal for node a is installed.

   3. Enter the following command to associate a node to a specific Login Server:

      ssodatax <-i portal_site_id> <-t portal_site_token> <-k encryption_key> 
      <-w portal_url> <-l login_server_url> <-s portal_schema> <-p portal_
      password> <-v cookie_version> <-o sso_schema> <-c connect_string>
      
      

   Example

   ssodatax -i 1234 -t A1B2C3 -k X9Y8Z7 -w 
   http://server.oracle.com:3000/pls/portal30/ -l 
   http://server.oracle.com:3000/pls/portal30_sso/ -s portal30 -v v1.0 -o 
   portal30_sso -c orcl
   
   

   where

   Table 6-3 ssodatax script parameters

   Parameter	Description
   -i portal_site_id	The ID is automatically set when a Partner Application (in this case, Oracle Portal installation) is added. It is used by the Login Server to identify the Partner Application to this node.
   -t portal_site_token	The token is automatically set when a Partner Application (in this case, Oracle Portal installation) is added. It is used by the Login Server to identify the Partner Application. The Partner Application must use the application token to identify itself to the Login Server to this node when requesting authentication.
   -k encryption_key	When a user tries to log into this Oracle Portal node using Single Sign-On, the Login Server generates a cookie that indicates a user's identity and whether the user has been authenticated. This key is used to encrypt the login cookie.
   -w portal_url	URL prefix to this Oracle Portal node and the DAD being accessed. Include the full domain name with the host, http:// prefix in your URL, and end the URL with a forward slash (/).
   -l login_server_url	URL prefix to the Login Server host and DAD. Include the full domain name with the host, http:// prefix in your URL, and end the URL with a forward slash (/).
   -s portal_schema	Oracle database schema containing the Oracle Portal installation (database objects). Default = portal30
   -p portal_password	Oracle database password for the Oracle Portal schema. Default = <portal_schema>
   -v cookie_version	Cookie version being used by the Login Server." Default = v1.0
   -o sso_schema	Oracle database schema for Login Server objects. Default = <portal_schema>_SSO
   -c connect_string	Connect string for the database in which the Oracle Portal schema is installed. You need to provide the connect string only if the Oracle Portal schema is located on a remote database. Default = null

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

6.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 6-4 Login Server Create New User Example

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

1. Click Create.

   A new user for the Login Server is created.

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

6.4.6 Step 6: Discover the name of each node

You require the name of each node for node registration.

1. In Oracle Portal, log onto 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 in order for the Oracle Portal session cookie that was created by node a to 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.

6.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 6-5 Node a to node b registration information

   Field	Example Entry
   Remote Node Name	Name of the remote node (node a) obtained in the Section 6.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 will be 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 6.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.

6.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 since 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 is 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.

6.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 6-6 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 6.4.1, "Step 1: Create Oracle Portal nodes"
Create a DAD for node c.	Section 6.4.3, "Step 3: Edit Oracle Portal DADs"
Associate node c with the Login Server used by node a and node b.	Section 6.4.4, "Step 4: Associate nodes with the same Login Server"
Create a user for node c on the Login Server.	Section 6.4.5, "Step 5: Create a user on the Login Server with administrator privileges"
Register node c on node a.	Section 6.4.7, "Step 7: Register nodes between themselves"
Register node c on node b.	Section 6.4.7, "Step 7: Register nodes between themselves"
Register node a on node c.	Section 6.4.7, "Step 7: Register nodes between themselves"
Register node b on node c.	Section 6.4.7, "Step 7: Register nodes between themselves"
Refresh the portlet repository on node a, b, and c.	Section 6.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.