Chapter 1   Introduction


This chapter describes the gateway functionality introduced with release 4.0 of the directory server. Topics include:

• What is a Gateway?

• Directory Express and Default Gateway

• Support for Multiple Gateway Instances

• Gateway Localization

• Non-Anonymous Searching

• Compatibility with Existing Gateways

• Automatic Updates to Directory Configuration

What is a Gateway?

---

A gateway is an HTTP-to-LDAP client that lives on an HTTP server. Using special directives embedded in HTML files, a gateway allows users to access user directory data using any kind of web browser. Using a gateway does not require login to the iPlanet Console.

In release 4.0 of directory server, many gateway instances can be defined on one HTTP server, providing access to any number of directory servers. A gateway instance consists of:

• A .conf file, stored in /usr/iplanet/servers/dsgw/context, defining the context for gateway instance. for instance, dsgw.conf defines the dsgw gateway instance.

• An HTML directory for object class templates and other files containing gateway directives used to communicate with the LDAP server.

• A configuration directory for directory search, directory authentication, language files, and gateway scripts.

Gateways Installed with Directory Server 4.0

Two gateway instances are installed during directory server installation: the default gateway and Directory Express. Both gateways are configured to use the suffix set when the directory server was configured, and non-SSL (Secure Socket Layer) communications.

For more information, see Location of Gateway Files.

Default Gateway

The configuration file for the default gateway is at /usr/iplanet/servers/dsgw/context/dsgw.conf.

Following directory server installation, the default gateway can be accessed from http://adminhost:adminport/ or directly using this URL:

http://adminhost:adminport/dsgw/bin/search?context=dsgw

Directory Express

The configuration file for Directory Express is /usr/iplanet/servers/dsgw/context/pb.conf.

During directory server installation, Directory Express is configured to use as its HTTP server the iPlanet Administration server installed with the directory.

Following directory server installation, Directory Express can be accessed from http://adminhost:adminport/ or directly using this URL:

http://adminhost:adminport/dsgw/bin/lang?context=pb

HTTP Server Requirements for Gateways

A gateway instance requires an HTTP server that can communicate with the LDAP directory server.

For optimum performance and highest security, the gateway should be configured to run under a high-performance HTTP server, such as the iPlanet Web Server, Enterprise or FastTrack edition.

For more information, see HTTP Server Configuration.

Directory Express and Default Gateway

---

The following sections describe directory express and the default gateway in more detail.

Directory Express (pb.conf)

Directory Express is a basic directory lookup tool that can be used out of the box.

"> Table 1-1    Directory Express Search Result


"> Table 1-2    Directory Express Extended Search Results

Default Gateway (dsgw.conf)

In addition to the standard search form, the default gateway provides an advanced search form, a directory server authentication form, and a form for adding and modifying entries.

"> Table 1-3    Default Gateway



Support for Multiple Gateway Instances

---

Release 4.0 of the directory server supports multiple gateway instances. Many gateways can access directory data from the same HTTP server without conflict.

The .conf files defining the configuration of gateway instances are stored in /usr/iplanet/servers/dsgw/context. Within the .conf file are two parameters specifying the path names for the HTML and template files for the gateway. The following lines show the HTML and configuration directories specified in the pb.conf file:

htmldir      ../pbhtml
configdir       ../pbconfig

Specifying Gateway Configuration to Gateway CGIs

Information about which .conf file to use is communicated in the QUERY STRING using a GET, and through a hidden variable on a POST.

GET Operations (GCONTEXT)

In a GET operation, gateway CGIs get the gateway context from the QUERY STRING in the URL.

Use the GCONTEXT directive in all URLS to gateway CGIs. Embed <!--GCONTEXT --> after the CGI name, as shown in following example. This directive will be replaced by the current CGI's gateway context. The GCONTEXT directive is the only gateway directive that does not have to be at the beginning of the line. An example of embedding the GCONTEXT string in a link follows:

<a href=/dsgw/bin/lang?<!-- GCONTEXT -->&file=auth.html>click</a>

---

Note	In Directory Server Gateway 3.x, CGIs passed their arguments using PATH_INFO. In 4.0, PATH_INFO is replaced by the QUERY_STRING, which works better with the Japanese version of Windows NT, and is functionally equivalent.

---

POST Operations (PCONTEXT)

