Configuring the Gateway

When you install your directory server, the Netscape Directory Server gateway is also installed. This gateway allows users to access your directory tree from a forms-capable web browser. By using the gateway, users can add, delete, and modify directory data from a web browser. In short, the gateway is an HTTP to LDAP gateway.

After your directory server is installed, you must do the following to use the gateway:

Make your gateway known to a local web server.

Customize your gateway to support your local directory (see "Customizing Your Gateway").

Keep in mind that the directory server gateway can only provide access to directory entries that correspond to a single suffix. Therefore, if you have more than one suffix configured for your directory and you want to have entries from both suffixes accessible via the gateway, you will have to configure multiple directory server gateway instances. Additionally, each web server instance can be configured to support only one directory server gateway. To support multiple directory server gateway instances, you must also install and configure multiple web server instances.

Configuring a Web Server for Your Gateway

To allow users to access the gateway, do the following:

Make sure a web server such as the Netscape FastTrack Server is installed and configured on the same host the directory server is installed on. (The FastTrack server is included on the Netscape Directory Server product CD.)

Add an additional document directory to your web server so that the gateway's files can be accessed. From the server manager for your web server, do the following:

Go to Content Mgmt | Additional Document Directories.

In the URL prefix field, enter dshtml.

In the Map to Directory field, enter:

		<NSHOME>/slapd-<serverID>/dsgw/html

where <NSHOME> is the directory server's installation directory, and <serverID> is your directory server's server identifier.

Click OK.

Click Save and Apply.

Add an additional CGI directory so that the gateway's CGI programs are available. From your web server's server manager:

Go to Programs | CGI Directory.

In the URL prefix field, enter ds.

In the CGI directory field, enter:

		<NSHOME>/slapd-<serverID>/dsgw/bin

Click OK.

Click Save and Apply.

Unix only: Change the permissions of the gateway's cookie directory so that the web server can write to it:

Find out what user name your web server is running as. Go to System Settings|View Server Settings in the web server's server manager and note the value set for the User field. If this value is set to nobody, then you should double-check to make sure that the server is not, in fact, running as a named user. The easiest way to do this is to list the processes running on your machine and grep for http. For example, on Solaris you would enter:

		ps -ef | grep http

The process listing identifies the name the process is running as.

Go to:

		<NSHOME>/slapd-<serverID>/dsgw

Enter:

		# chown <uid> authck

where <uid> is the name you found in the User field.

You can now access your directory by opening the URL:

http://<webserver-host>:<port>/ds/search

where <webserver-host> is your web server's host name, and <port> is the port number that your web server is using. Note that you need to specify the port number only if your web server is not using the standard HTTP port number (80).

Setting the Preferred Language for the Netscape Client

When a user accesses information in the directory from a web browser, either through the directory server gateway or another HTTP-based LDAP interface, the browser provides information that indicates the best character set and collation order to use when transmitting information back to the browser. When using Netscape Communicator 4.x, the server automatically sends Unicode characters. When using Netscape Navigator 3.01, the server sends Latin-1 characters.

By default, the directory server is capable of handling 36 different languages. To expose this ability, you should have users configure their web browser to identify their preferred language. For non-English language display, you must also install a font on your system that is capable of displaying a non-English alphabet.

Customizing Your Gateway

After the gateway is installed, it is by default configured to use:

a standard set of locations and entry types

the suffix that you set when you configured your directory server

non-SSL communications

You can customize your local gateway to support your local directory by editing the parameters contained in:

	<NSHOME>\slapd-<serverID>\dsgw\config\dsgw.conf

For a description of the parameters available in this file, see "dsgw.conf Parameters".

To customize your gateway, consider:

whether you want your gateway to use SSL communications

what DN you will use for the directory manager, if any

what types of entries you want to be able to add using the gateway

what directory locations you want to appear in the gateway when you add entries

The following sections describe how to configure the gateway to address these issues.

When You Should Customize Your Gateway

Gateway customization is not generally required unless:

You want the gateway to use SSL to communicate with the directory server.

Your directory server is using some port other than the default (389).

You move your directory server from the original host it was installed on to some other host.

You want to be able to add entries using the gateway, in which case you must manipulate the location and newtype parameters (for more information, see "Using newtypes and locations Together"), or you add a new branch point in your directory that you want recognized by the gateway.

You want to use an entry other than the Unrestricted User (root DN) as the Directory Manager.

The user defined in dsgw.conf to be the Directory Manager is changed in the directory server after the gateway is installed.

