Skip navigation.
Downloads | Product Documentation | Support

Using Web Server Plug-Ins with WebLogic Server

# Installing and Configuring the Netscape Enterprise Server Plug-In

The following sections describe how to install and configure the Netscape Enterprise Server (NES) proxy plug-in:

- Overview of the Netscape Enterprise Server Plug-In on page 4-1
- Installing and Configuring the Netscape Enterprise Server Plug-In on page 4-3
- Setting Up Perimeter Authentication on page 4-14
- Using SSL with the NES Plug-In on page 4-15
- Connection Errors and Clustering Failover on page 4-17
- Failover Behavior When Using Firewalls and Load Directors on page 4-18
- Sample obj.conf File (Not Using a WebLogic Cluster) on page 4-10
- Sample obj.conf File (Using a WebLogic Cluster) on page 4-12

# Overview of the Netscape Enterprise Server Plug-In

The Netscape Enterprise Server Plug-In proxies requests from Sun One Web Server (also called iPlanet) to WebLogic Server. The plug-in enhances a Sun One Web Server installation by allowing WebLogic Server to handle those requests that require the dynamic functionality of WebLogic Server.

The Netscape Enterprise Server Plug-In is designed for an environment where Sun One Web Server serves static pages, and a Weblogic Server instance (operating in a different process, possibly on a different machine) is delegated to serve dynamic pages, such as JSPs or pages generated by HTTP Servlets. The connection between WebLogic Server and the Netscape Enterprise Server Plug-In is made using clear text or Secure Sockets Layer (SSL). To the end user—the browser—the HTTP requests delegated to WebLogic Server appear to come from the same source as the static pages. Additionally, the HTTP-tunneling facility of WebLogic Server can operate through the Netscape Enterprise Server Plug-In, providing access to all WebLogic Server services (not just dynamic pages).

The Netscape Enterprise Server Plug-In operates as an NES module within a Sun One Web Server. The NES module is loaded by NES at startup, and then certain HTTP requests are delegated to it. NES is similar to an HTTP (Java) servlet, except that an NES module is written in code native to the platform.

You target a WebLogic Server instance using the WebLogicHost and WebLogicPort parameters in the plug-in configuration file. You target a WebLogic Server cluster or group of non-clustered servers using the WebLogicCluster parameter. For information about setting plug-in parameters, see Parameters for Web Server Plug-Ins.

For more information on supported versions of Sun One Web Server and iPlanet servers, see the BEA WebLogic Server Supported Configurations Page.

## Connection Pooling and Keep-Alive

The WebLogic Server Netscape Enterprise Server Plug-In provides efficient performance by using a re-usable pool of connections from the plug-in to WebLogic Server. The NES plug-in automatically implements "keep-alive" connections between the plug-in and WebLogic Server. If a connection is inactive for more than 30 seconds or a user-defined amount of time, the connection is closed. You can disable this feature if desired. For more information, see KeepAliveEnabled.

# Certifications

The Netscape Enterprise Server Plug-In is supported on Linux, Solaris, AIX, and Windows platforms. Plug-ins are not supported on all operating systems for all releases. For information on platform support for specific versions of Netscape Enterprise Server Plug-In, see Platform Support for WebLogic Server Plug-ins and Web Servers in Supported Configurations for WebLogic Server 8.1.

# Installing and Configuring the Netscape Enterprise Server Plug-In

To install and configure the Netscape Enterprise Server Plug-In:

1. Copy the NES library from WebLogic Server to Sun One Web Server.

The WebLogic NES plug-in module is distributed as a shared object (`.so`) on UNIX platforms and as a dynamic-link library (`.dll`) on Windows. These files are respectively located in the WL_HOME/server`/lib` or WL_HOME/server`/bin` directories of your WebLogic Server distribution. WL_HOME represents the top level installation directory for your WebLogic platform. The server directory contains installation files for WebLogic Server. The modules are

Table 4-1 Locations of Plug-In Shared Object Files

