6 Performing Common Tasks

The following sections describe common tasks that you perform for the plug-ins provided by Oracle for use with WebLogic Server:

Use SSL With Plug-Ins
Use IPv6 With Plug-Ins
Set Up Perimeter Authentication
Understanding Connection Errors and Clustering Failover

Use SSL With Plug-Ins

You can use the Secure Sockets Layer (SSL) protocol to protect the connection between the plug-in and WebLogic Server. The SSL protocol provides confidentiality and integrity to the data passed between the plug-in and WebLogic Server.

The plug-in does not use the transport protocol (HTTP or HTTPS) specified in the HTTP request (usually by the browser) to determine whether or not to use SSL to protect the connection between the plug-in and WebLogic Server. That is, the plug-in is in no way dependent on whether the HTTP request (again, usually from the browser) uses HTTPS (SSL).

Instead, the plug-in uses SSL parameters that you configure for the plug-in, as described in SSL Parameters for Web Server Plug-Ins, to determine when to use SSL. There are two key SSL parameters:

WLSSLWallet -- The version 1.1 plug-ins use Oracle wallets to store SSL configuration information. The plug-ins introduce a new SSL configuration parameter WLSSLWallet to use Oracle wallets. The orapki utility is provided in the plug-in distribution for this purpose.

The orapki utility manages public key infrastructure (PKI) elements, such as wallets and certificate revocation lists, on the command line so the tasks it performs can be incorporated into scripts. This enables you to automate many of the routine tasks of maintaining a PKI.

See "Using the orapki Utility for Certificate Validation and CRL Management" for information about this tool.
SecureProxy -- The SecureProxy parameter determines whether SSL is enabled or not.

In the case of two-way SSL, the plug-in (the SSL client) automatically uses two-way SSL when the WebLogic Server is configured for two-way SSL and requests a client certificate.

If a client certificate is not requested, the plug-ins default to one-way SSL.

Note:

If you have an Oracle Fusion Middleware 11g Release 11 (11.1.1) product installed on the same system as the Apache (including Oracle HTTP) plug-in, the ORACLE_HOME variable must point to a valid installation or the plug-in fails to initialize SSL.

For example, if ORACLE_HOME is invalid because the product was not cleanly removed, the plug-in fails to initialize SSL.

Configure Libraries for SSL