In a POST operation, the CGI posts to the gateway instance specified by a hidden variable on an HTML form. Each POST operation to a gateway CGI in an HTML form must use the PCONTEXT directive so that CGIs can pass the gateway instance to the next page and maintain the state.

For CGI invocations using a POST, put <!-- PCONTEXT --> at the beginning of a line. For example, you can specify PCONTEXT in an HTML form as follows:

<form method=post action=/dsgw/bin/dosearch>
<input type=hidden name=dn value="">
<!-- PCONTEXT -->
</form>

For more information about content-related directives, see "Context-Related Directives" on page 89.

URLs for Gateway Access

The URL customers use to access a 4.0 gateway differs from the URL customers use to access a 3.x gateway.

Release 4.0

To get to a 4.0 gateway, users enter the following URL:

http://adminhost:adminport/dsgw/bin/lang?context=<context>

The default gateway and Directory Express are available from the page for the iPlanet Administration server (http://host:port)

Release 3.x

To get to a 3.x gateway, users enter the following URL:

http://host:port/dshtml

Gateway Localization

---

The gateway is designed to allow support for clients in multiple locales. The following sections describe the different locales and characters sets supported by the gateway.

Gateway Locales

Release 4.0 of the gateway is localized for English, Japanese, French, Spanish, and German. You can configure the gateway to support additional locales.

Language files are stored in /usr/iplanet/servers/dsgw/html/lang and /usr/iplanet/servers/dsgw/config/lang, where lang is defined in RFC1766.

For example, language files for Japanese are stored in /usr/iplanet/servers/dsgw/html/ja and /usr/iplanet/servers/dsgw/config/ja[true]).

Support for the character sets necessary to render a particular locale (language) must be available in the browser's configuration.

Character Sets

Release 4.0 of the gateway supports Unicode (specifically, the UTF-8 character set), the character set containing all of the world's languages. However, Unicode or any character set specified in the gateway's .conf file, can be overridden by the HTTP Accept-charset header sent by the gateway client or by a character set created for a specific language.

For more information about gateway character sets, see How the Gateway Selects a Character Set.

Non-Anonymous Searching

---

Release 3.0 of the gateway allows anonymous searching only. This provides basic permissions for accessing information in the user directory.

The release 4.0 gateway provides the same functionality but in addition supports non-anonymous searching. A bind DN and bind password, stored in a binddnfile, can be set up for users to authenticate to the directory server. User permissions for directory access can be defined in the iPlanet Console.

If the directory server contains authentication credentials for a user, these override the bind DN and bind password in the gateway's binndnfile. When authentication credentials expire or are invalid, the gateway attempts to authenticate the user to the directory using the binddnfile. When no binddnfile is specified, the gateway instance binds anonymously.

binddnfile

The location of the binddnfile containing bind DNs and bind passwords for individual users and groups of users is specified in the gateway's .conf file.

The binddnfile contains highly sensitive information. Do not store the binddnfile under /usr/iplanet/servers/dsgw or in any directory that is served up over HTTP (for instance, /bin/slapd/server is a good place to store the binddnfile).

Compatibility with Existing Gateways

---

Release 4.0 of the directory server is compatible with previous versions of the gateway, including release 3.x. Although the HTML files and gateway CGIs are not interchangeable, a 3.x gateway can access a 4.0 directory server, and a 4.0 gateway can access a 3.x directory server.

It is not necessary to upgrade a 3.x gateway to release 4.0, however a script is available to complete this task. On UNIX and NT systems, this migration occurs automatically when a directory server is migrated from release 3.x to release 4.0.

The gateway migration script is described in Migrating 3.x Default Gateways to Release 4.0.

Directory server migration is described in the Release Notes for Directory Server 4.0

Automatic Updates to Directory Configuration

---

A script that updates gateway instances with changes to directory server configuration, updatedsgw, is included with the directory server installation. This script searches /usr/iplanet/servers/dsgw/context for gateway instances that match the directory server host and port.

The updatedsgw script runs automatically for gateways installed on the iPlanet Administration server managing the directory server instance. When the server port or root DN (or other settings, such as directory manager) for a directory server instance is changed, the iPlanet Administration server managing the directory server instance runs the updatedsgw script.

For more information, see Updating the Gateway with Changes to Directory Server Configuration.