Configuring Pass-through authentication on the Directory Server

Use this information to configure Pass-Through authentication on the Directory Server.

Pass-through authentication (PTA) is a mechanism which the server uses to verify the credential from another external directory server or a pass-through server on behalf of the client if :

a client attempts to bind to a directory server, and
the user credential is not available locally

To gain a better understanding of the pass-through authentication mechanism, consider an example given below:

Let us assume there are two servers, say server X and server Y and a user entry cn=Tom Brown,o=sample stored on server Y. Now, if the user Tom Brown attempts to access server X to perform any operation it has to first bind to server X with its credential for authentication. Since the credential is not present on server X the user will be unable to bind to the server. However, using the pass-through authentication mechanism, server X can verify the credential by contacting server Y. After the credential is validated using server Y, server X presumes that the user is authenticated and hence returns success for the bind operation.

Alternatively, if a user is present on server X while its credential is available on server Y, again server X will contact server Y to verify the credential.

In the above cases it is assumed that the DNs on server Y and server X are identical. However, this may not be true always as the directory structure layout may differ on both the servers. This means that DN "cn=Tom Brown,o=sample" on server X may map to some other DN on server Y. In such situations it is possible that the entries on server X and server Y have some attribute whose value is unique for every entry, say for instance uid. Therefore, an attribute from the TDS server can be mapped to another attribute in the pass-through server. This information can then be used to query the pass-through server to fetch the required DN. A bind operation will then be performed for this DN to identify if the userpassword is correct.

Note:

Any configuration changes done for pass through authentication are not dynamic in nature and hence require a restart.
It is important to note that all the entries mentioned in the scenarios below must be within a configured subtree.

Let us consider a few scenarios pertaining to pass-through authentication:

Scenario 1: Attribute mapping is configured and entry is present locally

This is a scenario where an attribute in TDS will match some other attribute in pass-through server. It is not necessary that the name of an attribute is identical in both directories. For instance, uid=Tom456 in TDS may map to userPrincipalName=Tom456 in the pass-through server. In this scenario, all the entries in TDS can be directly mapped to the entries in the pass-through server. Now, a search can be performed on the pass-through server to get the actual DN which will then be used to perform a bind operation to verify the user credential. A sample entry in the configuration would look like:

ibm-slapdPtaAttrMapping : uid $ userPrincipalName

uid in TDS is mapped to userPrincipalName in pass-through server.

Let us assume that the following entry exists on TDS:

dn: cn=Tom Brown,o=sample
sn: tests
uid: Tom456
objectclass: organizationalPerson
objectclass: person
objectclass: top
objectclass: inetOrgPerson

Now, in case of a bind request with a DN "cn=Tom Brown,o=sample" , the pass-through server will be searched using "userPrincipalName=Tom456" search filter. If only one entry is returned then the DN of that entry is used and a bind operation is performed to verify the password. However, if uid is multi-valued in the "cn=Tom Brown,o=sample" entry, the bind operation will fail.

Let us suppose another situation where there is no unique attribute that can be mapped between directories. In such a situation you must introduce an auxiliary class and attach it to the entry where the mapping is required. For instance:

dn: cn=Tom Brown,o=sample
sn: test
uid: Tom456
objectclass: organizationalPerson
objectclass: person
objectclass: top
objectclass: inetOrgPerson
objectclass: my-aux-class
uniqueValue: my_value

You can create a new auxiliary objectclass (my-aux-class) and associated attribute (uniqueValue) or use any existing objectclass and attribute. Finally, you set ibm-slapdPtaAttrMapping as:

ibm-slapdPtaAttrMapping : uniqueValue $ userPrincipalName

Note: If the mapping attribute ibm-slapdPtaAttrMapping is not set to a unique attribute then it is possible that the pass-through server will return more than one entry or a false entry and the PTA interface will return a bind failure and log a message.

Scenario 2: Attribute mapping is configured, entry is present locally, and password migration is enabled

This is similar to scenario 1 except that after the result is sent to the client, the PTA interface will store the userpassword provided by the user during the bind operation in its local entry. Here, password will be stored in the TDS local directory after the first successful bind and will be present in the directory even after the server is down. Subsequent bind requests from this user will be served completely by local TDS directory and will not reach the pass-through server. The userpassword will be stored using the encryption scheme configured locally and adhere to the local password policy settings.

Note: The password will also be replicated as per the replication configuration in TDS.