Operating System | Shared Object Location
--- | ---
AIX | `WL_HOME/server/lib/aix/libproxy128_60.so` `WL_HOME/server/lib/aix/libproxy128_61.so` `WL_HOME/server/lib/aix/libproxy_60.so` `WL_HOME/server/lib/aix/libproxy_61.so`
HP-UX11 | `WL_HOME/server/lib/hpux11/libproxy128.sl` `WL_HOME/server/lib/hpux11/libproxy128_61.sl` `WL_HOME/server/lib/hpux11/libproxy.sl` `WL_HOME/server/lib/hpux11/libproxy_61.sl`
Linux | `WL_HOME/server/lib/linux/i686/libproxy128.so` `WL_HOME/server/lib/linux/i686/libproxy128_61.so` `WL_HOME/server/lib/linux/i686/libproxy.so` `WL_HOME/server/lib/linux/i686/libproxy_61.so`
Solaris Sparc | `WL_HOME/server/lib/solaris/libproxy128.so` `WL_HOME/server/lib/solaris/libproxy128_61.so` `WL_HOME/server/lib/solaris/libproxy.so` `WL_HOME/server/lib/solaris/libproxy_61.so`
Solaris x86 | `WL_HOME/server/lib/solaris/x86/libproxy128_61.so` `WL_HOME/server/lib/solaris/x86/libproxy_61.so`
Windows | `WL_HOME\server\bin\proxy30.dll` `WL_HOME\server\bin\proxy30128.dll` `WL_HOME\server\bin\proxy35.dll` `WL_HOME\server\bin\proxy35128.dll` `WL_HOME\server\bin\proxy36.dll` `WL_HOME\server\bin\proxy36128.dll` `WL_HOME\server\bin\proxy61.dll` `WL_HOME\server\bin\proxy61128.dll`

1. Read Guidelines for Modifying the obj.conf File, then modify the NES `obj.conf` file as described in the following steps. The `obj.conf` file defines which requests are proxied to WebLogic Server and defines other configuration information.
2. Locate and open `obj.conf`.

The `obj.conf` file for your NES instance is in the following location:

`NETSCAPE_HOME``/https-``INSTANCE_NAME``/config/obj.conf`

Where `NETSCAPE_HOME` is the root directory of the NES installation, and `INSTANCE_NAME` is the particular "instance" or server configuration that you are using. For example, on a UNIX machine called `myunixmachine`, the `obj.conf` file would be found here:

>     /usr/local/netscape/enterprise-351/
>      https-myunixmachine/config/obj.conf

3. Instruct NES to load the native library (the `.so` or `.dll` file) as an NES module.

If you are using iPlanet 4.x or earlier, add the following lines to the beginning of the `obj.conf` file.

>     Init fn="load-modules" funcs="wl_proxy,wl_init"\
>     shlib=/usr/local/netscape/plugins/SHARED_LIBRARY
>     Init fn="wl_init"

Where `SHARED_LIBRARY` is the shared object or `dll` (for example `libproxy.so`) that you installed in step 1. under Installing and Configuring the Netscape Enterprise Server Plug-In. The function "`load-modules`" tags the shared library for loading when NES starts up. The values "`wl_proxy`" and "`wl_init`" identify the functions that the Netscape Enterprise Server Plug-In executes.

To use iPlanet 6.0, add the following lines to the beginning of the `magnus.conf` file. These lines instruct NES to load the native library (the `.so` or `.dll` file) as an NES module:

>     Init fn="load-modules" funcs="wl_proxy,wl_init"\
>     shlib=/usr/local/netscape/plugins/SHARED_LIBRARY
>     Init fn="wl_init"

Where `SHARED_LIBRARY` is the shared object or `dll` (for example `libproxy.so`) that you installed in step 1. under Installing and Configuring the Netscape Enterprise Server Plug-In. The function "`load-modules`" tags the shared library for loading when NES starts up. The values "`wl_proxy`" and "`wl_init`" identify the functions that the Netscape Enterprise Server Plug-In executes.

