Chapter 16
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 database.
iPlanet Directory Server 5.1 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 5.1 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 directory server, that is, the server that passes through bind requests to another directory server. The configuration directory acts as the authenticating directory, that is, the server that contains the entry and verifies the bind credentials of the requesting client.
You will also see the term pass-through subtree used in this chapter. The pass-through subtree is the subtree not present on the PTA directory. When a user's bind DN contains this subtree, the user's credentials are passed on to the authenticating directory.
|
Note
|
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.
|
Here's how pass-through authenticationworks:
You install the configuration directory server (authenticating directory) on Machine A.
Server Name: configdir.siroe.com
Suffix: o=NetscapeRoot
You install the user directory server (PTA directory) on Machine B.
Server Name: userdir.siroe.com
Suffix: dc=siroe,dc=com
During the installation of the user directory on Machine B, you are prompted to provide an LDAP URL. This URL points to the configuration directory on Machine A.
The installation program adds an entry to the dse.ldif file on the user directory that enables the PTA plug-in.
-
This entry contains the LDAP URL you provided. For example:
dn: cn=Pass Through Authentication,cn=plugins,
objectClass: top
objectClass: nsSlapdPlugin
objectClass: extensibleObject
cn: Pass Through Authentication
nsslapd-pluginPath: installDir/lib/passthru-plugin.so
nsslapd-pluginInitfunc: passthruauth_init
nsslapd-pluginType: preoperation
nsslapd-pluginEnabled: on
nsslapd-pluginarg0: ldap://config.siroe.com/ou=NetscapeRoot
nsslapd-plugin-depends-on-type: database
nsslapd-pluginId: passthruauth
nsslapd-pluginVersion: 5.0
nsslapd-pluginVendor: Sun | Netscape Alliance
nsslapd-pluginDescription: pass through authentication plugin
-
The user directory is now configured to send all bind requests for entries whose DN contains o=NetscapeRoot to the configuration directory configdir.siroe.com.
When installation is complete, the admin user attempts to connect to the user directory to begin adding users.
The setup program adds the admin user's entry to the directory as uid=admin, 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 user's credentials and sends the information back to the user directory.
The user directory allows the admin user to bind.
PTA Plug-In Syntax
PTA plug-in configuration information is specified in the
cn=Pass Through Authentication,cn=plugins,cn=config entry in the dse.ldif file on the PTA directory (the user directory configured to pass through bind requests to the authenticating directory) using the syntax described in this section.
dn: cn=Pass Through Authentication,cn=plugins,cn=config
objectClass: top
objectClass: nsSlapdPlugin
objectClass: extensibleObject
cn: Pass Through Authentication
nsslapd-pluginPath: installDir/lib/passthru-plugin.extension
nsslapd-pluginInitfunc: passthruauth_init
nsslapd-pluginType: preoperation
nsslapd-pluginEnabled: state
nsslapd-pluginarg0: ldap|ldaps://authDS/subtree [maxconns,maxops,timeout,ldver,connlifetime]
The variable components of the PTA plug-in syntax are described in Table 16-1.
|
Note
|
The LDAP URL (ldap|ldaps://authDS/subtree) must be separated from the optional parameters (maxconns, maxops, timeout, ldver, connlifetime) by a single space.
If you explicitly define any of the optional parameters, you must define all of them, even if you specify only the default values.
You can specify several authenticating directories or subtrees by incrementing the nsslapd-pluginarg attribute suffix by 1 each time. This is illustrated in "Specifying Multiple Authenticating Directory Servers".
|
The optional parameters are described in the following table in the order inwhich they appear in the syntax.
Table 16-1 PTA Plug-In Parameters
|
Variable
|
Definition
|
|
state
|
Defines whether the plug-in is enabled or disabled. Acceptable values are on or off . See "Turning the Plug-in On or Off" for more information.
|
|
extension
|
File extension for the plug-in. The extension is always .sl on HP-UX, .so on all other UNIX platforms, and .dll on Windows NT.
|
|
ldap|ldaps
|
Defines whether SSL is used for communication between the two directory servers. See "Configuring the Servers to Use a Secure Connection" for more information.
|
|
authDS
|
The authenticating directory hostname. You can specify the port number of the directory server by adding a colon and then the port number. For example:
ldap://dirserver.siroe.com:390/
If you do not specify the port number, the PTA server attempts to connect using:
See "Specifying the Authenticating Directory Server" for more information.
|
|
subtree
|
The pass-through subtree. The PTA directory server passes through bind requests to the authenticating directory server from all clients whose DN is in this subtree.
See "Specifying the Pass-Through Subtree" for more information.
|
|
maxconns
|
Optional. The maximum number of connections the PTA directory can simultaneously open to the authenticating directory. The default is 3.
See "Configuring the Optional Parameters" for more information.
|
|
maxops
|
Optional. The maximum number of simultaneous operations (usually bind requests) the PTA directory can send to the authenticating directory within a single connection. The default is 5.
See "Configuring the Optional Parameters" for more information.
|
|
timeout
|
Optional. The time limit, in seconds, that the PTA directory waits for a response from the authenticating directory server. If this timeout is exceeded, the server returns an error to the client.
The default is 300 seconds (five minutes). Specify zero (0) to indicate no time limit should be enforced.
See "Configuring the Optional Parameters" for more information.
|
|
ldver
|
Optional. The version of the LDAP protocol used to connect to the authenticating directory. iPlanet Directory Server supports LDAP version 2 and 3. The default is version 3.
See "Configuring the Optional Parameters" for more information.
|
|
connlifetime
|
Optional. The time limit, in seconds, within which a connection may be used. If a bind request is initiated by a client after this time has expired, the server closes the connection and opens a new connection to the authenticating directory. The server will not close the connection unless a bind request is initiated and the directory determines the connection lifetime has been exceeded.
If you do not specify this option, or if only one host is listed, no connection lifetime will be enforced. If two or more hosts are listed, the default is 300 seconds (five minutes).
See "Configuring the Optional Parameters" for more information.
|
Configuring the PTA Plug-In
The only method for configuring the PTA plug-in is to modify the entry
cn=Pass Through Authentication,cn=plugins,cn=config in the dse.ldif file. To modify the dse.ldif file, you must proceed as follows:
Use the ldapmodify command to modify cn=Pass Through Authentication,cn=plugins,cn=config
Restart Directory Server.
Before you configure any of the parameters discussed in this section, the PTA plug-in entry must be present in the dse.ldif file. If this entry does not exist, you must create it with the appropriate syntax, as described in "PTA Plug-In Syntax".
|
Note
|
If you installed the user and configuration directories on different instances of the directory, the PTA plug-in entry is automatically added to the user directory's dse.ldif file. If you installed the user and configuration directories on the same instance, the syntax is not automatically added and you need to add it manually.
|
This section provides information about configuring the plug-in in the following sections:
Turning the Plug-in On or Off
To turn the PTA plug-in on from the command line:
Create an LDIF file that contains the following LDIF update statements:
dn: cn=Pass Through Authentication,cn=plugins,cn=config
cn: Pass Through Authentication
changetype: modify
replace: nsslapd-pluginenabled
nsslapd-pluginenabled: on
Use the ldapmodify command to import the LDIF file into the directory.
-
For detailed information on the ldapmodify command, refer to iPlanet Directory Server Configuration, Command, and File Reference.
When you enable the plug-in, you must also check that the plug-in initialization function is properly defined.
-
The entry cn=Pass Through Authentication,cn=plugins,cn=config should contain the following attribute-value pairs:
nsslapd-pluginPath: installDir/lib/passthru-plugin.extension
nsslapd-pluginInitfunc: passthruauth_init
-
where extension is always .sl on HP-UX, .so on all other UNIX platforms, and .dll on Windows NT.
Restart the server.
-
For information on restarting the server, refer to "Starting and Stopping the Directory Server," on page 35.
To disable the plug-in, change the LDIF update statements to delete the nsslapd-pluginenabled: on statement, and add the nsslapd-pluginenabled: off statement. Whenever you enable or disable the PTA plug-in from the command line, you must restart the server.
Configuring the Servers to Use a Secure Connection
You can configure the PTA directory to communicate with the authenticating directory over SSL. You do this by specifying LDAPS in the LDAP URL of the PTA directory.
To configure the PTA directory and authenticating directory to use SSL:
Create an LDIF file that contains the following LDIF update statements:
dn: cn=Pass Through Authentication,cn=plugins,cn=config
cn: Pass Through Authentication
changetype: modify
replace: nsslapd-pluginarg0
nsslapd-pluginarg0: ldaps://authDS/subtree [optional_parameters]
-
For information on the variable components in this sytax, refer to "PTA Plug-In Parameters".
Use the ldapmodify command to import the LDIF file into the directory.
Restart the server.
-
For information on restarting the server, refer to "Starting and Stopping the Directory Server," on page 35.
Specifying the Authenticating Directory Server
The authenticating directory contains the bind credentials for the entry with which the client is attempting to bind. The PTA directory passes the bind request to the host you define as the authenticating directory. You specify the authenticating directory server by replacing authDS in the LDAP URL of the PTA directory with the authenticating directory's hostname.
To specify the authenticating directory for PTA:
Create an LDIF file that contains the following LDIF update statements:
dn: cn=Pass Through Authentication,cn=plugins,cn=config
cn: Pass Through Authentication
changetype: add
add: nsslapd-pluginarg0
nsslapd-pluginarg0: ldap://authDS/subtree [optional_parameters]
-
Optionally, you can include a colon followed by a port number. If you do not specify the port number, the PTA directory server attempts to connect using:
-
For example, you could set the value of the nsslapd-pluginarg0 attribute to:
-
"ldap://dirserver.siroe.com:389/subtree [Parameters]"
-
For information on the variable components in this sytax, refer to "PTA Plug-In Parameters".
Use the ldapmodify command to import the LDIF file into the directory.
Restart the server.
-
For information on restarting the server, refer to "Starting and Stopping the Directory Server," on page 35.
Specifying the Pass-Through Subtree
The PTA directory passes through bind requests to the authenticating directory from all clients whose DN is defined in the pass-through subtree. You specify the subtree by replacing the subtree parameter in the LDAP URL of the PTA directory.
The pass-through subtree must not exist in the PTA directory. If it does, the PTA directory attempts to resolve bind requests using its own directory contents and the binds fail.
To specify the pass-through subtree:
Create an LDIF file that contains the following LDIF update statements:
dn: cn=Pass Through Authentication,cn=plugins,cn=config
cn: Pass Through Authentication
changetype: add
add: nsslapd-pluginarg0
nsslapd-pluginarg0: ldap://authDS/subtree [optional_parameters]
-
For example, you could set the value of the nsslapd-pluginarg0 attribute to:
-
"ldap://dirserver.siroe.com/o=NetscapeRoot [Parameters]"
-
For information on the variable components in this sytax, refer to "PTA Plug-In Parameters".
Use the ldapmodify command to import the LDIF file into the directory.
Restart the server.
-
For information on restarting the server, refer to "Starting and Stopping the Directory Server," on page 35.
Configuring the Optional Parameters
You can configure the following optional parameters for the PTA plug-in:
The maximum number of connections the PTA directory server can open simultaneously to the authenticating directory, represented by maxconns in the PTA syntax.The default value is 3.
The maximum number of bind requests the PTA directory server can send simultaneously to the authenticating directory server within a single connection. In the PTA syntax, this parameter is represented as maxops. The default is value is 5.
The time limit you want the PTA directory server to wait for a response from the authenticating directory server. In the PTA syntax, this parameter is represented as timeout. The default value is 300 seconds (five minutes).
The version of the LDAP protocol you want the PTA directory server to use to connect to the authenticating directory server. In the PTA syntax, this parameter is represented as ldver. The default is LDAPv3.
The time limit in seconds within which a connection may be used. If a bind request is initiated by a client after this time has expired, the server closes the connection and opens a new connection to the authenticating directory server. 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 directory server is listed in the authDS parameter, no time limit will be enforced. If two or more hosts are listed, the default is 300 seconds (five minutes). In the PTA syntax, this parameter is represented as connlifetime.
|
Note
|
Although these parameters are optional, if you specify one of them, you need to specify them all, even if you use the default values.
|
Create an LDIF file that contains the following LDIF update statements:
dn: cn=Pass Through Authentication,cn=plugins,cn=config
cn: Pass Through Authentication
changetype: add
add: nsslapd-pluginarg0
nsslapd-pluginarg0: ldap://authDS/subtree [maxconns,maxops,timeout,ldver,connlifetime]
-
Make sure there is a space between the subtree parameter, and the optional parameters.
-
For example, you could set the value of the nsslapd-pluginarg0 attribute to:
-
"ldap://dirserver.siroe.com/o=NetscapeRoot 3,5,300,3,300"
-
In this example, each of the optional parameters is set to its default value.
Use the ldapmodify command to import the LDIF file into the directory.
Restart the server.
-
For information on restarting the server, refer to "Starting and Stopping the Directory Server," on page 35.
PTA Plug-In Syntax Examples
This section contains the following examples of PTA plug-in syntax in the dse.ldif file:
Specifying One Authenticating Directory Server and One Subtree
This example configures the PTA plug-in to accept all defaults for the optional variables. This configuration causes the PTA directory server to connect to the authenticating directory server for all bind requests to the o=NetscapeRoot subtree. The hostname of the authenticating directory server is config-dir.siroe.com.
dn: cn=Pass Through Authentication,cn=plugins,cn=config
objectClass: top
objectClass: nsSlapdPlugin
objectClass: extensibleObject
cn: Pass Through Authentication
nsslapd-pluginPath: installDir/lib/passthru-plugin.so
nsslapd-pluginInitfunc: passthruauth_init
nsslapd-pluginType: preoperation
nsslapd-pluginEnabled: on
nsslapd-pluginarg0: ldap://config-dir.siroe.com/ou=NetscapeRoot
nsslapd-plugin-depends-on-type: database
nsslapd-pluginId: passthruauth
nsslapd-pluginVersion: 5.0
nsslapd-pluginVendor: Sun | Netscape Alliance
nsslapd-pluginDescription: pass through authentication plugin
Specifying Multiple Authenticating Directory Servers
If the connection between the PTA directory server and the authenticating directory server is broken or the connection cannot be opened, the PTA directory server sends the request to the next server specified (if any). You can specify as many authenticating directory servers as required.
dn: cn=Pass Through Authentication,cn=plugins,cn=config
objectClass: top
objectClass: nsSlapdPlugin
objectClass: extensibleObject
cn: Pass Through Authentication
nsslapd-pluginPath: installDir/lib/passthru-plugin.so
nsslapd-pluginInitfunc: passthruauth_init
nsslapd-pluginType: preoperation
nsslapd-pluginEnabled: on
nsslapd-pluginarg0: ldap://config-dir.siroe.com/ou=NetscapeRoot
nsslapd-pluginarg1: ldap://config2-dir.siroe.com/ou=NetscapeRoot
nsslapd-plugin-depends-on-type: database
nsslapd-pluginId: passthruauth
nsslapd-pluginVersion: 5.0
nsslapd-pluginVendor: Sun | Netscape Alliance
nsslapd-pluginDescription: pass through authentication plugin
Specifying One Authenticating Directory Server and Multiple Subtrees
The following example configures the PTA directory server to pass through bind requests for more than one subtree (using parameter defaults):
dn: cn=Pass Through Authentication,cn=plugins,cn=config
objectClass: top
objectClass: nsSlapdPlugin
objectClass: extensibleObject
cn: Pass Through Authentication
nsslapd-pluginPath: installDir/lib/passthru-plugin.so
nsslapd-pluginInitfunc: passthruauth_init
nsslapd-pluginType: preoperation
nsslapd-pluginEnabled: on
nsslapd-pluginarg0: ldap://config-dir.siroe.com/ou=NetscapeRoot
nsslapd-pluginarg1: ldap://config-dir.siroe.com/dc=siroe,dc=com
nsslapd-plugin-depends-on-type: database
nsslapd-pluginId: passthruauth
nsslapd-pluginVersion: 5.0
nsslapd-pluginVendor: Sun | Netscape Alliance
nsslapd-pluginDescription: pass through authentication plugin
Using Non-Default Parameter Values
This example uses a non-default value (10) only for the maximum number of connections parameter maxconns. Each of the other parameters is set to its default value. However, because one parameter is specified, all parameters must be defined explicitly in the syntax.
dn: cn=Pass Through Authentication,cn=plugins,cn=config
objectClass: top
objectClass: nsSlapdPlugin
objectClass: extensibleObject
cn: Pass Through Authentication
nsslapd-pluginPath: installDir/lib/passthru-plugin.so
nsslapd-pluginInitfunc: passthruauth_init
nsslapd-pluginType: preoperation
nsslapd-pluginEnabled: on
nsslapd-pluginarg0: ldap://config-dir.siroe.com/ou=NetscapeRoot 10,5,300,3,300
nsslapd-plugin-depends-on-type: database
nsslapd-pluginId: passthruauth
nsslapd-pluginVersion: 5.0
nsslapd-pluginVendor: Sun | Netscape Alliance
nsslapd-pluginDescription: pass through authentication plugin
Specifying Different Optional Parameters and Subtrees for Different Authenticating Directory Servers
If you want to specify a different pass-through subtree and optional parameter values for each authenticating directory server, you must specify more than one LDAP URL/optional parameters pair. Separate the LDAP URL/optional parameter pairs with a single space as follows.
dn: cn=Pass Through Authentication,cn=plugins,cn=config
objectClass: top
objectClass: nsSlapdPlugin
objectClass: extensibleObject
cn: Pass Through Authentication
nsslapd-pluginPath: installDir/lib/passthru-plugin.so
nsslapd-pluginInitfunc: passthruauth_init
nsslapd-pluginType: preoperation
nsslapd-pluginEnabled: on
nsslapd-pluginarg0: ldap://config-dir.siroe.com/ou=NetscapeRoot 7,7,300,3,300
nsslapd-pluginarg1: ldap://config2-dir.siroe.com/dc=siroe,dc=com 7,7,300,3,300
nsslapd-plugin-depends-on-type: database
nsslapd-pluginId: passthruauth
nsslapd-pluginVersion: 5.0
nsslapd-pluginVendor: Sun | Netscape Alliance
nsslapd-pluginDescription: pass through authentication plugin