In general, be aware that any changes in the directory server are not automatically reflected in dsgw.conf; you must explicitly change dsgw.conf to reflect any directory server configuration changes of the type noted above.

Customizing Your Gateway to Use SSL

When you install your directory server, your gateway is automatically configured to communicate with your server using the host name and non-SSL port number that you supplied to the directory server configuration screen. The installation script sets this information using the baseurl parameter. You do not need to change the value set for this parameter unless you want your gateway to use SSL communications.

Before the gateway can use SSL to communicate with your directory server, you must also enable SSL communications on your directory server. For information on enabling SSL on your directory server, see the Netscape Directory Server Administrator's Guide.

To cause your gateway to use SSL:

Change ldap to ldaps in the baseurl parameter value.

Change the port number that is specified on the baseurl parameter to the SSL port configured for your directory server.

Ensure that the gateway certificate database contains any server or Certificate Authority (CA) certificates needed to communicate with the directory server.

For example, if baseurl is set to:

	baseurl "ldap://dir.airius.com:389/o%3Dairius.com"

then to cause the gateway to use SSL communications to the well-known directory server SSL port number (636), change baseurl to:

	baseurl "ldaps://dir.airius.com:636/o%3Dairius.com"

Setting the Directory Manager

If a directory manager is configured for your gateway, then the gateway provides a button in the Authentication form that allows you to quickly authenticate as the directory manager (this button is displayed only if a directory manager is configured for the gateway). This section describes how to set up your directory manager and then configure your gateway to use the directory manager.

Note

The directory manager is by default set to be the root DN, but Netscape strongly recommends you change this to some other entry for security reasons. Also, if you did not configure a root DN when you installed your directory server, then a default directory manager is not configured for your gateway.

To set up the directory manager for the gateway:

Create an entry that you will use as the directory manager. When you create this entry, be sure to set a password for the entry. For information on creating entries in your directory, see the Netscape Directory Server Administrator's Guide.

Set the permissions for the directory manager such that it has read and write authority for the entries that you want it to be able to manage. Because forgotten passwords are likely to be a common problem with end-users, make sure you allow the directory manager write access to the userPassword attribute in those entries you want it to manage.

For information on setting permissions in your directory, see the Netscape Directory Server Administrator's Guide.

If necessary, change the dirmgr dsgw.conf parameter to refer to your directory manager's distinguished name.

Your gateway will now reference the correct DN when you authenticate as the directory manager. For information on authenticating as the directory manager from the gateway, see the online documentation that is available from within the gateway.

Customizing Types of Entries That Can Be Added Using the Gateway

When you add an entry using the gateway, the gateway provides a pop-up menu of the types of entries you can add.

You use one newtype dsgw.conf parameter to define each such type of entry. Each newtype parameter defines a specific type of entry, such as a person, group, or organizational unit.

Customizing DN Formats

When you add a person or NT person entry to the directory using the directory server gateway, you are by default prompted to create a UID-based DN. Although cn-based DNs are more traditional, use of UID-based DNs prevents naming colisions within your directory. This is because user IDs are unique by nature whereas common names are often duplicated within an organization.

You can modify the default DN format by editing the rdnattr variable within the newtype parameter. For example, to change the gateway configuration so that person entries are created using cn-based DNs rather than UID-based DNs, you would edit the

newtype orgperson "Person" uid people special

line in the dsgw.conf file to read

newtype orgperson "Person" cn people special

Customizing Locations

When you add an entry using the gateway, you first select the type of entry that you are adding, and then you select the location where you are adding the entry. The gateway provides a pop-up menu of these locations that allows you to avoid typing in long distinguished names.

You use one location dsgw.conf parameter to define each such location. You should define locations that represent the branch points in your directory, such as an organizational unit or a physical location. You can define a location for every branch point in your directory, although if your directory structure is complex, you may want to define branch points only for your most commonly used directory branches.

Note that the default locations defined in dsgw.conf are intended for the sample directory shipped with your directory server; they are unlikely to match the structure of your actual directory.

Using newtypes and locations Together

Before you can add a new entry to the gateway, you must map the entry type to a location where that type of entry can be placed.

The Default Behavior

The dsgw.conf file that is installed with your gateway has the following default newtype and location parameters:

location	country	"United States"	"c=US#"

location	org	"This Organization"	""

location 	groups	"Organizational Groups"	"ou=Groups"

location	acct	"Accounting"	"ou=Accounting"

location	hr	"Human Resources"	"ou=Human Resources"

location	pay	"Payroll"	"ou=Payroll"

location	pd 	"Product Development"	"ou=Product Development"