4. If you want to proxy requests by URL, (also called proxying by path.) create a separate `<Object>` tag for each URL that you want to proxy and define the PathTrim parameter. (You can proxy requests by MIME type, in addition to or instead of proxying requests by path. See step 6. Proxying by path supersedes proxying by MIME type.) The following is an example of an `<Object>` tag that proxies a request containing the string `*/weblogic/*`.

>     <Object name="weblogic" ppath="*/weblogic/*">
>     Service fn=wl_proxy WebLogicHost=myserver.com\
>      WebLogicPort=7001 PathTrim="/weblogic"
>     </Object>

To create an `<Object>` tag to proxy requests by URL:

1. Specify a name for this object (optional) inside the opening `<Object>` tag using the `name` attribute. The `name` attribute is informational only and is not used by the Netscape Enterprise Server Plug-In. For example:

>     <Object name=myObject ...>

2. Specify the URL to be proxied within the `<Object>` tag, using the `ppath` attribute. For example:

>     <Object name=myObject ppath="*/weblogic/*>

The value of the `ppath` attribute can be any string that identifies requests intended for Weblogic Server. When you use a `ppath`, every request that contains that path is redirected. For example, a `ppath` of "`*/weblogic/*`" redirects every request that begins "`http://enterprise.com/weblogic`" to the Netscape Enterprise Server Plug-In, which sends the request to the specified Weblogic Server instance or cluster.

Note: If the web application uses absolute URLs, ensure that the `ppath` string is included in the URL.

3. Add the `Service` directive within the `<Object>` and `</Object>` tags. In the `Service` directive you can specify any valid parameters as name=value pairs. Separate multiple name=value pairs with one and only one space. For example:

>     Service fn=wl_proxy WebLogicHost=myserver.com\
>      WebLogicPort=7001 PathTrim="/weblogic"

For a complete list of parameters, see General Parameters for Web Server Plug-Ins. You must specify the following parameters:

For a non-clustered WebLogic Server:
The WebLogicHost and WebLogicPort parameters.

For a cluster of WebLogic Server instances:
The WebLogicCluster parameter.

Always begin the `Service` directive with Service `fn=wl_proxy`, followed by valid name=value pairs of parameters.

Here is an example of the object definitions for two separate `ppaths` that identify requests to be sent to different instances of WebLogic Server:

>     <Object name="weblogic" ppath="*/weblogic/*">
>     Service fn=wl_proxy WebLogicHost=myserver.com\
>      WebLogicPort=7001 PathTrim="/weblogic"
>     </Object>

>     <Object name="si" ppath="*/servletimages/*">
>     Service fn=wl_proxy WebLogicHost=otherserver.com\
>      WebLogicPort=7008
>     </Object>

Note: Parameters that are not required, such as PathTrim, can be used to further configure the way the `ppath` is passed through the Netscape Enterprise Server Plug-In. For a complete list of plug-in parameters, see

1. If you are proxying requests by MIME type, add any new MIME types referenced in the `obj.conf` file to the `MIME.types` file. You can add MIME types by using the Netscape server console or by editing the `MIME.types` file directly.

To directly edit the `MIME.types` file, open the file for edit and type the following line:

>     type=text/jsp        exts=jsp

Note: For NES 4.0 (iPlanet), instead of adding the MIME type for JSPs, change the existing MIME type from

>     magnus-internal/jsp

to

>     text/jsp.

To use the Netscape console, select Manage Preferences—> Mime Types, and make the additions or edits.

2. All requests with a designated MIME type extension (for example, `.jsp`) can be proxied to WebLogic Server, regardless of the URL. To proxy all requests of a certain file type to WebLogic Server:

1. In `obj.conf`, add a `Service` directive to the existing `default` `Object` definition. (`<Object name=default ...>`)

For example, to proxy all JSPs to a WebLogic Server instance, the following `Service` directive should be added after the last line that begins with:

`NameTrans fn=....`

and before the line that begins with:

`PathCheck`.

