5
Configuring the Login Server on a Separate Listener

In an enterprise deployment of Oracle Portal, it is typical to have a separate Login Server listener from the Oracle Portal listener. For performance reasons and connection pooling, it makes sense to configure the Login Server on a separate Oracle HTTP Server powered by Apache listener so that it is dedicated to authentication service only.

Architecturally, the Login Server is designed to be a central authentication service. As such, several Partner Applications exist within the enterprise and are hosted on various hosts. These Partner Applications are then configured to share a centralized Login Server.

Specific topics covered include:

5.1 Oracle Portal as a Partner Application

Oracle Portal is considered a Partner Application of the Login Server. The following figure illustrates such a configuration. Oracle Portal has a separate listener from the Login Server.

Figure 5-1 Oracle Portal as a Partner Application

Text description of partner.gif follows.
Text description of the illustration partner.gif

Whether you set up Oracle Portal as a Partner Application depends on:

Whether you are associating Oracle Portal to an existing Login Server (that you may not have any control over).
Configuring a new Oracle Portal installation.
Just want Oracle Portal and the Login Server to be serviced from separate middle-tier servers.

5.1.1 Associating Portal to an Existing Login Server That You Have No Control Over

If you do not have any administrative authority over the Login Server (for example, it is managed by the IT department), then you would associate an Oracle Portal node in the following way:

Inform the IT department that you need your Oracle Portal associated with the Login Server. Provide them with the following information:

Name of your application (arbitrary)
Home page URL
Success URL

Contact information - name and e-mail address

Note:
The Success URL points to a Web page where the browser is redirected after a successful login. It must correspond to the procedure that processes the user identification information from the Login Server. Your Oracle Portal's Success URL must be the full URL to the wwsec_app_priv.process_signon procedure in your Oracle Portal's schema.

Based on this information, the IT department creates a new Partner Application entry on the Login Server for your Oracle Portal and provides you with the following information:
- Site ID
- Site Token
- Encryption Key
Associate Oracle Portal to the Login Server by running the ssodatax script and entering the input information provided above. You will need to know the following information from the IT group to run the script:
- Site ID
- Site Token
- Encryption Key
- URL Prefix of the Login Server
- Schema Name of the Login Server

Syntax


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> <-e pstore_schema> <-r pstore_password> 
<-b pstore_dblink> <-c connect_string> <-n ps_connect_string>

See also:
For syntax and parameter descriptions, see "Updating an Existing Portal Instance with the ssodatax Script" in Appendix B .

After running the ssodatax script, your Oracle Portal is associated with the Login Server, each running on a separate listener providing you specified a different host name in the URL prefix for the Oracle Portal and the Login Server (ssodatax parameters -w and -l parameters respectively).

5.1.2 Associating Portal to an Existing Login Server That You Have Control Over

If you have full administrative control over the Login Server, then you can perform the association between your Oracle Portal and the Login Server using the ssodatan script, providing that they both reside on the same database instance.

If the database instances are on separate instances, complete the following steps first on your Oracle Portal and then on the Login Server.

These steps are summarized below:

Install a standalone Login Server by running the linstall script:

linstall <-o sso_schema> <-i pstore_password> <-s login_server_url> <-r random_
seed> <-p sys_password> <-u default_tablespace> <-t temporary_tablespace> <-d 
document_tablespace> <-l logging_tablespace> <-c connect_string>

See also:
For syntax and parameter descriptions, see "Manually Installing a Login Server with the linstall Script" in Appendix B .

Click
Text description of the illustration home.gif to navigate to the Oracle Portal Home Page.
Click the Administer tab.
In the Services portlet, click Login Server Administration.
Click Administer Partner Applications.
Click Add Partner Application.
In the Partner Application Login section, enter the Partner Application's name, the URL to the application's home page, and a success URL.
In the Valid Login Timeframe section, enter the dates when users can log on to the application through the Login Server. If you leave the End Date field blank, users can log on to the application indefinitely. In the Application Administrator section, enter an e-mail address and other information for the application's contact person or administrator.
Click OK. The new Partner Application appears in the Edit/Delete Partner Application list on the Partner Application page.
Run the ssodatax script and enter the input information generated above for your Oracle Portal.