location	test 	"Product Testing"	"ou=Product Testing"

newtype 	orgperson	"Person"	cn	acct hr pay pd test

newtype 	NTperson	"NT Person"	cn	acct hr pay pd test

newtype	groupun	"Group"	cn	groups

newtype	orgunit	"Organizational Unit"	ou	org

newtype	org	"Organization"	o	country

Note

The location parameters must be placed before the newtype parameters in the dsgw.conf file.

These parameters allow you to create the following types of entries in the following locations:

The entry type . . .
Can be created at the locations. . .

Person
ou=Accounting, ou=Human Resources, ou=Payroll,
ou=Product Development, and ou=Product Testing. The remainder of the DN is the suffix you specified for your location-suffix parameter.

Group
ou=Groups. The remainder of the DN is the suffix you specified for your location-suffix field.

Organizational Unit
The suffix specified on the location-suffix parameter.

Organization
c=US.

The entry type . . .	Can be created at the locations. . .
Person	ou=Accounting, ou=Human Resources, ou=Payroll, ou=Product Development, and ou=Product Testing. The remainder of the DN is the suffix you specified for your location-suffix parameter.
Group	ou=Groups. The remainder of the DN is the suffix you specified for your location-suffix field.
Organizational Unit	The suffix specified on the location-suffix parameter.
Organization	c=US.

For example, suppose you want to create an entry that represents a person, and your location-suffix parameter is set to o=airius.com. Then you can use the gateway to create people in the following organizational units:

ou=Accounting, o=airius.com

ou=Human Resources, o=airius.com

ou=Payroll, o=airius.com

ou=Product Development, o=airius.com

ou=Product Testing, o=airius.com

Changing the Default Behavior

Suppose your directory does not have organizational units represented by Accounting, Human Resources, Payroll, Product Development, and Product Testing. Instead, your directory contains organizational units for Widget Dev 1, Widget Dev 2, Employee Relations, Senior Staff, and Facilities. Do the following:

Because the default organizational units do not exist in your directory, delete the following lines from dsgw.conf:

	location  acct 	"Accounting" 	"ou=Accounting"

	location  hr 	"Human Resources" 	"ou=Human Resources"

	location  pay 	"Payroll" 	"ou=Payroll"

	location  pd 	"Product Development"	"ou=Product Development"

	location  test 	"Product Testing" 	"ou=Product Testing"

Create the new locations using the dsgw.conf location parameter. For each location, be sure to specify a handle to be used on the newtype parameter. For example, create the following lines in dsgw.conf:

	location	wig1 	"Widget 1" 	"ou=Widget Dev 1"

	location 	wig2	"Widget 2" 	"ou=Widget Dev 2"

	location	er 	"ER" 	"ou=Employee Relations"

	location	staff 	"Senior Staff"	"ou=Senior Staff"

	location	fac 	"Facilities" 	"ou=Facilities"

Convert the following Person newtype line in dsgw.conf:

	newtype 	orgperson	"Person"	cn	acct hr pay pd test

to use the handles you defined in step 2. For example:

	newtype 	orgperson	"Person"	cn	wig1 wig2 er staff fac

When you add a person to your directory using the gateway, the gateway shows the following locations in the Locations pop-up menu:

	Widget 1

	Widget 2

	ER

	Senior Staff

	Facilities

dsgw.conf Parameters

dsgw.conf includes the following parameters:

Table 5.1 dsgw.conf parameters


Parameter	Description
baseurl	Specifies the server, port number, and search base the gateway uses to connect to your directory server.
dirmgr	Specifies the directory manager's distinguished name.
location-suffix	Identifies the suffix used for adding new entries to your directory.
securitypath	Identifies the location of your certificate database.
authlifetime	Specifies how long client authentication credentials are valid.
template	Maps specific object classes to internal templates.
newtype	Defines the types of entries that you can add to your directory using the gateway.
location	Defines the location choices selectable from the gateway when you add new entries.
vcard-property	Maps LDAP attribute names to vCard properties.

baseurl

Description

Specifies the host name and port number used to contact your directory server. This parameter also determines the search base used for searches performed from the gateway, and whether the gateway uses SSL to communicate with the directory server.

Format

baseurl [ldap | ldaps]://<host>:<port>/<search base>

Use ldap if you do not want the gateway to use SSL to communicate with the directory server, and use ldaps if you do want the gateway to use SSL.

<host> is the host name on which your directory server is installed.

<port> is the port number used by your directory server. Always specify a port number even if you are using the well-known ldap or ldaps port numbers (389 and 636, respectively).