In this kind of scenario it is important to maintain consistency between the passwords of the pass-through server and the local TDS directory. Inconsistencies between the passwords available at the pass-through server and the local TDS directory can pose a potential security threat. A system administrator needs to ensure that the integrity of passwords at both the directories is maintained.

Scenario 3: The attribute mapping is not configured and the entry is not present locally.

In this kind of scenario after the bind request fails to locate the entry locally, the PTA interface will check if any pass-through server is configured to service the bind DN. If any pass-through server is configured, then using the bind DN and password supplied by the user, the bind request is send to the pass-through server. If the bind succeeds, the server returns success, otherwise it returns LDAP_INVALID_CREDENTIALS. In this scenario since the entry is not present locally, enabling password migration will not have any effect.

Scenario 4: Auxiliary object class is set for attribute-linking

Now, uid=Tom456 can be easily mapped to userPrincipal=Tom456. However, there is no mapping between the second entry uid=Tom396 and userPrincipal=Tom456 since both the values differ even though they actually pertain to the same person. Therefore, if there is a bind request for uid=Tom396 which has its credentials on the pass-through server, the bind will fail. To solve this problem, you must add an auxiliary class ibm-ptaReferral. This will hold two MUST attributes ibm-PtaLinkAttribute and ibm-PtaLinkValue. This needs to be added to the entry that has no mapping in the pass-through server. Now, whenever there is a bind request for uid=Tom396, the PTA interface will first look if the ibm-ptaReferral objectclass is present. If it is present then it will fetch the details for the MUST attribute and frame the required search query. The entry will look like:

dn:  cn=Tom396,o=sample
objectclass: inetOrgPerson
objectclass: organizationalPerson
objectclass: person
objectclass: top
uid:Tom396
sn: test
objectclass: ibm-ptaReferral
ibm-ptaLinkAttribute:  userPrincipalName
ibm-ptaLinkValue:  Tom456

Another case to be considered is when there is no mapping between TDS and the pass-through server but the administrator is aware of the DN that directly maps between both the directories. In such cases, ibm-PtaLinkAttribute must be set to "_DN_" and ibm-PtaLinkValue must be set to the actual DN of mapped entry. The entry will look like:

dn:  cn=Tom396,o=sample
objectclass: inetOrgPerson
objectclass: organizationalPerson
objectclass: person
objectclass: top
uid:Tom396
sn: test
objectclass: ibm-ptaReferral
ibm-ptaLinkAttribute:  _DN_
ibm-ptaLinkValue:  cn=Tom1000,o=sample

By setting these values in the entry, the PTA interface takes the specified DN value and binds using the user supplied credentials. The result will be returned accordingly. It is important to note that when computing the DN to be passed to the pass-through server, if it is found that an entry is set with ibm-ptaReferral auxiliary class, then the attribute mapping configured for the entry will be ignored.

Note: In case you do not want pass-through authentication to be performed for a specific entry, you must set the ibm-ptaLinkAttribute to _DISABLE_.

To configure pass-through authentication, use one of the following methods:

Using Web Administration Tool
If you have not done so already, expand the Manage security properties category under Server administrationin the navigation area of the Web Administration Tool and click the Pass-through authenticationtab.
On this panel, you can:
- Enable or disable pass-through authentication by selecting or clearing the Enable pass-through authentication check box.
- Configure a pass-through entry for a subtree for pass-through authentication. Clicking Adddisplays the Configure subtree for pass-through authentication wizard that can be used for configuring a pass-through entry for a subtree for pass-through authentication.
- Edit an existing pass-through entry of a subtree for pass-through authentication. Clicking Editdisplays the Configure subtree for pass-through authentication wizard that can be used for modifying an existing pass-through entry of a subtree for pass-through authentication.
- Delete an existing pass-through entry of a subtree configured for pass-through authentication. For this, select a subtree from the Subtrees configured for pass-through authentication table and click the Deletebutton
- view pass-through entry details of a configured subtree for pass-through authentication. For this, select a subtree from the Subtrees configured for pass-through authentication table, select View from the Select Action list, and click Go.
- After you are finished, do one of the following:
  - Click OK to save changes and navigate to the "Introduction" panel.
  - Click Apply to save changes and to remain on this panel.
  - Click Cancel to discard changes made and navigate to the "Introduction" panel.

To configure a pass-through entry for a subtree for pass-through authentication follow the steps given below:

