Pass-Through Authentication

Pass-through authentication (PTA) is a mechanism by which bind requests are filtered by bind DN. One Directory Server (the delegator) receives the bind request and, based on the filter, can consult another Directory Server (the delegate) to authenticate bind requests. As part of this functionality, the PTA plug-in enables the delegator Directory Server to accept simple password-based bind operations for entries that are not necessarily stored in its local database.

• PTA Plug-In and DSCC

• Configuring the PTA Plug-in

PTA Plug-In and DSCC

The PTA plug-in is also used by DSCC for private communication with the server. When a server instance is registered in DSCC, the PTA plug-in is enabled and the DSCC URL is added as an argument.

$ dsconf get-plugin-prop -h host -p port "Pass Through Authentication"

argument          :  ldap://dscc_host:3998/cn=dscc
depends-on-named  :
depends-on-type   :
desc              :  pass through authentication plugin
enabled           :  on
feature           :  passthruauth
init-func         :  passthruauth_init
lib-path          :  install-path/lib/passthru-plugin.so
type              :  preoperation
vendor            :  Sun Microsystems, Inc.
version           :  7.0 

If your server is registered in DSCC and you need to use PTA, you must preserve the following settings while modifying the PTA plug-in.

• Keep the enabled property on.

• Keep the DSCC URL in the argument, although you can add other values to the argument property.

If the PTA plug-in is disabled or the DSCC URL is removed from the argument, the server instance will appear as inaccessible in DSCC. If this happens, DSCC will automatically give you the option of resetting the PTA plug-in.

You can also fix this problem by unregistering and registering the Directory Server instance into DSCC. To perform these operations, you can use either DSCC or the dsccreg remove-server and dsccreg add-server commands. For more information about the dsccreg command, see dsccreg(1M).

Configuring the PTA Plug-in

PTA plug-in configuration information is specified in the cn=Pass Through Authentication,cn=plugins,cn=config entry on the PTA server.

The PTA plug-in is a system plug-in, which is disabled by default. It can be enabled and setup using the dsconf command or using DSCC.

Setting up the PTA Plug-In

1. Run the following dsconf commands:

   $ dsconf enable-plugin -h PTAhost -p port "Pass Through Authentication" $ dsconf set-plugin-prop -h PTAhost -p port "Pass Through Authentication" \ argument:"ldap[s]://authenticatingHost[:port]/PTAsubtree options"

   The plug-in argument specifies the LDAP URL identifying the hostname of the authenticating directory server, an optional port, and the PTA subtree. If no port is specified, the default port is 389 with LDAP and 636 with LDAPS. You may also set the optional connection parameters described in the following sections. If the PTAsubtree exists in the PTAhost, the plug-in will not pass the bind request to the authenticatingHost, and the bind will be processed locally without any pass-through.

2. Restart the server as described in Starting, Stopping, and Restarting a Directory Server Instance.

Configuring PTA to Use a Secure Connection

Because the PTA plug-in must send bind credentials including the password to the authenticating directory, we recommend using a secure connection. To configure the PTA directory to communicate with the authenticating directory over SSL:

• Configure and enable SSL in both the PTA and authenticating directories, as described in Chapter 5, Directory Server Security.

• Create or modify the PTA plug-in configuration to use LDAPS and the secure port in the LDAP URL, for example:

  ldaps://host:secure-port/subtree

Setting the Optional Connection Parameters

The PTA plug-in arguments accept a set of optional connection parameters after the LDAP URL:

http[s]://host:port/subtree [maxconns,maxops,timeout,ldapver,connlife]

The parameters must be given in the order shown. Although these parameters are optional, if you specify one of them, you must specify them all. If you do not want to customize all parameters, specify their default values given below. Make sure there is a space between the subtree parameter and the optional parameters.

You can configure the following optional parameters for each LDAP URL:

• maxconns - The maximum number of connections the PTA server can open simultaneously to the authenticating server. This parameter limits the number of simultaneous binds that can be passed-through to the authenticating server. The default value is 3.

• maxops - The maximum number of bind requests the PTA directory server can send simultaneously to the authenticating directory server within a single connection. This parameter further limits the number of simultaneous pass-through authentications. The default is value is 5.

• timeout - The maximum delay in seconds that you want the PTA server to wait for a response from the authenticating server. The default value is 300 seconds (five minutes).

• ldapver - The version of the LDAP protocol you want the PTA server to use when connecting to the authenticating server. The allowed values are 2 for LDAPv2 and 3 for LDAPv3. The default value is 3.

• connlife - The time limit in seconds within which the PTA server will reuse a connection to the authenticating server. If a bind in the PTA subtree is requested by a client after this time has expired, the server closes the PTA connection and opens a new one. 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 server is listed in the LDAP URL, no time limit will be enforced. If two or more hosts are listed, the default is 300 seconds (five minutes).

While setting the argument property using the dsconf command, put the value in double quotes to protect spaces. For example:

dsconf set-plugin-prop -h PTAhost -p port "Pass Through Authentication"\
 argument:"ldaps://eastbak.example.com/ou=East,ou=People,dc=example,dc=com\
 3,5,300,3,300"

Specifying Multiple Servers and Subtrees

You may configure the PTA plug-in with multiple arguments to specify multiple authenticating servers, multiple PTA subtrees, or both. Each argument contains one LDAP URL and may have its own set of connection options.

When there are multiple authenticating servers for the same PTA subtree, they act as failover servers. The plug-in will establish connections to them in the order listed whenever a PTA connection reaches the timeout limit. If all connections time out, the authentication fails.

When there are multiple PTA subtrees defined, the plug-in will pass-through the authentication request to the corresponding server according to the bind DN. The following example shows four PTA plug-in arguments that define two PTA subtrees, each with a failover server for authentication and server-specific connection parameters:

$ dsconf set-plugin-prop -h PTAhost -p port "Pass Through Authentication"\
 argument:"ldaps://configdir.example.com/o=example.com\
 10,10,60,3,300"
$ dsconf set-plugin-prop -h PTAhost -p port "Pass Through Authentication"\
 argument+:"ldaps://configbak.example.com/o=example.com\
 10,10,60,3,300"
$ dsconf set-plugin-prop -h PTAhost -p port "Pass Through Authentication"\
 argument+:"ldaps://east.example.com/ou=East,ou=People,dc=example,dc=com\
 10,10,60,3,300"
$ dsconf set-plugin-prop -h PTAhost -p port "Pass Through Authentication"\
 argument+:"ldaps://eastbak.example.com/ou=East,ou=People,dc=example,dc=com\
 10,10,60,3,300"