Sun Java logo     Previous      Contents      Index      Next     

Sun logo
Sun Java(TM) System Directory Server 5.2 2005Q1 Administration Guide 

Chapter 12
Implementing Pass-Through Authentication

Pass-through authentication (PTA) is a mechanism by which one directory server consults another to authenticate bind requests. The PTA plug-in provides this functionality, allowing a directory server to accept simple bind operations (password based) for entries not stored in its local suffixes.

Directory Server uses PTA to allow you to administer your user and configuration directories on separate instances of Directory Server.


The PTA plug-in is not listed in Directory Server Console when you use the same server for your user directory and your configuration directory, but you may create it to use pass-through authentication.

This chapter describes the PTA plug-in in the following sections:

How Directory Server Uses PTA

If you install the configuration directory and the user directory on separate instances of Directory Server, the installation program automatically sets up PTA to allow the Configuration Administrator user (usually admin) to perform administrative duties.

PTA is required in this case because the admin user entry is stored under o=NetscapeRoot in the configuration directory. Therefore, attempts to bind to the user directory as admin would normally fail. PTA allows the user directory to transmit the credentials to the configuration directory which verifies them. The user directory then allows the admin user to bind.

The user directory in this example acts as the PTA server, that is, the server that passes through bind requests to another directory server. The configuration directory acts as the authenticating server, that is, the server that contains the entry and verifies the bind credentials of the requesting client.

You will also see the term PTA subtree used in this chapter. The pass-through authentication subtree is the subtree not present on the PTA server. When a user's bind DN contains this subtree, the user's credentials are passed on to the authenticating directory.

This sequence of steps shows how pass-through authentication works:

  1. You install the configuration directory server (authenticating directory) containing the pass-through authentication subtree o=NetscapeRoot on the host
  2. You install the user directory server (PTA directory) containing data in the dc=example,dc=com suffix on the host
  3. During the installation of the user directory, you are prompted to provide an LDAP URL that points to the configuration directory, for example:
  4. ldap://

  5. The installation program configures and enables the PTA plug-in in the user directory with the LDAP URL you provided.
  6. The user directory is now configured as a PTA directory. It will send all bind requests for entries whose DN contains o=NetscapeRoot to the configuration directory

  7. When installation is complete, the admin user attempts to bind to the user directory to begin creating the user data.
  8. The admin entry is stored in the configuration directory as uid=admin, ou=Administrators,ou=TopologyManagement,o=NetscapeRoot. So, the user directory passes the bind request through to the configuration directory as defined by the PTA plug-in configuration.

  9. The configuration directory authenticates the bind credentials, including the password, and sends the confirmation back to the user directory.
  10. The user directory allows the admin user to bind.

Configuring the PTA Plug-In

PTA plug-in configuration information is specified in the cn=Pass Through Authentication,cn=plugins,cn=config entry on the PTA server.

If you installed the user and configuration directories on different server instances, the PTA plug-in entry is automatically added to the user directory's configuration. If you installed both directories on the same instance, and you wish to perform pass-through authentication with other directories, you must first create the plug-in configuration entry.

Creating the Plug-In Configuration Entry

  1. Run the following command to create the plug-in configuration entry:
  2. ldapmodify -a -h PTAhost -p port -D "cn=Directory Manager" -w password
    dn: cn=Pass Through Authentication,cn=plugins,cn=config
    objectClass: top
    objectClass: nsSlapdPlugin
    objectClass: extensibleObject
    cn: Pass Through Authentication
    nsslapd-pluginPath: ServerRoot/lib/passthru-plugin.soextension
    nsslapd-pluginInitfunc: passthruauth_init
    nsslapd-pluginType: preoperation
    nsslapd-plugin-depends-on-type: database
    nsslapd-pluginId: passthruauth
    nsslapd-pluginVersion: 5.2
    nsslapd-pluginVendor: Sun Microsystems, Inc.
    nsslapd-pluginDescription: pass through authentication plugin
    nsslapd-pluginEnabled: on or off
    nsslapd-pluginarg0: ldap[s]://authenticatingHost[:port]/PTAsubtree options

    where ServerRoot depends on your installation and the extension is .sl on HP-UX, .so on all other UNIX platforms, and .dll on Windows.

    The plug-in argument specifies the LDAP URL identifying the hostname of the authenticating directory server, an optional port, and the PTA subtree. If no port is specified, the default port is 389 with LDAP and 636 with LDAPS. You may also set the optional connection parameters described in the following sections. If the PTAsubtree exists in the PTAhost, the plug-in will not pass the bind request to the authenticatingHost, and the bind will be processed locally without any pass-through.

  3. Restart the server as described in Starting and Stopping Directory Server.