See also:
For syntax and parameter descriptions, see "Updating an Existing Portal Instance with the ssodatax Script" in Appendix B .

After running the ssodatax script, your Oracle Portal is associated with the Login Server. Each one is running on a separate listener, if you specified a different host name in the URL prefix for the Oracle Portal and the Login Server (ssodatax parameters -w and -l parameters respectively).

Repeat steps 2-10 on the Login Server.

5.1.3 Login Server Configured with Oracle Internet Directory (OID)

With any of the previously described configurations, you can also use the Oracle Internet Directory as a user repository.

Figure 5-2 Login Server configured with Oracle Internet Directory (OID)

Text description of the illustration lsoid.gif

In this architecture, instead of authenticating the user's credentials against a local table, the Login Server authenticates the user's credentials against a local table. The Login Server makes LDAP API calls to the configured LDAP directory and authenticates the credentials against the directory.

Such a configuration requires that the Login Server be able to establish LDAP protocol communications between the database instance it resides in with the LDAP directory.

So, depending on the placement of the LDAP directory, the Login Server, and any firewalls, it must be noted that the machine on which the Login Server database schema resides needs to be able to have LDAP protocol access to the LDAP server. The default port for LDAP communication is port 389, however, it is configurable.

See also:

White Paper entitled, "Configuring Oracle Portal for LDAP Authentication" at the following URL:
http://technet.oracle.com/products/iportal/ listing.htm

5.2 Configuring Virtual Hosts

The Oracle9i Application Server HTTP server powered by Apache supports the configuration of virtual hosts. This allows a single machine and port to represent a number of virtual hosts. To configure virtual hosts, you must set this up on both Oracle Portal as well as on the Oracle HTTP Server.

In our example, let's assume that we want to access Oracle Portal as http://www.abc.com as well as http://www.xyz.com. Also, let's assume that the Login Server's URL is http://www.login.com.

The steps for configuring virtual hosts are:

In <ORACLE_HOME>/Apache/Apache/conf, open and edit the Oracle HTTP Server configuration file, http.conf. Verify that the contents of the file includes the similar information in the Virtual Hosts section:
```
### Section 3: Virtual Hosts
NameVirtualHost 127.0.0.1

<VirtualHost 127.0.0.1>
    ServerName www.abc.com
</VirtualHost>

<VirtualHost 127.0.0.1>
    ServerName www.xyz.com
</VirtualHost>

<VirtualHost 127.0.0.1>
    ServerName www.login.com
</VirtualHost>
```
See also:
"Oracle HTTP Server Configuration File (httpd.conf)" in Appendix A .
- In this example, we are using the IP address 127.0.0.1, which is a special IP address representing the local machine. In the more general case, this would be any valid IP address.
- The domain names specified in the ServerName entries need to be valid domain names. If you are setting up Oracle Portal on a local laptop, make the appropriate entries in your local hosts file.
```
# Copyright (c) 1993-1995 Microsoft Corp.
#
# This is a sample HOSTS file used by Microsoft TCP/IP
# for Windows NT/2000.
#
127.0.0.1	localhost
127.0.0.1	www.abc.com
127.0.0.1	www.xyz.com
127.0.0.1	www.login.com
```

For Single Sign-On, on the Login Server, to work, it must always be referenced by any Partner Application with the same hostname in the URL. This is because cookies are sent back only to the host that generated them. So, in the example above, the Login Server must always be referenced as http://www.login.com.

Thus, you must register www.abc.com, www.xyz.com, and www.login.com as Partner Applications.

Log on to the Login Server directly as an administrator with Full Privileges on the Login Server.
Add a Partner Application entry for www.abc.com.
Add a Partner Application for www.xyz.com.
Add a Partner Application for the Login Server, www.login.com.
Run the ssodatax script to create configuration entries on the Oracle Portal for each of these entry points.

After running the ssodatax script for each of the Partner Applications, the aliases should be correctly configured.

See also:
"Updating an Existing Portal Instance with the ssodatax Script".

