Red Hat Summit Red Hat SummitSupportConsoleDevelopersStart a trialContact

20.13. 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.
The first instance acts as the PTA Directory Server which is the server that passes through bind requests to another Directory Server. The second instance acts as the authenticating directory, which is 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 20.2. Simple Pass-Through Authentication Process

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 suffix with the authenticating user entry, for example, o=RedHat. In this example, the server name is authdir.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. Set up the plug-in on userdir.example.com by using the following commands: 
    # dsconf -D "cn=Directory Manager" ldap://userdir.example.com plugin pass-through-auth enable
# dsconf -D "cn=Directory Manager" ldap://userdir.example.com plugin pass-through-auth url add "ldap://authdir.example.com/o=RedHat"
  4. Restart Directory Server on userdir.example.com.
  5. The user directory is now configured to send all bind requests for entries with a DN containing o=RedHat to the configuration directory authdir.example.com.
  6. The user directory allows any user from o=RedHat to bind.

20.13.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.
Use the following commands to manage pass-through authentication URLs:
  • To add a pass-through authentication URL: 
    # dsconf -D "cn=Directory Manager" ldap://server.example.com plugin pass-through-auth url add URL
  • To modify a pass-through authentication URL: 
    # dsconf -D "cn=Directory Manager" ldap://server.example.com plugin pass-through-auth url modify old_URL new_URL
  • To remove pass-through authentication URL: 
    # dsconf -D "cn=Directory Manager" ldap://server.example.com plugin pass-through-auth url delete URL
The variable components of the PTA plug-in syntax are described in Table 20.3, “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 20.13.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 20.3. 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 20.13.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 20.13.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 20.13.2.3, “Specifying the Pass-Through Subtree” for more information. This subtree must not exist on this server.
maxconns Optional. The maximum number of connections the PTA directory can simultaneously open to the authenticating directory. The default is 3. See Section 20.13.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 20.13.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 20.13.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 20.13.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 20.13.2.4, “Configuring the Optional Parameters” for more information.
startTLS
Optional. A flag of whether to use STARTTLS for the connection to the authenticating directory. STARTTLS 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 STARTTLS, set it to 1. To use STARTTLS, the LDAP URL must use ldap:, not ldaps:.
See Section 20.13.2.4, “Configuring the Optional Parameters” for more information.

20.13.2. Configuring the PTA Plug-in

To modify the PTA configuration:
  1. Use the dsconf plugin pass-through-auth command to modify the cn=Pass Through Authentication,cn=plugins,cn=config entry.
  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 20.13.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:

20.13.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=example

20.13.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 20.3, “PTA Plug-in Parameters”.
  1. Use the dsconf plugin pass-through-auth command to edit the PTA Plug-in entry: 
    # dsconf -D "cn=Directory Manager" ldap://server.example.com plugin pass-through-auth add ldap://server.example.com/o=example
    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. 
    # dsctl instance_name restart

20.13.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 dsconf plugin pass-through-auth command to import the LDIF file into the directory: 
    # dsconf -D "cn=Directory Manager" ldap://server.example.com plugin pass-through-auth add ldap://server.example.com/o=example
    For information on the variable components in this syntax, see Table 20.3, “PTA Plug-in Parameters”.
  2. Restart the server: 
    # dsctl instance_name restart

20.13.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 STARTTLS for the connection. STARTTLS creates a secure connection over a standard LDAP port. For STARTTLS, 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 STARTTLS is off. To enable STARTTLS, set it to 1. To use STARTTLS, the LDAP URL must use ldap:, not ldaps:.
  1. Use the dsconf plugin pass-through-auth command to edit the plug-in entry: 
    # dsconf -D "cn=Directory Manager" ldap://server.example.com plugin pass-through-auth add ldap://server.example.com/o=example 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: 
    # dsctl instance_name restart

20.13.3. PTA Plug-in Syntax Examples

This section contains the following examples of PTA Plug-in syntax in the dse.ldif file:

20.13.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=example 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=example
...

20.13.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=example
...

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.

20.13.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=example
nsslapd-pluginarg1: ldap://configdir.example.com/dc=example,dc=com
...

20.13.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=example 10,5,300,3,300,1
...

20.13.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=example 10,15,30,3,600,0
nsslapd-pluginarg1:ldap://config2dir.example.com/dc=example,dc=com 7,7,300,3,300,1
...
Red Hat logoGithubRedditYoutubeTwitter

Learn

Try, buy, & sell

Communities

About Red Hat Documentation

We help Red Hat users innovate and achieve their goals with our products and services with content they can trust.

Making open source more inclusive

Red Hat is committed to replacing problematic language in our code, documentation, and web properties. For more details, see the Red Hat Blog.

About Red Hat

We deliver hardened solutions that make it easier for enterprises to work across platforms and environments, from the core datacenter to the network edge.

© 2024 Red Hat, Inc.