>     Service method="(GET|HEAD|POST|PUT)" type=text/jsp fn=wl_proxy\
>      WebLogicHost=192.1.1.4 WebLogicPort=7001 PathPrepend=/jspfiles

This `Service` directive proxies all files with the `.jsp` extension to the designated WebLogic Server, where they are served with a URL like this:

`http://WebLogic:7001/jspfiles/myfile.jsp`

The value of the PathPrepend parameter should correspond to the context root of a Web Application that is deployed on the WebLogic Server instance or cluster to which requests are proxied.

After adding entries for the Netscape Enterprise Server Plug-In, the default `Object` definition will be similar to the following example, with the additions shown in `bold`:

>     <Object name=default>
>     NameTrans fn=pfx2dir from=/ns-icons\
>      dir="c:/Netscape/SuiteSpot/ns-icons"
>     NameTrans fn=pfx2dir from=/mc-icons\
>      dir="c:/Netscape/SuiteSpot/ns-icons"
>     NameTrans fn="pfx2dir" from="/help" dir=\
>      "c:/Netscape/SuiteSpot/manual/https/ug"
>     NameTrans fn=document-root root="c:/Netscape/SuiteSpot/docs"
>     Service method="(GET|HEAD|POST|PUT)" type=text/jsp\
>      fn=wl_proxy WebLogicHost=localhost WebLogicPort=7001\  PathPrepend=/jspfiles
>     PathCheck fn=nt-uri-clean
>     PathCheck fn="check-acl" acl="default"
>     PathCheck fn=find-pathinfo
>     PathCheck fn=find-index index-names="index.html,home.html"
>     If a required parameter is missing from the configuration, when the object is invoked it issues an HTML error that notes the missing parameter from the configuration.

>     ObjectType fn=type-by-extension
>     ObjectType fn=force-type type=text/plain
>     Service method=(GET|HEAD) type=magnus-internal/imagemap\  fn=imagemap
>     Service method=(GET|HEAD) \
>      type=magnus-internal/directory fn=index-common
>     Service method=(GET|HEAD) \
>      type=*~magnus-internal/* fn=send-file
>     AddLog fn=flex-log name="access"
>     </Object>

2. Add a similar `Service` statement to the default object definition for all other MIME types that you want to proxy to WebLogic Server.
3. To configure proxy-by-MIME for the JSP,you must add the following entry to the mime.types file

`type=text/jsp exts=jsp`

For proxy-by-MIME to work properly you need to disable JAVA from the Sun One Web Server otherwise SUN One will try to serve all requests that end in *.jsp and will return a 404 error as it will fail to locate the resource under $doc_root.

To disable JAVA from the Sun One Web Server, comment out the following in the obj.conf file under the name="`default"#NameTrans fn="ntrans-j2ee" name="j2ee`" and restart the webserver.

3. Optionally, if you are proxying by path, enable HTTP-tunneling:

1. If you are using `weblogic.jar` and tunneling the t3 protocol, add the following object definition to the `obj.conf` file, substituting the WebLogic Server host name and the WebLogic Server port number, or the name of a WebLogic Cluster that you wish to handle HTTP tunneling requests.

`<Object name="tunnel" ppath="*/HTTPClnt*">
Service fn=wl_proxy WebLogicHost=192.192.1.4\ WebLogicPort=7001
</Object>`

2. If you are tunneling IIOP, which is the only protocol used by the WebLogic Server thin client, `wlclient.jar`, add the following object definition to the `obj.conf` file, substituting the WebLogic Server host name and the WebLogic Server port number, or the name of a WebLogic Cluster that you wish to handle HTTP tunneling requests.

`<Object name="tunnel" ppath="*/iiop*">
Service fn=wl_proxy WebLogicHost=192.192.1.4\ WebLogicPort=7001
</Object>`

4. Deploy and test the Netscape Enterprise Server Plug-In.

1. Start WebLogic Server.
2. Start Sun One Web Server. If NES is already running, you must either restart it or apply the new settings from the console in order for the new settings to take effect.
3. To test the Netscape Enterprise Server Plug-In, open a browser and set the URL to the Sun One Web Server + `/weblogic/`, which should bring up the default WebLogic Server HTML page, welcome file, or default servlet, as defined for the default Web Application as shown in this example:

`http://myenterprise.server.com/weblogic/`