<search base> is the distinguished name representing the point in your directory from which you want all searches to be performed. Normally, searchbase should be the same as your directory's suffix. Also, note that the installation process substitutes hexadecimal values for equal signs (=), spaces ( ), and commas (,) in the search base. It is recommended, but not required, that you use these values:

%3D is the equal sign (=)

%20 is a space ( )

%2C is a comma (,)

Example
The following example sets the base URL to use SSL communications for a server running on the well-known LDAP security port (636). The base search address is set to o=airius.com:

baseurl "ldaps://dirserver.airius.com:636/o%3Dairius.com"

dirmgr

Description

Specifies the distinguished name of the directory manager. This is the DN used to bind to the directory server when users authenticate as the directory manager from the gateway. Netscape recommends you use a DN other than the root DN for this purpose. It is intended that the DN specified here has read and write authority for the entire directory.

For information on authenticating as the directory manager from the gateway, see the online documentation that is available for the gateway. For information on the root DN and on setting permissions for the directory, see the Netscape Directory Server Administrator's Guide.

Format

dirmgr "<distinguished name>"

Example

dirmgr "cn=Directory Manager, o=airius.com"

location-suffix

Description

Identifies the suffix used to create new entries in the directory. The value specified here should match the value set for your directory server's Suffix parameter (you identified your directory's suffix when you first installed your server).

This value is appended to the DN field of the location parameter when you use the gateway to create new entries in your directory.

Format

location-suffix "<suffix>"

Example

location-suffix "o=airius.com"

securitypath

Description

Identifies the location of the certificate database used by the gateway when using SSL to communicate with your directory server. Do not change the value set on this parameter. Changing this parameter will break the directory server's ability to generate certificates for the gateway.

Format

securitypath <NSHOME>/alias/dsgw-<serverID>/cert.db

authlifetime

Description

Specifies the amount of time in seconds before a user's authentication expires in the gateway. When you use the gateway to authenticate to the directory server, the gateway will retain your authentication credentials for the amount of time specified on this parameter. Once your authentication credentials have expired, the gateway prompts you to reauthenticate.

For information on authenticating to the directory server using the gateway, see the online documentation that is available through the gateway.

Format

authlifetime <seconds>

Example

The following example causes user authentication to expire in two hours. This is the default expiration time:

	authlifetime 7200

template

Description

Maps specific object classes to internal gateway templates. These templates define how a specific object class such as a person, a group, or an organizational unit is displayed in the gateway.

newtype

Description

Defines the types of entries that can be added to your directory using the gateway. newtype also defines the locations in your directory to which the specified type of entry can be added. In order for a user to create the entry, you must define the corresponding location using the location parameter.

Format

newtype <template_name> "<friendly_name>" <rdnattr> <locations>

<template_name> corresponds to the name of a display-<template_name>.html file. These template files are stored in the same directory as the dsgw.conf file. The gateway uses these files to define how various types of entries are displayed when entries are being created or viewed:

orgperson--corresponds to the display-orgperson.html template. Defines how the gateway displays an entry of object class type inetOrgPerson.

groupun--corresponds to the display-groupun.html template. Defines how the gateway displays an entry of object class type groupOfUniqueNames.

orgunit--corresponds to the display-orgunit.html template. Defines how the gateway displays an entry of object class type organizationalUnit.

org--corresponds to the display-org.html template. Defines how the gateway displays an entry of object class type organization.

<friendly_name> is an arbitrary string that describes the entry. This string should be reasonably descriptive of the entry type because the gateway displays this string to users who are adding entries.

<rdnattr> is the attribute used to name entries of this type. For example, the default value for the rdnattr field for people entries is uid. This means that any people entries created using the gateway will have DNs of the following format:

	uid=<string>

You can modify the rdnattr field so that entries are named using a different attribute. For example, if you change the rdnattr of the newtype orgperson line from uid to cn, people entries created using the gateway will have cn-based DNs rather than the default UID-based DNs.

<locations> is a space-separated list of the locations where this type of entry can be added. The locations you place in this list must be identical to the <handle> specified on the corresponding location parameter.

Example

The following example allows you to add a person using the gateway. The template used is for an organizationalPerson. This example also allows you to use the gateway to add the entry to the Marketing subtree:

	newtype orgperson	"Person"	cn	marketing

For a more complete example of the newtype parameter, see "Using newtypes and locations Together".

location

Description

Defines the location choices selectable from the gateway when you add new entries. Each location parameter represents a branch point in your directory tree below which new entries can be added.

Format

location <handle> "<friendly name>" "<dn>"

