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.
Simple Pass-Through Authentication Process

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:
  1. 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 is configdir.example.com.
  2. 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 is userdir.example.com.
  3. 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.
  4. 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 containing o=NetscapeRoot to the configuration directory configdir.example.com.
  5. When installation is complete, the admin user attempts to connect to the user directory to begin adding users.
  6. 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.
  7. The configuration directory authenticates the user's credentials and sends the information back to the user directory.
  8. 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 or off.
  • 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:
Port 389 if ldap:// is specified in the URL.
Port 636 if ldaps:// is specified in the URL.
See Section 19.12.2.2, “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 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:
  1. Use the ldapmodify command to modify cn=Pass Through Authentication,cn=plugins,cn=config.
  2. 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”.
  1. 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) for ldap:// or the secure port (636) for ldaps://.
    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, with this format: 
    ldap|ldaps://host1:port1 host2:port2/subtree
  2. 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.
  1. 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”.
  2. 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 to 1. To use Start TLS, the LDAP URL must use ldap:, not ldaps:.
  1. 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.
  2. 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
...