In the Pass-through authentication panel, click Add
Next , on the Subtree settings panel you can do the following:
- Enter a subtree DN in the field and click the Addbutton to add it to the list for storing subtree DN.
- Enter multiple subtree DNs by clicking the Browsebutton and then selecting the required rows from the Browse entries panel.
- Remove a subtree DN from the list for storing subtree DN by selecting the subtree DN and clicking the Removebutton.
- Specify the host name of the pass-through server in the Host name field. This is a required field.
- Specify o Specify the port number of the pass-through server in the Portfield. This is a required field.
- Enable SSL encryption on the pass-through server by selecting the Enable SSL encryptioncheck box
- Specify o Specify whether to save the user password on the local directory for all successful bind request processed through the pass-through server by selecting a value from the Migrate userpassword to this directory servercombo box. The default value of this control is "False".
- Specify the number of connections that is required for each pass-through server entry in the Number of connections to the pass-through server to maintain for Pass-through authentication field.
- Specify a timeout value in the Pass-through authentication timeoutfield. The pass-through authentication interface will wait for result from socket till the timeout period before it returns the client request.
  Note: The attribute "ibm-slapdPtaResultTimeout" in the "cn=< pass-through server >, cn=Passthrough Authentication, cn=Configuration" entry is associated with this control.
- Click Next.

To configure attribute mapping, do the following:

Select the Enable attribute mappingcheck box to enable attribute mapping. Selecting the Enable attribute mappingcheck box also enables other controls on the Attribute mapping panel.
In the Bind DN for pass-through serverfield, enter a bind DN for binding to the pass-through server.
In the Bind password for pass-through server field, enter a bind password for binding to the pass-through server.
In the Search base DNfield, enter the search base DN of pass-through server where the entry will be searched, or click the Browsebutton to display Browse entries panel from which the user can select the existing DN from the pass-through server.
From the Attribute for this directory servercombo box, select an attribute that should be mapped to an attribute in pass-through server.
From the Attribute for pass-through directory server combo box, select an attribute that should be mapped to the TDS attribute
When you are finished, do one of the following:
- click Backto navigate to the Subtree settings panel.
- Click Finishto save the changes and to navigate to the Pass-through authentication.
- Click Cancel to discard the changes and to navigate to the Pass-through authentication

Using command line

To enable PTA using the command line you must modify the configuration file of the directory server. Issue the following command to enable PTA:

ldapmodify -h <hosname> -p <port> -D <adminDN> -w <adminpwd> -f <ldif file>

where the ldif file contains

dn: cn=Configuration 
ibm-slapdPtaEnabled: true 

dn: cn=Passthrough Server1, cn=Passthrough Authentication, cn=Configuration 
changetype: add 
cn: passthrough Server1 
ibm-slapdPtaURL:  ldap://<hostname>:<port>
ibm-slapdPtaSubtree: o=sample 
ibm-slapdPtaMigratePwd: false 
ibm-slapdPtaConnectionPoolSize: 6 
objectclass: top 
objectclass: ibm-slapdConfigEntry 
objectclass: ibm-slapdPta

The above command enables PTA, configures a subtree for pass-through authentication, specifies the hostname and port number for a pass through server, and specifies the number of connections that is required for each pass-through server entry. Also, the above command specifies that the user password must not be saved to the local directory for all successful bind requests.

To enable PTA and configure attribute mapping, issue the following command:

ldapmodify -h <hostname> -p <port> -D <adminDN> -w <adminpwd> -f <ldif file>

where the ldif file contains:

dn: cn=Configuration 
ibm-slapdPtaEnabled: true 

dn: cn=Passthrough Server1, cn=Passthrough Authentication, cn=Configuration 
changetype: add 
cn: passthrough Server1 
ibm-slapdPtaURL: ldap: //<hostname>:<port>
ibm-slapdPtaSubtree: o=sample 
ibm-slapdPtaMigratePwd: true 
ibm-slapdPtaAttrMapping: sn $ uid 
ibm-slapdPtaSearchBase: ou=austin,o=sample 
ibm-slapdPtaBindDN: <bind DN>
ibm-slapdPtabindPW: <bind password>
objectclass: top 
objectclass: ibm-slapdConfigEntry 
objectclass: ibm-slapdPta 
objectclass: ibm-slapdPtaExt

In the above example attribute mapping is configured and password migration is also enabled. Here, the attribute 'sn' in the directory server is mapped to the attribute 'uid' in the pass-through server.