|
| Sun ONE Directory Server Administration Guide |
Chapter 14 Using the Pass-Through Authentication Plug-In
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.
Sun ONE Directory Server 5.2 uses PTA to allow you to administer your user and configuration directories on separate instances of Directory Server.
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 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:
- You install the configuration directory server (authenticating directory) containing the pass-through subtree o=NetscapeRoot on the host configdir.example.com.
- You install the user directory server (PTA directory) containing data in the dc=example,dc=com suffix on the host userdir.example.com.
- During the installation of the user directory, you are prompted to provide an LDAP URL that points to the configuration directory server, for example:
- The installation program configures and enables the PTA plug-in in the user directory with the LDAP URL you provided.
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 configdir.example.com.
- When installation is complete, the admin user attempts to bind to the user directory to begin creating the user data.
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.
- The configuration directory authenticates the bind credentials, including the password, and sends the confirmation back to the user directory.
- 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 the 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
- Run the following command to create the plug-in configuration entry:
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.extension
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.
- Restart the server as described in "Starting and Stopping the 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:
- Configure and enable SSL in both the PTA and authenticating directories, as described in Chapter 11 "Implementing Security."
- Create or modify the PTA plug-in configuration to use LDAPS and the secure port in the LDAP URL, for example:
Setting the Optional Connection Parameters
The PTA plug-in arguments accept a set of optional connection parameters after the LDAP URL:
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:
- maxconns - The maximum number of connections the PTA server can open simultaneously to the authenticating server. This parameter limits the number of simultaneous binds that can be passed-through to the authenticating server. The default value is 3.
- maxops - The maximum number of bind requests the PTA directory server can send simultaneously to the authenticating directory server within a single connection. This parameter further limits the number of simultaneous pass-through authentications. The default is value is 5.
- timeout - The maximum delay in seconds that you want the PTA server to wait for a response from the authenticating server. The default value is 300 seconds (five minutes).
- ldapver - The version of the LDAP protocol you want the PTA server to use when connecting to the authenticating server. The allowed values are 2 for LDAPv2 and 3 for LDAPv3The default value is 3.
- connlife - The time limit in seconds within which the PTA server will reuse a connection to the authenticating server. If a bind in the PTA subtree is requested by a client after this time has expired, the server closes the PTA connection and opens a new one. The server will not close the connection unless a bind request is initiated and the server determines the timeout has been exceeded. If you do not specify this option, or if only one authenticating server is listed in the LDAP URL, no time limit will be enforced. If two or more hosts are listed, the default is 300 seconds (five minutes).
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:
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://configdir.example.com/o=NetscapeRoot
10,10,60,3,300
nsslapd-pluginarg1: ldaps://configbak.example.com/o=NetscapeRoot
3,5,300,3,300
nsslapd-pluginarg2: ldaps://east.example.com/ou=East,ou=People,
dc=example,dc=com 10,10,300,3,300
nsslapd-pluginarg3: ldaps://eastbak.example.com/ou=East,ou=People,
dc=example,dc=com 3,5,300,3,300Modifying 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.
- 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.
For example, the following command will enable the PTA plug-in with SSL and the connection parameters shown above.
changetype: modify
replace: nsslapd-pluginenabled
nsslapd-pluginenabled: on
-
replace: nsslapd-pluginarg0
nsslapd-pluginarg0: ldaps://configdir.example.com:636/
o=NetscapeRoot 10,10,60,3,300
-
replace: nsslapd-pluginarg1
nsslapd-pluginarg1: ldaps://configbak.example.com:636/
o=NetscapeRoot 3,5,300,3,300
^D
- Restart the server as described in "Starting and Stopping the Directory Server".