For information on how to create a default Web Application, read Configuring Web Application Components at ../webapp/components.html.

## Guidelines for Modifying the obj.conf File

To use the Netscape Enterprise Server Plug-In, you must make several modifications to the NES `obj.conf` file. These modifications specify how requests are proxied to WebLogic Server. You can proxy requests by URL or by MIME type. The procedure for each is described in Installing and Configuring the Netscape Enterprise Server Plug-In.

The Netscape `obj.conf` file is very strict about the placement of text. To avoid problems, note the following regarding the `obj.conf` file:

- Eliminate extraneous leading and trailing white space. Extra white space can cause your Netscape server to fail.
- If you must enter more characters than you can fit on one line, place a backslash (`\`) at the end of that line and continue typing on the following line. The backslash directly appends the end of the first line to the beginning of the following line. If a space is necessary between the words that end the first line and begin the second line, be certain to use one space, either at the end of the first line (before the backslash), or at the beginning of the second line.
- Do not split attributes across multiple lines. (For example, all servers in a cluster must be listed in the same line, following `WebLogicCluster`.)

## Sample obj.conf File (Not Using a WebLogic Cluster)

Below is an example of lines that should be added to the `obj.conf` file if you are not using a cluster. You can use this example as a template that you can modify to suit your environment and server. Lines beginning with # are comments.

Note: Make sure that you do not include any extraneous white space in the `obj.conf` file. Copying and pasting from the samples below sometimes adds extra white space, which can create problems when reading the file.

You can read the full documentation on Enterprise Server configuration files in the Netscape Enterprise Server Plug-In documentation.

>     ## ------------- BEGIN SAMPLE OBJ.CONF CONFIGURATION  ---------
>     # (no cluster)

>     # The following line locates the NES library for loading at
>     # startup, and identifies which functions within the library are
>     # NES functions.  Verify the path to the library (the value
>     # of the shlib=<...> parameter) and that the file is
>     # readable, or the server fails to start.

>     Init fn="load-modules" funcs="wl_proxy,wl_init"\
>      shlib=/usr/local/netscape/plugins/libproxy.so
>     Init fn="wl_init"

>     # Configure which types of HTTP requests should be handled by the
>     # NES module (and, in turn, by WebLogic).  This is done
>     # with one or more "<Object>" tags as shown below.

>     # Here we configure the NES module to pass requests for
>     # "/weblogic" to a WebLogic Server listening at port 7001 on
>     # the host myweblogic.server.com.

>     <Object name="weblogic" ppath="*/weblogic/*">
>     Service fn=wl_proxy WebLogicHost=myweblogic.server.com\
>      WebLogicPort=7001 PathTrim="/weblogic"
>     </Object>

>     # Here we configure the plug-in so that requests that
>     # match "/servletimages/" is handled by the
>     # plug-in/WebLogic.

>     <Object name="si" ppath="*/servletimages/*">
>     Service fn=wl_proxy WebLogicHost=192.192.1.4 WebLogicPort=7001
>     </Object>

>     # This Object directive works by file extension rather than
>     # request path. To use this configuration, you must also add
>     # a line to the mime.types file:
>     #
>     # type=text/jsp             exts=jsp
>     #
>     # This configuration means that any file with the extension
>     # ".jsp" are proxied to WebLogic. Then you must add the
>     # Service line for this extension to the Object "default",
>     # which should already exist in your obj.conf file:

>     <Object name=default>
>     NameTrans fn=pfx2dir from=/ns-icons\
>      dir="c:/Netscape/SuiteSpot/ns-icons"
>     NameTrans fn=pfx2dir from=/mc-icons\
>      dir="c:/Netscape/SuiteSpot/ns-icons"
>     NameTrans fn="pfx2dir" from="/help" dir=\
>      "c:/Netscape/SuiteSpot/manual/https/ug"
>     NameTrans fn=document-root root="c:/Netscape/SuiteSpot/docs"
>     Service method="(GET|HEAD|POST|PUT)" type=text/jsp fn=wl_proxy\
>      WebLogicHost=localhost WebLogicPort=7001 PathPrepend=/jspfiles
>     PathCheck fn=nt-uri-clean
>     PathCheck fn="check-acl" acl="default"
>     PathCheck fn=find-pathinfo
>     PathCheck fn=find-index index-names="index.html,home.html"
>     ObjectType fn=type-by-extension
>     ObjectType fn=force-type type=text/plain
>     Service method=(GET|HEAD) type=magnus-internal/imagemap\  fn=imagemap
>     Service method=(GET|HEAD) \
>      type=magnus-internal/directory fn=index-common
>     Service method=(GET|HEAD) type=*~magnus-internal/* fn=send-file
>     AddLog fn=flex-log name="access"
>     </Object>

>     # The following directive enables HTTP-tunneling of the
>     # WebLogic protocol through the NES plug-in.

>     <Object name="tunnel" ppath="*/HTTPClnt*">
>     Service fn=wl_proxy WebLogicHost=192.192.1.4 WebLogicPort=7001
>     </Object>

>     #
>     ## ------------- END SAMPLE OBJ.CONF CONFIGURATION ---------

## Sample obj.conf File (Using a WebLogic Cluster)

Below is an example of lines that should be added to `obj.conf` if you are using a WebLogic Server cluster. You can use this example as a template that you can modify to suit your environment and server. Lines beginning with `#` are comments.

Note: Make sure that you do not include any extraneous white space in the `obj.conf` file. Copying and pasting from the samples below sometimes adds extra white space, which can create problems when reading the file.

Note: If you are proxying to more than one WebLogic Server cluster from a single Web server, each cluster must have a unique `CookieName` parameter, and each value should start with a unique string.

For more information, see the full documentation on Enterprise Server configuration files from Netscape.

>     ## ------------- BEGIN SAMPLE OBJ.CONF CONFIGURATION ---------
>     # (using a WebLogic Cluster)
>     #
>     # The following line locates the NES library for loading at
>     # startup, and identifies which functions within the library are
>     # NES functions.  Verify the path to the library (the value
>     # of the shlib=<...> parameter) and that the file is
>     # readable, or the server fails to start.

>     Init fn="load-modules" funcs="wl_proxy,wl_init"\
>      shlib=/usr/local/netscape/plugins/libproxy.so
>     Init fn="wl_init"

>     # Configure which types of HTTP requests should be handled by the
>     # NES module (and, in turn, by WebLogic).  This is done
>     # with one or more "<Object>" tags as shown below.

>     # Here we configure the NES module to pass requests for
>     # "/weblogic" to a cluster of WebLogic Servers.

>     <Object name="weblogic" ppath="*/weblogic/*">
>     Service fn=wl_proxy \
>      WebLogicCluster="myweblogic.com:7001,yourweblogic.com:7001,\
>      theirweblogic.com:7001" PathTrim="/weblogic"
>     </Object>

>     # Here we configure the plug-in so that requests that
>     # match "/servletimages/" are handled by the
>     # plug-in/WebLogic.

>     <Object name="si" ppath="*/servletimages/*">
>     Service fn=wl_proxy \
>     WebLogicCluster="myweblogic.com:7001,yourweblogic.com:7001,\
>      theirweblogic.com:7001"
>     </Object>

>     # This Object directive works by file extension rather than
>     # request path. To use this configuration, you must also add
>     # a line to the mime.types file:
>     #
>     # type=text/jsp             exts=jsp
>     #
>     # This configuration means that any file with the extension
>     # ".jsp" is proxied to WebLogic. Then you must add the
>     # Service line for this extension to the Object "default",
>     # which should already exist in your obj.conf file:

>     <Object name=default>
>     NameTrans fn=pfx2dir from=/ns-icons\
>      dir="c:/Netscape/SuiteSpot/ns-icons"
>     NameTrans fn=pfx2dir from=/mc-icons\
>      dir="c:/Netscape/SuiteSpot/ns-icons"
>     NameTrans fn="pfx2dir" from="/help" dir=\
>      "c:/Netscape/SuiteSpot/manual/https/ug"
>     NameTrans fn=document-root root="c:/Netscape/SuiteSpot/docs"
>     Service method="(GET|HEAD|POST|PUT)" type=text/jsp fn=wl_proxy\
>      WebLogicCluster="myweblogic.com:7001,yourweblogic.com:7001,\
>      theirweblogic.com:7001",PathPrepend=/jspfiles
>     PathCheck fn=nt-uri-clean
>     PathCheck fn="check-acl" acl="default"
>     PathCheck fn=find-pathinfo
>     PathCheck fn=find-index index-names="index.html,home.html"
>     ObjectType fn=type-by-extension
>     ObjectType fn=force-type type=text/plain
>     Service method=(GET|HEAD) type=magnus-internal/imagemap\  fn=imagemap
>     Service method=(GET|HEAD) \
>      type=magnus-internal/directory fn=index-common
>     Service method=(GET|HEAD) type=*~magnus-internal/* fn=send-file
>     AddLog fn=flex-log name="access"
>     </Object>

>     # The following directive enables HTTP-tunneling of the
>     # WebLogic protocol through the NES plug-in.

>     <Object name="tunnel" ppath="*/HTTPClnt*">
>     Service fn=wl_proxy WebLogicCluster="myweblogic.com:7001,\
>      yourweblogic.com:7001,theirweblogic.com:7001"
>     </Object>

>     #
>     ## ------------- END SAMPLE OBJ.CONF CONFIGURATION ---------

# Setting Up Perimeter Authentication

Use perimeter authentication to secure your WebLogic Server applications that are accessed via the Netscape Enterprise Server 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 Netscape Enterprise Server Plug-In. Create an Identity Assertion Provider that will safely secure your Plug-In as follows:

1. Create a custom Identity Assertion Provider for your WebLogic Server application. See How to Develop a Custom Identity Assertion Provider in Developing Security Providers for WebLogic Server.
2. Configure the custom Identity Assertion Provider to support the "Cert" token type and make it the active token type. See How to Create New Token Types in Developing Security Providers for WebLogic Server.
3. Set the `clientCertProxy` attribute to True in the `web.xml` deployment descriptor file for the Web application (or, if using a cluster, you can instead set the `ClientCertProxyEnabled` attribute to True for the whole cluster on the Administration Console Cluster-->Configuration-->General tab). See context-param in Developing Web Applications for WebLogic Server.
4. 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 Netscape Enterprise Server Plug-In is running. See Using Network Connection Filters in Programming WebLogic Security.

See Identity Assertion Providers in Developing Security Providers for WebLogic Server for more information about Identity Assertion Providers.

# Using SSL with the NES Plug-In

You can use the Secure Sockets Layer (SSL) protocol to protect the connection between the Netscape Enterprise Server Plug-In, and WebLogic Server. The SSL protocol provides confidentiality and integrity to the data passed between the Netscape Enterprise Server Plug-In and WebLogic Server.

The Netscape Enterprise Server 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 the SSL protocol will be used to protect the connection between the Netscape Enterprise Server Plug-In and WebLogic Server.

To use the SSL protocol between Netscape Enterprise Server Plug-In and WebLogic Server:

1. Configure WebLogic Server for SSL. For more information, see Configuring the SSL Protocol.
2. Configure the WebLogic Server SSL listen port. For more information, see Configuring the SSL Protocol.
3. Set the `WebLogicPort` parameter in the `Service` directive in the `obj.conf` file to the listen port configured in step 2.
4. Set the SecureProxy parameter in the `Service` directive in the `obj.conf` file to `ON`.
5. Web server plug-ins require a trusted Certificate Authority file in order to use SSL between the plug-in and WebLogic Server. Use Sun Microsystem's `keytool` utility to export a trusted Certificate Authority file from the `DemoTrust.jks` keystore file that resides in `BEA_HOME/weblogic81/server/lib`.

1. To extract the `wlsdemoca` file, for example, use the command:

>     keytool -export -file trustedcafile.der -keystore DemoTrust.jks -alias wlsdemoca

Change the alias name to obtain a different trusted CA file from the keystore.

To look at all of the keystore's trusted CA files, use:

>     keytool -list -keystore DemoTrust.jks

Press enter if prompted for password.

2. To convert the Certificate Authority file to `pem` format:

>     java utils.der2pem trustedcafile.der

6. Set additional parameters in the `Service` directive in the `obj.conf` file that define information about the SSL connection. For a complete list of parameters, see SSL Parameters for Web Server Plug-Ins.

# Connection Errors with Single Non-Clustered WebLogic Server Instances

If you are running a single WebLogic Server instance, the plug-in attempts to connect to that server which is defined with the WebLogicHost parameter. If the attempt fails, an `HTTP 503` error message is returned. The plug-in continues trying to connect to WebLogic Server until ConnectTimeoutSecs is exceeded.

# Connection Errors and Clustering Failover

When the Netscape Enterprise Server 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 Servers 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 4-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 possible problems with the host machine, networking problems, or other server failures.

Failure of all WebLogic Server instances to respond, could indicate that WebLogic Server is not running or is unavailable, a hung server, a database problem, or other application failure.

## The Dynamic Server List

When you specify a list of WebLogic Server instances in the `WebLogicCluster` parameter, 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, in the POST data, or by URL encoding, the session ID contains a reference to the specific server in which the session was originally established (called the primary server) and a reference to an additional server where the original session is replicated (called the secondary server). A request containing a cookie attempts to connect to the primary server. If that attempt fails, the request is routed to the secondary server. If both the primary and secondary servers fail, the session is lost and the plug-in attempts to make a fresh connection to another server in the dynamic cluster list. For more information, see Figure 4-1 Connection Failover.

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.

## Failover Behavior When Using Firewalls and Load Directors

In most configurations, the Netscape Enterprise Server Plug-In sends a request to the primary instance of a cluster. When that instance is unavailable, the request fails over to the secondary instance. However, in some configurations that use combinations of firewalls and load-directors, any one of the servers (firewall or load-directors) can accept the request and return a successful connection while the primary instance of WebLogic Server is unavailable. After attempting to direct the request to the primary instance of WebLogic Server (which is unavailable), the request is returned to the plug-in as "connection reset."

Requests running through combinations of firewalls (with or without load-directors) are handled by WebLogic Server. In other words, responses of `connection reset` fail over to a secondary instance of WebLogic Server. Because responses of `connection reset` fail over in these configurations, servlets must be idempotent. Otherwise duplicate processing of transactions may result.

Figure 4-1 Connection Failover

Notes:

The HTTP error code thrown by the plug-in depends on the situation. Plug-in will return the HTTP error code 500 in the following conditions:

- Neither `WebLogicCluster` nor `WebLogicPort` was specified in the `httpd.conf` file.
- Unable to resolve the `WebLogicHost` parameter specified in the `httpd.conf` file.
- Port number specified by `WebLogicPort,` in the `httpd.conf` file, exceeds 65535.
- Unsuccessful in parsing the request while applying the `PathTrim` property.
- The request header is of type Unknown Transfer-Encoding.
- Failed to read the chunked request.
- Encounetered an error reading `POST` data from client.
- Failed to open a temporary(temp) file.
- Failed to write `POST` data to the temp file.
- Encounetered an error reading `POST` data from the temp file.
- `POST` timed out.
- SSL was specified without the parameter `trustedCAFile`.

On the other hand, the HTTP error code 503 is returned when:

- The maximum number of retries is exceeded. This value is computed by dividing `ConnectTimeoutSecs` by `ConnectRetrySecs`.
- `Idempotent` is `OFF`.