Using the Pass-through Authentication Plug-in

Administrator’s Guide
Red Hat Directory Server

Index

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.

Red Hat Directory Server (Directory Server) 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 (page 517)
PTA Plug-in Syntax (page 519)
Configuring the PTA Plug-in (page 521)
PTA Plug-in Syntax Examples (page 527)

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 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.

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 authentication works:

You install the configuration directory server (authenticating directory) on machine A.

Server name: configdir.example.com
Suffix: o=NetscapeRoot

You install the user directory server (PTA directory) on machine B.

Server name: userdir.example.com
Suffix: dc=example,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: 
/opt/redhat-ds/servers/lib/passthru-plugin.so

nsslapd-pluginInitfunc: passthruauth_init

nsslapd-pluginType: preoperation

nsslapd-pluginEnabled: on

nsslapd-pluginarg0: ldap://config.example.com/ou=NetscapeRoot

nsslapd-plugin-depends-on-type: database

nsslapd-pluginId: passthruauth

nsslapd-pluginVersion: 7.1

nsslapd-pluginVendor: Red Hat, Inc.

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.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 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: 
/opt/redhat-ds/servers/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," on page 528.

The optional parameters are described in the following table in the order in which 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," on page 522, for more information.

extension

File extension for the plug-in. The extension is always .sl on HP-UX and .so on all other UNIX platforms.

ldap|ldaps

Defines whether SSL is used for communication between the two Directory Servers. See "Configuring the Servers to Use a Secure Connection," on page 523, 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.example.com:390/

If you do not specify the port number, the PTA server attempts to connect using:

Port 389 if ldap:// is specified in the URL.
Port 636 if ldaps:// is specified in the URL.

See "Specifying the Authenticating Directory Server," on page 524, 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," on page 525, 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," on page 525, 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," on page 525, 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," on page 525, 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.

See "Configuring the Optional Parameters," on page 525, 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," on page 525, 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," on page 519.

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
Configuring the Servers to Use a Secure Connection
Specifying the Authenticating Directory Server
Specifying the Pass-through Subtree
Configuring the Optional Parameters

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 Red Hat 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: 
/opt/redhat-ds/servers/lib/passthru-plugin.extension

nsslapd-pluginInitfunc: passthruauth_init
 
where extension is always .sl on HP-UX and .so on all other UNIX platforms.

Restart the server.

For information on restarting the server, refer to "Starting and Stopping the Directory Server," on page 37.

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 Table 16-1, on page 520,.

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 37.

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:

Port 389 if ldap:// is specified in the URL.
Port 636 if ldaps:// is specified in the URL.

For example, you could set the value of the nsslapd-pluginarg0 attribute to:
"ldap://dirserver.example.com:389/subtree [Parameters]"
 
For information on the variable components in this sytax, refer to Table 16-1, on page 520,.

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 37.

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.example.com/o=NetscapeRoot [Parameters]"
 
For information on the variable components in this sytax, refer to Table 16-1, on page 520,.

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 37.

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.example.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 37.

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
Specifying Multiple Authenticating Directory Servers
Specifying One Authenticating Directory Server and Multiple Subtrees
Using Non-Default Parameter Values
Specifying Different Optional Parameters and Subtrees for Different Authenticating Directory Servers

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 configdir.example.com.
dn: cn=Pass Through Authentication,cn=plugins,cn=config

objectClass: top

objectClass: nsSlapdPlugin

objectClass: extensibleObject

cn: Pass Through Authentication

nsslapd-pluginPath: 
/opt/redhat-ds/servers/lib/passthru-plugin.so

nsslapd-pluginInitfunc: passthruauth_init

nsslapd-pluginType: preoperation

nsslapd-pluginEnabled: on

nsslapd-pluginarg0: ldap://configdir.example.com/ou=NetscapeRoot

nsslapd-plugin-depends-on-type: database

nsslapd-pluginId: passthruauth

nsslapd-pluginVersion: 7.1

nsslapd-pluginVendor: Red Hat, Inc.

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: 
/opt/redhat-ds/servers/lib/passthru-plugin.so

nsslapd-pluginInitfunc: passthruauth_init

nsslapd-pluginType: preoperation

nsslapd-pluginEnabled: on

nsslapd-pluginarg0: 
ldap://configdir.example.com/ou=NetscapeRoot

nsslapd-pluginarg1: 
ldap://config2dir.example.com/ou=NetscapeRoot

nsslapd-plugin-depends-on-type: database

nsslapd-pluginId: passthruauth

nsslapd-pluginVersion: 7.1

nsslapd-pluginVendor: Red Hat, Inc.

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: 
/opt/redhat-ds/servers/lib/passthru-plugin.so

nsslapd-pluginInitfunc: passthruauth_init

nsslapd-pluginType: preoperation

nsslapd-pluginEnabled: on

nsslapd-pluginarg0: ldap://configdir.example.com/ou=NetscapeRoot

nsslapd-pluginarg1: 
ldap://configdir.example.com/dc=example,dc=com

nsslapd-plugin-depends-on-type: database

nsslapd-pluginId: passthruauth

nsslapd-pluginVersion: 7.1

nsslapd-pluginVendor: Red Hat, Inc.

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: 
/opt/redhat-ds/servers/lib/passthru-plugin.so

nsslapd-pluginInitfunc: passthruauth_init

nsslapd-pluginType: preoperation

nsslapd-pluginEnabled: on

nsslapd-pluginarg0: ldap://configdir.example.com/ou=NetscapeRoot 
10,5,300,3,300

nsslapd-plugin-depends-on-type: database

nsslapd-pluginId: passthruauth

nsslapd-pluginVersion: 7.1

nsslapd-pluginVendor: Red Hat, Inc.

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: 
/opt/redhat-ds/servers/lib/passthru-plugin.so

nsslapd-pluginInitfunc: passthruauth_init

nsslapd-pluginType: preoperation

nsslapd-pluginEnabled: on

nsslapd-pluginarg0: 
ldap://configdir.example.com/ou=NetscapeRoot 7,7,300,3,300

nsslapd-pluginarg1: 
ldap://config2dir.example.com/dc=example,dc=com 7,7,300,3,300

nsslapd-plugin-depends-on-type: database

nsslapd-pluginId: passthruauth

nsslapd-pluginVersion: 7.1

nsslapd-pluginVendor: Red Hat, Inc.

nsslapd-pluginDescription: pass through authentication plugin
 

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.

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," on page 528.

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," on page 522, for more information.
extension	File extension for the plug-in. The extension is always .sl on HP-UX and .so on all other UNIX platforms.
ldap\|ldaps	Defines whether SSL is used for communication between the two Directory Servers. See "Configuring the Servers to Use a Secure Connection," on page 523, 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.example.com:390/ If you do not specify the port number, the PTA server attempts to connect using: Port 389 if ldap:// is specified in the URL. Port 636 if ldaps:// is specified in the URL. See "Specifying the Authenticating Directory Server," on page 524, 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," on page 525, 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," on page 525, 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," on page 525, 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," on page 525, 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. See "Configuring the Optional Parameters," on page 525, 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," on page 525, for more information.

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.

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.

Contents

Index