Show Table of Contents

19.12. Using Pass-Through Authentication
Pass-through authentication (PTA) is a mechanism which allows one Red Hat Directory Server instance to consult another to authenticate bind requests. Pass-through authentication is implement through the PTA Plug-in; when enabled, the plug-in lets a Directory Server instance accept simple bind operations (password-based) for entries not stored in its local database.
Directory Server uses PTA to administer the user and configuration directories on separate instances of Directory Server.
If the configuration directory and the user directory are installed on separate instances of Directory Server, the setup 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
suffix 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, the server that passes through bind requests to another Directory Server. The configuration directory acts as the authenticating directory, the server that contains the entry and verifies the bind credentials of the requesting client.
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.

Figure 19.2. Simple Pass-Through Authentication Process
Note
The PTA Plug-in may not be listed in the Directory Server Console if the same server instance is used for the user directory and the configuration directory.
Here's how pass-through authentication works:
- The configuration Directory Server (authenticating directory) is installed on machine A. The configuration directory always contains the configuration database and suffix,
o=NetscapeRoot
. In this example, the server name isconfigdir.example.com
. - The user Directory Server (PTA directory) is then installed on machine B. The user directory stores the root suffix, such as
dc=example,dc=com
. In this example, the server name isuserdir.example.com
. - When the user directory is set up on machine B, the setup script prompts for the LDAP URL of the configuration directory on machine A.
- The setup program enables the PTA Plug-in and configures it to use the configuration directory LDAP URL.This entry contains the LDAP URL for the configuration directory. For example:
dn: cn=Pass Through Authentication,cn=plugins, ... nsslapd-pluginEnabled: on nsslapd-pluginarg0: ldap://configdir.example.com/o=NetscapeRoot ...
The user directory is now configured to send all bind requests for entries with a DN containingo=NetscapeRoot
to the configuration directoryconfigdir.example.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 asuid=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.
19.12.1. PTA Plug-in Syntax
PTA Plug-in configuration information is specified in the
cn=Pass Through Authentication
, cn=plugins,cn=config
entry on the PTA directory (the user directory configured to pass through bind requests to the authenticating directory) using the required PTA syntax. There are only two attributes in this entry that are significant:
- nsslapd-pluginEnabled, which sets whether the plug-in is enabled or disabled. The value for this attribute can be
on
oroff
. - nsslapd-pluginarg0, which points to the configuration directory. The value for this attribute is the LDAP URL of the server and suffix to which to pass the bind requests, along with the optional parameters, maxconns, maxops, timeout, ldver, connlifetime, startTLS.
The variable components of the PTA plug-in syntax are described in Table 19.5, “PTA Plug-in Parameters”.
Note
The LDAP URL (
ldap|ldaps://
authDS/subtree) must be separated from the optional parameters (maxconns, maxops, timeout, ldver, connlifetime, startTLS) by a single space. If any of the optional parameters are defined, all of them must be defined, even if only the default values are used.
Several authenticating directories or subtrees can be specified by incrementing the
nsslapd-pluginarg
attribute suffix by one each time, as in Section 19.12.3.2, “Specifying Multiple Authenticating Directory Servers”. For example:
nsslapd-pluginarg0: LDAP URL for the first server nsslapd-pluginarg1: LDAP URL for the second server nsslapd-pluginarg2: LDAP URL for the third server ...
The optional parameters are described in the following table in the order in which they appear in the syntax.
Table 19.5. PTA Plug-in Parameters
Variable | Definition | ||
---|---|---|---|
state | Defines whether the plug-in is enabled or disabled. Acceptable values are on or off . | ||
ldap|ldaps | Defines whether TLS is used for communication between the two Directory Servers. See Section 19.12.2.1, “Configuring the Servers to Use a Secure Connection” for more information. | ||
authDS | The authenticating directory host name. The port number of the Directory Server can be given by adding a colon and then the port number. For example, ldap://dirserver.example.com:389/ . If the port number is not specified, the PTA server attempts to connect using either of the standard ports:
| ||
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 Section 19.12.2.3, “Specifying the Pass-Through Subtree” for more information. This subtree must not exist on this server. To pass the bind requests for o=NetscapeRoot to the configuration directory, the subtree o=NetscapeRoot must not exist on the server. | ||
maxconns | Optional. The maximum number of connections the PTA directory can simultaneously open to the authenticating directory. The default is 3 . See Section 19.12.2.4, “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 Section 19.12.2.4, “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 Section 19.12.2.4, “Configuring the Optional Parameters” for more information. | ||
ldver | Optional. The version of the LDAP protocol used to connect to the authenticating directory. Directory Server supports LDAP version 2 and 3. The default is version 3, and Red Hat strongly recommends against using LDAPv2, which is old and will be deprecated. See Section 19.12.2.4, “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 this option is not specified, 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 Section 19.12.2.4, “Configuring the Optional Parameters” for more information. | ||
startTLS |
Optional. A flag of whether to use Start TLS for the connection to the authenticating directory. Start TLS establishes a secure connection over the standard port, so it is useful for connecting using LDAP instead of LDAPS. The TLS server and CA certificates need to be available on both of the servers.
The default is
0 , which is off. To enable Start TLS, set it to 1 . To use Start TLS, the LDAP URL must use ldap: , not ldaps: .
See Section 19.12.2.4, “Configuring the Optional Parameters” for more information.
|
19.12.2. 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
. To modify the PTA configuration:
- Use the
ldapmodify
command to modifycn=Pass Through Authentication,cn=plugins,cn=config.
- Restart Directory Server.
Before configuring any of the PTA Plug-in parameters, the PTA Plug-in entry must be present in the Directory Server. If this entry does not exist, create it with the appropriate syntax, as described in Section 19.12.1, “PTA Plug-in Syntax”.
Note
If the user and configuration directories are installed on different instances of the directory, the PTA Plug-in entry is automatically added to the user directory's configuration and enabled.
This section provides information about configuring the plug-in in the following sections:
19.12.2.1. Configuring the Servers to Use a Secure Connection
The PTA directory can be configured to communicate with the authenticating directory over TLS by specifying LDAPS in the LDAP URL of the PTA directory. For example:
nsslapd-pluginarg0: ldaps://ldap.example.com:636/o=NetscapeRoot
19.12.2.2. 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 defines as the authenticating directory. To specify the authenticating Directory Server, replace authDS in the LDAP URL of the PTA directory with the authenticating directory's host name, as described in Table 19.5, “PTA Plug-in Parameters”.
- Use
ldapmodify
edit the PTA Plug-in entry.ldapmodify -D "cn=Directory Manager" -W -p 389 -h server.example.com -x dn: cn=Pass Through Authentication,cn=plugins,cn=config changetype: modify replace: nsslapd-pluginarg0 nsslapd-pluginarg0: ldap://dirserver.example.com/o=NetscapeRoot
Optionally, include the port number. If the port number is not given, the PTA Directory Server attempts to connect using either the standard port (389) forldap://
or the secure port (636) forldaps://
.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. There can be multiple authenticating Directory Servers specified, as required, to provide failover if the first Directory Server is unavailable. All of the authentication Directory Server are set in thensslapd-pluginarg0
attribute.Multiple authenticating Directory Servers are listed in a space-separate list of host:port pairs, with this format:ldap|ldaps://host1:port1 host2:port2/subtree
- Restart the server.
systemctl restart dirsrv@instance
19.12.2.3. Specifying the Pass-Through Subtree
The PTA directory passes through bind requests to the authenticating directory from all clients with a DN defined in the pass-through subtree. The subtree is specified 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.
- Use the
ldapmodify
command to import the LDIF file into the directory.# ldapmodify -D "cn=Directory Manager" -W -p 389 -h server.example.com -x dn: cn=Pass Through Authentication,cn=plugins,cn=config changetype: modify replace: nsslapd-pluginarg0 nsslapd-pluginarg0: ldap://dirserver.example.com/o=NetscapeRoot
For information on the variable components in this syntax, see Table 19.5, “PTA Plug-in Parameters”. - Restart the server.
# systemctl restart dirsrv@instance
19.12.2.4. Configuring the Optional Parameters
Additional parameters the control the PTA connection can be set with the LDAP URL.
ldap|ldaps://authDS/subtree maxconns, maxops, timeout, ldver, connlifetime, startTLS
- 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 maxops. The default is value is
5
. - The time limit for the PTA Directory Server to wait for a response from the authenticating Directory Server. In the PTA syntax, this parameter is timeout. The default value is
300
seconds (five minutes). - The version of the LDAP protocol for the PTA Directory Server to use to connect to the authenticating Directory Server. In the PTA syntax, this parameter is 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 this option is not specified 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 connlifetime. - Whether to use Start TLS for the connection. Start TLS creates a secure connection over a standard LDAP port. For Start TLS, the servers must have their server and CA certificates installed, but they do not need to be running in TLS.The default is
0
, which means Start TLS is off. To enable Start TLS, set it to1
. To use Start TLS, the LDAP URL must useldap:
, notldaps:
.
- Use
ldapmodify
to edit the plug-in entry.# ldapmodify -D "cn=Directory Manager" -W -p 389 -h server.example.com -x dn: cn=Pass Through Authentication,cn=plugins,cn=config changetype: modify replace: nsslapd-pluginarg0 nsslapd-pluginarg0: ldap://dirserver.example.com/o=NetscapeRoot 3,5,300,3,300,0
(In this example, each of the optional parameters is set to its default value.) Make sure there is a space between the subtree parameter, and the optional parameters.Note
Although these parameters are optional, if any one of them is defined, they all must be defined, even if they use the default values. - Restart the server.
# systemctl restart dirsrv@instance
19.12.3. PTA Plug-in Syntax Examples
This section contains the following examples of PTA Plug-in syntax in the
dse.ldif
file:
19.12.3.1. 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 host name of the authenticating Directory Server is configdir.example.com
.
dn: cn=Pass Through Authentication,cn=plugins,cn=config ... nsslapd-pluginEnabled: on nsslapd-pluginarg0: ldap://configdir.example.com/o=NetscapeRoot ...
19.12.3.2. 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. There can be multiple authenticating Directory Servers specified, as required, to provide failover if the first Directory Server is unavailable. All of the authentication Directory Server are set in the
nsslapd-pluginarg0
attribute. Multiple authenticating Directory Servers are listed in a space-separate list of host:port pairs. For example:
dn: cn=Pass Through Authentication,cn=plugins,cn=config ... nsslapd-pluginEnabled: on nsslapd-pluginarg0: ldap://configdir.example.com:389 config2dir.example.com:1389/o=NetscapeRoot ...
Note
The
nsslapd-pluginarg0
attribute sets the authentication Directory Server; additional nsslapd-pluginargN
attributes can set additional suffixes for the PTA Plug-in to use, but not additional hosts.
19.12.3.3. 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 ... nsslapd-pluginEnabled: on nsslapd-pluginarg0: ldap://configdir.example.com/o=NetscapeRoot nsslapd-pluginarg1: ldap://configdir.example.com/dc=example,dc=com ...
19.12.3.4. 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 ... nsslapd-pluginEnabled: on nsslapd-pluginarg0: ldap://configdir.example.com/o=NetscapeRoot 10,5,300,3,300,1 ...
19.12.3.5. Specifying Different Optional Parameters and Subtrees for Different Authenticating Directory Servers
To specify a different pass-through subtree and optional parameter values for each authenticating Directory Server, set 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 ... nsslapd-pluginEnabled: on nsslapd-pluginarg0:ldap://configdir.example.com/o=NetscapeRoot 10,15,30,3,600,0 nsslapd-pluginarg1:ldap://config2dir.example.com/dc=example,dc=com 7,7,300,3,300,1 ...