The plug-ins use Oracle libraries (NZ) to provide SSL support. Because the libraries are large, they are dynamically linked only when SSL is needed. You need to make sure that the library files, located in lib/*.so*, are available in the proper locations so that they can be dynamically loaded by the plug-in.

Configure Apache Libraries for SSL

To configure the libraries for the Apache plug-in (used for both the Apache HTTP Server and the Oracle HTTP Server ) you have a few options:

For Windows, the lib\*.dll directory must be in the PATH variable, or add the *.dll files to the Apache/bin directory.
For Unix, copy the binaries to the Apache lib folder, or configure LD_LIBRARY_PATH to point the the folder containing the binaries.

Configuring a Plug-In for One-Way SSL

After you have installed and configured a plug-in as described in the respective plug-in-specific chapter, you can configure that plug-in to use one-way SSL.

Perform the following steps to configure one-way SSL.

In these steps, you run the keytool commands on the system on which WebLogic Server is installed. You run the orapki commands on the system on which the version 1.1 plug-ins are installed.

Note:

This section uses the WebLogic Server demo CA for the purpose of example.

If you are using the plug-in in a production environment, make sure that trusted CAs are properly configured for the plug-in as well as for WebLogic Server.

Configure WebLogic Server for SSL. For more information, see "Configuring SSL" in Securing Oracle WebLogic Server.
Configure the WebLogic Server SSL listen port. For more information, see "Configuring SSL" in Securing Oracle WebLogic Server.
Create an Oracle Wallet with the orapki utility.

See "Using the orapki Utility for Certificate Validation and CRL Management" in Oracle Fusion Middleware Administrator's Guide for information about this tool.
```
orapki wallet create -wallet mywallet -auto_login_only
```

Import the WL_HOME\server\lib\CertGenCA.der CA into the Oracle Wallet.

orapki wallet add -wallet mywallet -trusted_cert -cert CertGenCA.der -auto_login_only

For the Apache Plug-in, in the HTTP Server, edit the httpd.conf file as follows:
```
<IfModule mod_weblogic.c>
WebLogicHost my-weblogic.server.com
  WebLogicPort weblogic-server-secure-port
  SecureProxy ON
  WLSSLWallet /home/myhome/mywallet
</IfModule>
```
Where:
- my-weblogic-server.com is your WebLogic Server system.
- weblogic-server-secure-port is the port used for SSL, typically 7002.
- The SecureProxy parameter determines whether SSL is enabled or not.
- WLSSLWallet takes the path of an Oracle Wallet as an argument.
For the IIS plug-in, edit the Microsoft Internet Information Server iisproxy.ini file as follows:
```
WebLogicHost=my-weblogic.server.com
  WebLogicPort=weblogic-server-secure-port
  SecureProxy=ON
  WLSSLWallet=c:\home\myhome\mywallet
```
Where:
- my-weblogic-server.com is your WebLogic Server system.
- weblogic-server-secure-port is the port used for SSL, typically 7002.
- The SecureProxy parameter determines whether SSL is enabled or not.
- WLSSLWallet takes the path of an Oracle Wallet as an argument.
For the Apache Plug-in, set any additional parameters in the httpd.conf file that define information about the SSL connection. For a complete list of the SSL parameters that you can configure for the plug-in, see SSL Parameters for Web Server Plug-Ins.
For the IIS plug-in, set any additional parameters in the iisproxy.ini file that define information about the SSL connection. For a complete list of the SSL parameters that you can configure for the plug-in, see SSL Parameters for Web Server Plug-Ins.
Send a request to http://apache-host:apache-port/mywebapp/my.jsp from the browser. Validate the response.

Configure Two-Way SSL Between the Plug-In and WebLogic Server

After you have installed and configured a plug-in as described in the respective plug-in-specific chapter, you can configure that plug-in to use two-way SSL.

You configure two-way SSL by importing a user certificate into the Wallet. When WebLogic Server is configured for two-way SSL, the plug-in forwards the user certificate to WebLogic Server. As long as WebLogic Server can validate the user certificate, two-way SSL can be established.

In addition to the steps described in Configuring a Plug-In for One-Way SSL to configure SSL, perform the following additional steps to configure two-way SSL between the plug-in and WebLogic Server.

Again, in these steps, you run the keytool commands on the system on which WebLogic Server is installed. You run the orapki commands on the system on which the version 1.1 plug-ins are installed.

From the Oracle wallet, generate a certificate request.
Use this certificate request to create a certificate via a CA or some other mechanism.
Import the user certificate as a trusted certificate in the WebLogic truststore. WebLogic Server needs to trust the certificate.
```
keytool -file user.crt -importcert -trustcacerts -keystore DemoTrust.jks -storepass <passphrase>
```
Set the WebLogic Server SSL configuration options that require the presentation of client certificates (for two-way SSL). See "Configure two-way SSL" in the Oracle WebLogic Server Administration Console Help.

Issues with SSL-Apache Configuration

These known issues arise when you configure the Apache plug-in to use SSL:

The PathTrim parameter (see SSL Parameters for Web Server Plug-Ins ) must be configured inside the <Location> tag.

The following configuration is incorrect:

<Location /weblogic>
 SetHandler weblogic-handler 
</Location> 

<IfModule mod_weblogic.c>
 WebLogicHost localhost
 WebLogicPort 7001
 PathTrim /weblogic
</IfModule>

The following configuration is the correct setup:

<Location /weblogic>
  SetHandler weblogic-handler
  PathTrim /weblogic
</Location>

The current implementation of the WebLogic Server Apache Plug-In does not support the use of multiple certificate files with Apache SSL.

Use IPv6 With Plug-Ins

The version 1.1 plug-ins support IPv6. Specifically, the WebLogicHost and WebLogicCluster configuration parameters (see Table 7-1) now support IPv6 addresses. For example:

<IfModule mod_weblogic.c>
      WebLogicHost [a:b:c:d:e:f]
      WebLogicPort 7002
      ...
</IfModule>

<IfModule mod_weblogic.c>
      WebLogicCluster [a:b:c:d:e:f]:<port>, [g:h:i:j:k:l]:<port>
 
      ....
</IfModule>

You can also use the IPv6 address mapped host name.

Set Up Perimeter Authentication

Use perimeter authentication to secure WebLogic Server applications that are accessed via the plug-in.

A WebLogic Identity Assertion Provider authenticates tokens from outside systems that access your WebLogic Server application, including users who access your WebLogic Server application through the plug-in. Create an Identity Assertion Provider that will safely secure your plug-in as follows:

Create a custom Identity Assertion Provider on your WebLogic Server application. See "How to Develop a Custom Identity Assertion Provider" in Developing Security Providers for Oracle WebLogic Server.
Configure the custom Identity Assertion Provider to support the Cert token type and make Cert the active token type. See "How to Create New Token Types" in Developing Security Providers for Oracle WebLogic Server.
Set clientCertProxy to True in the web.xml deployment descriptor file for the Web application (or, if using a cluster, optionally set the Client Cert Proxy Enabled attribute to true for the whole cluster on the Administration Console Cluster-->Configuration-->General tab).

The clientCertProxy attribute can be used with a third party proxy server, such as a load balancer or an SSL accelerator, to enable 2-way SSL authentication. For more information about the clientCertProxy attribute, see context-param in Developing Web Applications, Servlets, and JSPs for Oracle WebLogic Server.
Once you have set clientCertProxy, be sure to use a connection filter to ensure that WebLogic Server accepts connections only from the machine on which the plug-in is running. See "Using Network Connection Filters" in Programming Security for Oracle WebLogic Server.
Web server plug-ins require a trusted Certificate Authority file in order to use SSL between the plug-in and WebLogic Server. See Use SSL With Plug-Ins for the steps you need to perform to configure SSL.

See Identity Assertion Providers in Developing Security Providers for Oracle WebLogic Server.

Understanding Connection Errors and Clustering Failover

When the plug-in attempts to connect to WebLogic Server, the plug-in uses several configuration parameters to determine how long to wait for connections to the WebLogic Server host and, after a connection is established, how long the plug-in waits for a response. If the plug-in cannot connect or does not receive a response, the plug-in attempts to connect and send the request to other WebLogic Server instances in the cluster. If the connection fails or there is no response from any WebLogic Server in the cluster, an error message is sent.

Figure 6-1 demonstrates how the plug-in handles failover.

Possible Causes of Connection Failures

Failure of the WebLogic Server host to respond to a connection request could indicate the following problems:

Physical problems with the host machine
Network problems
Other server failures

Failure of all WebLogic Server instances to respond could indicate the following problems:

WebLogic Server is not running or is unavailable
A hung server
A database problem
An application-specific failure

Tuning Apache Plug-In to Reduce Connection_Refused Errors

Under load, an Apache plug-in may receive CONNECTION_REFUSED errors from a back-end WebLogic Server instance. Follow these tuning tips to reduce CONNECTION_REFUSED errors:

Increase the AcceptBackLog setting in the configuration of your WebLogic Server domain.
Decrease the time wait interval. This setting varies according to the operating system you are using. For example:
- On Windows NT, set the TcpTimedWaitDelay on the proxy and WebLogic Server servers to a lower value. Set the TIME_WAIT interval in Windows NT by editing the registry key under HKEY_LOCAL_MACHINE:
```
SYSTEM\CurrentControlSet\Services\Tcpip\Parameters\TcpTimedWaitDelay 
```
  If this key does not exist you can create it as a DWORD value. The numeric value is the number of seconds to wait and may be set to any value between 30 and 240. If not set, Windows NT defaults to 240 seconds for TIME_WAIT.
- On Windows 2000, lower the value of the TcpTimedWaitDelay by editing the registry key under HKEY_LOCAL_MACHINE:
```
SYSTEM\CurrentControlSet\Services\Tcpip\Parameters
```
- On Solaris, reduce the setting tcp_time_wait_interval to one second (for both the WebLogic Server machine and the Apache machine, if possible):
```
$ndd /dev/tcp
   param name to set - tcp_time_wait_interval
   value=1000
```
Increase the open file descriptor limit on your machine. This limit varies by operating system. Using the limit (.csh) or ulimit (.sh) directives, you can make a script to increase the limit. For example:
```
#!/bin/sh
ulimit -S -n 100
exec httpd
```
On Solaris, increase the values of the following tunables on the WebLogic Server machine:
```
tcp_conn_req_max_q tcp_conn_req_max_q0
```

Failover with a Single, Non-Clustered WebLogic Server

If you are running only a single WebLogic Server instance the plug-in only attempts to connect to the server defined with the WebLogicHost parameter. If the attempt fails, an HTTP 503 error message is returned. The plug-in continues trying to connect to that same WebLogic Server instance for the maximum number of retries as specified by the ratio of ConnectTimeoutSecs and ConnectRetrySecs.

The Dynamic Server List

The WebLogicCluster parameter is required to proxy to a list of back-end servers that are clustered, or to perform load balancing among non-clustered managed server instances.

In the case of proxying to clustered managed servers, when you use the WebLogicCluster parameter in your httpd.conf or weblogic.conf file to specify a list of WebLogic Servers, the plug-in uses that list as a starting point for load balancing among the members of the cluster. After the first request is routed to one of these servers, a dynamic server list is returned containing an updated list of servers in the cluster. The updated list adds any new servers in the cluster and deletes any that are no longer part of the cluster or that have failed to respond to requests. This list is updated automatically with the HTTP response when a change in the cluster occurs.

Failover, Cookies, and HTTP Sessions

When a request contains session information stored in a cookie or in the POST data, or encoded in a URL, the session ID contains a reference to the specific server instance in which the session was originally established (called the primary server). A request containing a cookie attempts to connect to the primary server. If that attempt fails, the plug-in attempts to make a connection to the next available server in the list in a round-robin fashion. That server retrieves the session from the original secondary server and makes itself the new primary server for that same session. See Figure 6-1.

Note:

If the POST data is larger than 64K, the plug-in will not parse the POST data to obtain the session ID. Therefore, if you store the session ID in the POST data, the plug-in cannot route the request to the correct primary or secondary server, resulting in possible loss of session data.

Figure 6-1 Connection Failover

Description of "Figure 6-1 Connection Failover"

In this figure, the Maximum number of retries allowed in the red loop is equal to ConnectTimeoutSecs/ConnectRetrySecs.