<handle> is an arbitrary string used by the newtype parameter to map a type of entry to the locations where the entry can be created.

<friendly name> is an arbitrary string that represents the location. This string should be descriptive of the location because the gateway displays this string to users to represent the location.

<dn> is the distinguished name representing this branch point in your directory. If this value is not terminated with a pound sign, the value specified on the location-suffix parameter is appended to this value to build the fully qualified distinguished name. If dn is terminated with a pound sign (#), the value represented here is assumed to be a fully qualified distinguished name, and the pound sign is stripped from the distinguished name before the DN is used by the gateway.

Example

The following example defines an entry creation location in the Airius directory. This location corresponds to the Marketing organizational unit, and the remainder of the distinguished name is built from the value set on the location-suffix parameter:

	location marketing "Marketing Organization" "ou=Marketing"

The following example defines the same location, but it specifies the fully qualified distinguished name:

	location marketing "Marketing Organization" 

	 "ou=Marketing, o=airius.com#"

For a more complete example of the location parameter, see "Using newtypes and locations Together".

vcard-property

Description

The directory server gateway allows users to view vCards for person and NT person directory entries. The vCard and LDAP specifications define different labels to access information: vCards use properties and LDAP uses attributes. Therefore, you must map the vCard property names to the LDAP attribute names so that the directory server can locate the information for the vCard display. Use the vcard-property parameter to map vCard properties to LDAP attributes.

Format

vcard-property <vcardprop> <syntax> <ldapattr> [<ldapattr2>...]

<vcardprop> is the name of a vCard property. vCard properties that are currently mapped to LDAP attributes are:

FN--The Formatted Name property. All vCards must have an FN property. By default, FN is mapped to the cn attribute.

N--The Name property. By default, N is mapped to the sn and givenName attributes.

ORG--The ORG property may refer to the organizational name and units of the person or resource associated with the vCard. By default, ORG is mapped to the o and ou attributes.

ROLE--The ROLE property may refer to the role, occupation, or business category of the person or resource described by the vCard. By default, ROLE is mapped to the businessCategory attribute.

ADR;WORK--The work address of the of the person or resource described by the vCard. By default, ADR;WORK is mapped to the postalAddress attribute.

ADR;HOME--The home address of the of the person or resource described by the vCard. By default, ADR;HOME is mapped to the homePostalAddress attribute.

EMAIL;INTERNET--The email address of the person or resource described by the vCard. By default, EMAIL;INTERNET is mapped to the mail attribute.

TITLE--The TITLE property specifies the job title, functional position or function of the person or resource described by the vCard. By default, TITLE is mapped to the title attribute.

TEL;WORK--The business telephone number of the person or resource described by the vCard. By default, TEL;WORK is mapped to the telephoneNumber attribute.

TEL;FAX--The fax number of the person or resource described by the vCard. By default, TEL;FAX is mapped to the facsimileTelephoneNumber attribute.

TEL;CELL--The cellular telephone number of the person or resource described by the vCard. By default, TEL;CELL is mapped to the mobile attribute.

TEL;HOME--The residential telephone number of the person or resource described by the vCard. By default, TEL;HOME is mapped to the homePhone attribute.

NOTE--Provides any additional comments or information about the person or resource described by the vCard. By default, NOTE is mapped to the description attribute.

<syntax> is a string that that describes the nature of the vCard information. The following syntaxes are supported:

cis is used for simple strings, such as a person's name or telephone number

mls is used for multiline strings, such as a mailing address

<ldapattr> [<ldapattr2>...] is the attribute(s) to be mapped to the vCard property. You can change which attributes are mapped to a given vCard property. This is especially useful if you want to map a vCard property to a custom attribute.

Example

The following example changes the mapping of the NOTE property from the default description attribute to a custom attribute named hobbies:

	vcard-property NOTE mls hobbies

Museum

Configuring the Gateway

Configuring a Web Server for Your Gateway

Setting the Preferred Language for the Netscape Client

Displaying a Non-English Alphabet

Browser Configuration

Configuring Communicator 4.x

Configuring Navigator 3.01

Customizing Your Gateway

When You Should Customize Your Gateway

Customizing Your Gateway to Use SSL

Setting the Directory Manager

Customizing Types of Entries That Can Be Added Using the Gateway

Customizing DN Formats

Customizing Locations

Using newtypes and locations Together

The Default Behavior

Changing the Default Behavior

dsgw.conf Parameters

baseurl

dirmgr

location-suffix

securitypath

authlifetime

template

newtype

location

vcard-property