5.3 Working with Firewalls and Load Balancers

Once Oracle Portal is deployed for access over the Internet, there are typically other network devices that may complicate the configuration such as firewalls, reverse proxies, server farms, and so on.

5.3.1 Internet Configuration with Reverse Proxy Server

A reverse proxy server is a host process which is used as part of a firewall architecture to isolate the internal hosts from the externally accessible host(s) by providing a proxy through which external requests must pass to access internal services. Typically, such a proxy server takes the form of a dual-homed host. This means that it is a host with two network interface cards. One interface connects to the external network, and the other interface connects to the internal network, or demilitarized zone (DMZ) of the firewall.

Figure 5-3 Internet configuration with reverse proxy server

Text description of proxy.gif follows.
Text description of the illustration proxy.gif

In this architecture, the browser accesses the server through a hostname which is published by the proxy server. The proxy server then forwards the request to the actual host within the firewall, which could be some other host name.

For this example, let's assume the following:

The published address is www.myOracle Portal.com
Internal to the firewall, the server name for the Oracle9i Application Server middle-tier is actually server.company.com.
Externally, the server is addressed with the default port 80; however, internally, the server.company.com is listening on port 7777.

Note:
This configuration is only possible with Oracle Portal version 3.0.7 and above. Prior to 3.0.7, Oracle Portal was not using the ServerName specified by the Oracle HTTP Server powered by Apache configuration. Instead, it was using the Host value in the HTTP request. Thus, you could not control the generation of self-referential URLs.

Complete these steps to configure Oracle Portal for this architecture:

Define configuration settings that allow the Oracle9i Application Server middle-tier to listen on port 7777, but assert to the server that it is using port 80.
Create VirtualHost entries that accept the internal host name, but then assert the externally visible host name, using the ServerName directive, so that self-referential URLs rendered on the Oracle Portal pages are valid for the browser.
Edit the hosts file on the internal middle-tier servers to define the IP addresses for the ServerNames asserted above, so that they can resolve the hostnames that are generated by Oracle Portal, for HTTP calls looping back to fetch portlet content.

See also:
"Local HOSTS File"
Run the ssodatan or ssodatax script(s), as appropriate, using the externally published server names; for example, www.myOracle Portal.com
See also:

"Configuring a New Oracle Portal Instance and Login Server with the ssodatan Script"

"Updating an Existing Portal Instance with the ssodatax Script"
Register the www.myOracle Portal.com domain name on a domain name server on the Internet, with IP address 196.12.67.8.

Note:
The IP addresses used in this example are for illustration purposes only and may not be valid IP addresses.

The figure below shows the server names and ports used in the above example:

Figure 5-4 Example of reverse proxy server configuration

Text description of proxyeg.gif follows.
Text description of the illustration proxyeg.gif

5.3.2 Oracle HTTP Server Configuration

You provide directives in the Oracle HTTP Server powered by Apache configuration file, httpd.conf, which specify the behavior described in the points above. The reverse proxy server contacts the internal middle-tier server as server.company.com over port 7777.

When the Oracle HTTP Server invokes PL/SQL Gateway (mod_plsql), and the mod_jserv, it then passes the ServerName www.myOracle Portal.com and port 80. Thus, URLs that are generated by the Oracle Portal code use www.myOracle Portal.com, port 80.