Configuring PTA to Use a Secure Connection

Because the PTA plug-in must send bind credentials including the password to the authenticating directory, we recommend using a secure connection. To configure the PTA directory to communicate with the authenticating directory over SSL:

Setting the Optional Connection Parameters

The PTA plug-in arguments accept a set of optional connection parameters after the LDAP URL:

ldap[s]://host[:port]/subtree [maxconns,maxops,timeout,ldapver,connlife]

The parameters must be given in the order shown. Although these parameters are optional, if you specify one of them, you must specify them all. If you do not wish to customize all parameters, specify their default values given below. Make sure there is a space between the subtree parameter and the optional parameters.

You can configure the following optional parameters for each LDAP URL:

The following example of a PTA plug-in argument increases the number of connections to 10, but decreases the timeout to one minute (60 seconds). The default values are give for all other parameters:

ldaps:// 10,5,60,3,300

Specifying Multiple Servers and Subtrees

You may configure the PTA plug-in with multiple arguments to specify multiple authenticating servers, multiple PTA subtrees, or both. Each argument contains one LDAP URL and may have its own set of connection options.

When there are multiple authenticating servers for the same PTA subtree, they act as failover servers. The plug-in will establish connections to them in the order listed whenever a PTA connection reaches the timeout limit. If all connections time out, the authentication fails.

When there are multiple PTA subtrees defined, the plug-in will pass-through the authentication request to the corresponding server according to the bind DN. The following example shows four PTA plug-in arguments that define two PTA subtrees, each with a failover server for authentication and server-specific connection parameters:

nsslapd-pluginarg0: ldaps://
nsslapd-pluginarg1: ldaps://
nsslapd-pluginarg2: ldaps://,ou=People,
 dc=example,dc=com 10,10,300,3,300
nsslapd-pluginarg3: ldaps://,ou=People,
 dc=example,dc=com 3,5,300,3,300

You can also specify multiple servers by separating the host names by spaces, as shown in the following example:

nsslapd-pluginarg0: ldaps:// 10,10,60,3,300

Modifying the PTA Plug-In Configuration

You can reconfigure the PTA plug-in at any time to enable or disable it, or to change the authenticating hosts or PTA subtrees.

  1. Edit the PTA plug-in configuration entry (cn=Pass Through Authentication,cn=plugins,cn=config) to modify the nsslapd-pluginenabled and nsslapd-pluginargN attributes. You may use either the console or the ldapmodify utility to edit the configuration.
  2. For example, the following command will enable the PTA plug-in with SSL and the connection parameters shown above.

    dn: cn=Pass Through Authentication,cn=plugins,cn=config
    changetype: modify
    replace: nsslapd-pluginenabled
    nsslapd-pluginenabled: on
    replace: nsslapd-pluginarg0
    nsslapd-pluginarg0: ldaps://
     o=NetscapeRoot 10,10,60,3,300
    replace: nsslapd-pluginarg1
    nsslapd-pluginarg1: ldaps://
     o=NetscapeRoot 3,5,300,3,300

  3. Restart the server as described in Starting and Stopping Directory Server.

Previous      Contents      Index      Next     

Part No: 817-7613-10.   Copyright 2005 Sun Microsystems, Inc. All rights reserved.