The directive `useCanonicalName on' instructs Apache to use the ServerName specified. Otherwise, it passes the name used in the Host: field of the request, which is not what we want in this case.

The relevant sections in the httpd.conf file for the server.company.com Oracle9i Application Server configuration is as shown below:

### Section 2: 'Main' server configuration
...
Port 80
Listen 7777
Listen 80

ServerName www.myOracle Portal.com
...
UseCanonicalName On
...
### Section 3: Virtual Hosts
#
# VirtualHost: If you want to maintain multiple domains/hostnames on 
# your machine you can setup VirtualHost containers for them.
#
# If you want to use name-based virtual hosts you need to define at
# least one IP address (and port number) for them.
#

# This section is mandatory for URLs that are generated by
# the PL/SQL packages of the Oracle Portal
# These entries dictate that the server should listen on port
# 7777, but will assert that it is using port 80, so that
# self-referential URLs generated specify www.myOracle Portal.com:80
# This will create URLs that are valid for the browser since
# the browser does not directly see the host server.company.com.
NameVirtualHost 123.45.67.8:7777

<VirtualHost server.company.com:7777>
ServerName www.myOracle Portal.com
Port 80
</VirtualHost>

# Since the previous virtual host entry will cause all links 
# generated by the Oracle Portal to use port 80, the server.company.com
# server needs to listen on 80 as well since the Parallel Page
# Engine will make connection requests to Port 80 to request the
# portlets.

NameVirtualHost 123.45.67.8:80

<VirtualHost server.company.com:80>
ServerName www.myOracle Portal.com
Port 80
</VirtualHost>

If you need to support multiple aliases for the published address www.myOracle Portal.com, then some additional directives are needed. For example, if the server also needs to be accessible as www.Oracle Portal.com, then you need to define additional virtual host entries on the internal server as well so that of the reverse proxy directs requests from each corresponding published hostname to a related internal host alias which can assert the correct published name.

In this example, the VirtualHost sections appear as follows:

NameVirtualHost 123.45.67.8:7777

<VirtualHost server.company.com:7777>
ServerName www.myOracle Portal.com
Port 80
</VirtualHost>

<VirtualHost server2.company.com:7777>
ServerName www.Oracle Portal.com
Port 80
</VirtualHost>

NameVirtualHost 123.45.67.8:80

<VirtualHost server.company.com:80>
ServerName www.myOracle Portal.com
Port 80
</VirtualHost>

<VirtualHost server2.company.com:80>
ServerName www.Oracle Portal.com
Port 80
</VirtualHost>

5.3.3 Resolving Domain Names

A local HOSTS file can help resolve domain names that are not normally visible to the internal network. For example, the Oracle9i Application Server host for server.company.com makes requests to itself, but the URLs that it is requesting are referring to www.myOracle Portal.com. You must create host entries in the local HOSTS file on that machine allowing it to resolve this name, within the firewall. The hosts entry for this example should include the following lines:

# This is a sample HOSTS file used by Microsoft TCP/IP
# for Windows NT/2000.
#
127.0.0.1   	  localhost
123.45.67.8	   www.myOracle Portal.com

If you do not provide these entries in the local HOSTS file, then you need to set the Oracle9i Application Server host to recognize a proxy server that would take the request out to the Internet and back in through the reverse proxy (www.myOracle Portal.com). Avoid this setup as this may result in poor performance.

Note:
On some platforms, such as HP, there is a file which indicates the search order that should be applied to the sources for IP name mapping. For the above example to work, if such a file exists on your platform, make sure that it specifies the local hosts file to be checked for IP mapping, before any DNS servers.

5.4 Configuration with Load Balancing Router

The purpose of a Load Balancing Router (LBR) is to provide a single published address to the client browsers, and provide a "farm" of Web servers which actually service the requests, based on the distribution of the requests done by the LBR. The LBR itself is a very fast network device which can distribute Web requests to a large number of physical servers.

If you want to install multiple Oracle9i Application Server middle-tier servers to handle a large load, you could configure Oracle Portal as illustrated in the following diagram:

Figure 5-5 Load balancing router configuration

Text description of load.gif follows.
Text description of the illustration load.gif

This example shows that each of the servers can handle requests for either the Login Server or Oracle Portal. Each of the middle-tier servers must have DAD entries for each of the databases. A good way to accomplish this is to have the middle-tier servers share a file system that contains the configuration information for the DADs, and allows them to share cache files.

The important points to consider with this configuration include:

The Internet DNS maps the name www.myOracle Portal.com to the external IP address on the LBR.
The LBR performs load balancing of requests to www.myOracle Portal.com to svr1.company.com, svr2.company.com, and svr3.company.com, addressing the request to their IP addresses, but still containing www.myOracle Portal.com in the Host: field of the HTTP request.
Each of the middle-tier hosts accepts requests to www.myOracle Portal.com, and their httpd.conf files assert that name as the ServerName. Hence the names svr1, svr2, and so on are irrelevant.
The local hosts files on svr1, svr2, and svr3 contain the entry www.myOracle Portal.com, each pointing to its own IP address.
Unless your LBR does port mapping, you should configure the internal servers to use the same ports as the LBR.
Optimal cache utilization can be realized by mounting a shared file system on which to write the cache files. If you decide not to have the middle-tier servers share a cache directory, caching will still work, but with a lower hit ratio.

5.4.1 Placing a Firewall Between the Middle-tier and the Database

It is fairly typical to have a firewall with a SQL*Net proxy between the application server and the database for Oracle installations. Keep in mind though that the Oracle Portal architecture requires HTTP connects from the database to the middle-tier servers, for example, when the Oracle Portal makes an HTTP request to the Login Server to get the list of external applications. Or, when the Oracle Portal repository makes an HTTP request to a particular provider which may be a Web provider, potentially outside the Intranet firewall. Keep this communication path in mind when planning where firewalls should go and what traffic should be allowed through them.

You need to allow HTTP traffic to pass on the ports that are being used, through any firewall set up between the middle-tier and the database on which the Oracle Portal code resides.

Similarly, if the Login Server is setup for LDAP authentication, then LDAP traffic must be allowed to reach the LDAP server. The LDAP calls are made from the Login Server database instance.

See also:
Oracle Portal Content Area Help: "Configuring the Login Server for LDAP user authentication" Help topic.

5.5 Setting the Number of Requests That Can Be Handled by the Apache Listener

However you choose to configure the Apache listener, you can optimize performance by setting an approximate number of simultaneous requests that can be handled by the Apache listener.

On UNIX, in particular, since Apache is process-based, each process needs to open a connection to each database-DAD combination that has requested it. As a result, the number of requests can be quite high, which may result in clients being "locked out" if the number of sessions allowable has been exceeded. However, setting too high of a value unnecessarily consumes resources.

The scenario is described below:

For every service request from an Oracle Portal DAD, there is one network connection and two sessions (the two sessions use the same physical connection).

The first session is for "portal30" and the second is for "portal30_public".
If you are logging into Oracle Portal, then you'll need to open a connection for the Login Server DAD (SSO DAD) as well as requiring one network connection and two sessions.

In this case, the first session is for "portal30_sso" and the second session is for "portal30_sso_public".
The Apache configuration setting that determines the maximum number of requests being handled simultaneously is named MaxClients. It defaults to 150.

If each user were logging in and working in Oracle Portal, then scenario (1) and (2) above would result in four sessions per process. The total number of sessions for such a scenario is calculated as follows:
```
150 * 4 = 600 
```
600 sessions and approximately 300 database connections (2 sessions per connection)

5.5.1 Setting the MaxClient Setting on the Apache Listener and on the Portal Listener

Since login frequency is generally lower than Oracle Portal access frequency, it makes sense to configure the Login Server on a different Apache listener. The objective is to tune down the MaxClient setting to a value that is reasonable without affecting the needs of the portal system.

On the Apache listener, once you've determined the approximate value to set for the MaxClients parameter, edit this accordingly in the Apache configuration file, http.conf, which is located in:
```
<ORACLE_HOME>/Apache/Apache/conf/
```
Tune down the MaxClients setting to control the number of requests that Apache services on the Apache listener. This controls the number of sessions established.
On the Portal listener, you can separately tune the MaxClients parameter according to the needs of the Login Server and the needs of Oracle Portal, without affecting each other. This parameter directly corresponds to the number of sessions established and to the maximum workload that the Apache listener can handle on the Portal listener.

The MaxClients section in the http.conf file is shown below:
```
# Limit on total number of servers running, i.e., limit on the number
# of clients who can simultaneously connect --- if this limit is ever
# reached, clients will be LOCKED OUT, so it should NOT BE SET TOO LOW.
# It is intended mainly as a brake to keep a runaway server from taking
# the system with it as it spirals down...
#
MaxClients 150
```

5Configuring the Login Server on a Separate Listener