Configure Pass-Through Authentication on IBM
Tivoli Directory Server
Amit Aherao ([email protected]),
Staff Software Engineer, IBM India Software Labs.
Mayur Boob ([email protected]),
Software Engineer, IBM India Software Labs.
5th May 2014, Rev. 1
19th August 2014, Rev. 2
Abstract:
This white paper is intended to help customers and LDAP administrators identify and configure Pass Through
Authentication (PTA)per their organization's requirements. Pass-through authentication is a mechanism in which the
server attempts to verify the credential from another external directory server (also known as a pass-through server) on
behalf of the client, if the client's user credential is not available on the local server. This white paper also discusses
advanced PTA configurations over multiple LDAP suffixes and describes how to debug trivial pass through
authentication problems.
• Table of Contents
Configure Pass-Through Authentication on IBM Tivoli Directory Server...........................................1
Table of Listings.........................................................................................................................................2
1Introduction..............................................................................................................................................4
2PTA Work-flow........................................................................................................................................4
Points to remember for a successful pass-through authentication:.......................................................4
3How To Configure the Pass-Through Authentication Server...................................................................5
3.1The basic scenarios...........................................................................................................................5
3.1.1Scenario 1: Attribute mapping is configured and the entry is present locally..........................5
3.1.2Scenario 2: Attribute mapping is configured, entry is present locally, and password
migration is enabled..........................................................................................................................7
3.1.3Scenario 3: Attribute Mapping is Not Configured and the Entry is Not Present Locally........8
3.1.4Scenario 4: Mapping multiple entries in Tivoli Directory Server to one entry in pass-through
server.................................................................................................................................................9
3.1.5Scenario 5: Configuring pass-through authentication to Active Directory Global Catalog...12
3.2Configure a PTA over multiple suffixes.........................................................................................13
3.3Attributes associated with the ibm-slapdPta objectclass................................................................15
3.4Attributes associated with the ibm-slapdPtaExt objectclass..........................................................16
3.5Attributes associated with the ibm-PtaReferral objectclass...........................................................17
4Tips for Administrator when configuring PTA......................................................................................18
5Troubleshooting pass-through authentication........................................................................................19
5.1When the server starts is Config-only mode.................................................................................19
5.1.1When error code 81 is reported .............................................................................................19
5.1.2When error code 81 is reported (SSL)...................................................................................19
5.1.3No PTA related messages logged in ibmslpad.log, but the server starts in config only mode
........................................................................................................................................................20
5.2When error code 49 is reported......................................................................................................21
5.3User password synchronization......................................................................................................21
5.4How to report a PTA problem.......................................................................................................22
6Resources ..............................................................................................................................................22
7About the authors...................................................................................................................................22
• Table of Listings
Listing 1: Example ldapmodify command to enale PTA...........................................................................6
Listing 2: Command to configure PTA for scenario 1, case 1...................................................................6
Listing 3: myUniqueAttribute added to local server entries......................................................................7
Listing 4: Configure PTA for Scenarion 1, case 2.....................................................................................7
Listing 5: Enabling PTA for scenario 2......................................................................................................8
Listing 6: Configure the PTA for scenario 2..............................................................................................8
Listing 7: Enable PTA for scenario 3.........................................................................................................9
Listing 8: Configure the PTA interface for scenario 3...............................................................................9
Listing 9: Enable PTA for scenario 4.........................................................................................................9
Listing 10: Entry for Thom456................................................................................................................10
Listing 11: Entry for Thom888................................................................................................................10
Listing 12: Thom888 entry with ibm-ptaLinkAttribute set......................................................................11
Listing 13: Configure the PTA for Scenario 4, case 1..............................................................................11
Listing 14: Thom 888 entry for scenario 4, case 2..................................................................................12
Listing 15: Configure the PTA interface for scenario 4, case 2...............................................................12
Listing 16: Enable the PTA for scenario 5...............................................................................................13
Listing 17: Configure the PTA interface for scenario 5...........................................................................13
Listing 18: Enable PTA for muliple servers.............................................................................................14
Listing 19: Configure multople PTA servers...........................................................................................14
Listing 20: Example of a readconfig operation........................................................................................18
Listing 21: Return code 81 message........................................................................................................19
Listing 22: ldap_getenv message.............................................................................................................19
Listing 23: error code 81..........................................................................................................................20
Listing 24: SSL messages........................................................................................................................20
Listing 25: Decryption failure..................................................................................................................21
Listing 26: Error 49..................................................................................................................................21
1 Introduction
Tivoli Directory Server (TDS) provides user authentication for the users stored in its directory. User
must bind to the correct Tivoli Directory Server in order to retrieve authentication information. The
user has to perform a successful bind to the directory using his password to be authorized for
subsequent LDAP operations. By default, Tivoli Directory Server supports authentication only to local
users, i.e. the users present in the local directory.
Pass-through authentication is a mechanism which allows a client to bind to a directory server even if
the user credential is not available locally. Using this mechanism the server attempts to verify the
credentials from another external directory server or a pass-through server on behalf of the client. The
credential in this white paper refer to the userpassword attribute in Tivoli Directory Server, but passthrough authentication can also be used in migrating one-way encrypted passwords.
2 PTA Work-flow
The "Figure 1: PTA Work Flow" illustrates a PTA work flow and is described further below.
Points to remember
for a successful
pass-through
authentication:
•After PTA is configured,
make sure the PTA
server is up and running
when the TDS is started.
•The PTA server should
be an LDAP V3
compliant directory.
•The PTA server must
always be reachable for
PTA to work.
Figure 1: PTA Work Flow
1 A client sends the bind request to the Tivoli Directory Server normally without the knowledge of any
pass-through authentication configuration.
2. TDS determines that the entry for that particular user does exist, but the userpassword attribute,
which would have helped in authenticating the user, does not exist. If the server is configured to
perform a pass-through authentication to another server, the Tivoli Directory Server will continue with
the following steps.
3. The same credentials which the client used to bind to the Tivoli Directory Server, are used to bind to
the PTA server.
4. The PTA server, which has the credentials, responds to the Tivoli Directory Server's bind with a
success or an invalid credentials error.
5. Per the result obtained from the pass-through server, the user is authenticated or a failure is reported.
3 How To Configure the Pass-Through Authentication Server
3.1 The basic scenarios
There are Five basic steps scenarios for configuring PTA:
1. Attribute mapping is configured and the entry is present locally.
2. Attribute mapping is configured, entry is present locally and password migration is enabled.
3. Attribute mapping is not configured and the entry is not present locally.
4. Mapping multiple entries in TDS to one entry in PTA directory
5. Configuring pass-through authentication to Active Directory Global Catalog
Each of these scenarios are discussed in the following sections.
3.1.1 Scenario 1: Attribute mapping is configured and the entry is present
locally.
In this scenario, the LDAP entries are present on the local server and an attribute in the server can be
uniquely mapped to some other attribute in the pass-through server for all entries. The attribute that can
be mapped uniquely from the local directory server to the pass-through server must have unique value
for all entries. Using this attribute, the user can map all the entries from the directory server instance to
the pass-through directory without adding any additional information to each entry. It is the
responsibility of an administrator to set a unique value for the mapped attribute. If no such attribute can
be determined, administrator must add an attribute explicitly to all the entries with a unique value.
The following steps demonstrate how to implement this scenario:
1.
Enable PTA on the local server,
"Listing 1: Example ldapmodify command to enale PTA" shows an example::
ldapmodify -h <hostname> -p <port> -D <adminDN> -w <adminPWD>
dn: cn=Configuration
changetype: modify
replace: ibm-slapdPtaEnabled
ibm-slapdPtaEnabled: true
Listing 1: Example ldapmodify command to enale PTA
2. Configure the attribute mapping.
There are two cases for this step, depending on whether an attribute exists that can uniquely identify
every entry.
Case 1: A unique attribute exists and can be uniquely mapped to some other unique attribute in passthrough server.
As an example, suppose entries on the local server have a unique attribute called ""uid," which can be
mapped to the attribute "userPrincipalName" on the PTA server.
For example, an entry in the local directory server instance might look like this:
dn: cn=Thomas Gray,o=sample1
sn: Gray
uid: Thom456
objectclass: organizationalPerson
objectclass: person
objectclass: top
objectclass: inetOrgPerson
To configure the PTA interface and to set attribute mapping for this example, you would issue the
command shown in "Listing 2: Command to configure PTA for scenario 1, case 1."
idsldapmodify -h <hostname> -p <port> -D <adminDN> -w <adminPWD>
dn: cn=Passthrough Server1, cn=Passthrough Authentication, cn=Configuration
changetype: add
cn: Passthrough Server1
ibm-slapdPtaURL: ldap://<PTA hostname>:<port>
ibm-slapdPtaSubtree: o=sample1
ibm-slapdPtaAttrMapping: uid $ userPrincipalName
ibm-slapdPtaSearchBase: c=in,dc=com
ibm-slapdPtaBindDN: <bind DN>
ibm-slapdPtabindPW: <bind password>
objectclass: top
objectclass: ibm-slapdConfigEntry
objectclass: ibm-slapdPta
objectclass: ibm-slapdPtaExt
Listing 2: Command to configure PTA for scenario 1, case 1
Case 2: There is no unique attribute for all entries in the local server.
In this case, you must add an attribute to all entries in TDS explicitly as follows:.
a. Add an attribute, for example myUniqueAttribute, to the directory server instance schema.
b. Create an auxiliary objectclass, for example myUniqueAuxClass, with an attribute,
myUniqueAttribute.
c. Add the objectclass, myUniqueAuxClass, to all the user entries.
d. Assign a unique value to the added attribute, myUniqueAttribute.
An example of an entry with the unique attribute and auxiliary objectclass is shown in "Listing 3:
myUniqueAttribute added to local server entries."
dn: cn=Thomas Gray,o=sample1
sn: Gray
uid: Thom456
objectclass: organizationalPerson
objectclass: person
objectclass: top
objectclass: inetOrgPerson
objectclass: myUniqueAuxClass
myUniqueAttribute: my_value
Listing 3: myUniqueAttribute added to local server entries
To configure the PTA interface for this case, use the command shown in "Listing 4: Configure PTA for
Scenarion 1, case 2."
idsldapmodify -h <hostname> -p <port> -D <adminDN> -w <adminPWD>
dn: cn=Passthrough Server2, cn=Passthrough Authentication, cn=Configuration
changetype: add
cn: Passthrough Server2
ibm-slapdPtaURL: ldap://<PTA hostname>:<port>
ibm-slapdPtaSubtree: o=sample1
ibm-slapdPtaAttrMapping: myUniqueAttribute $ userPrincipalName
ibm-slapdPtaSearchBase: c=in,dc=com
ibm-slapdPtaBindDN: <bind DN>
ibm-slapdPtabindPW: <bind Password>
objectclass: top
objectclass: ibm-slapdConfigEntry
objectclass: ibm-slapdPta
objectclass: ibm-slapdPtaExt
Listing 4: Configure PTA for Scenarion 1, case 2
3.1.2 Scenario 2: Attribute mapping is configured, entry is present locally,
and password migration is enabled.
In this scenario, an entry is present in the local TDS and a unique attribute exists that can be mapped to
the entries in the pass-through server. In this scenario, the pass-through interface stores the password
provided by the user in the user entry during the bind operation in TDS. After the first successful bind,
the credential that is stored, remains in the directory server. Subsequent bind requests from the user are
authenticated by the local directory server instance using the stored credential. The local server does
not use the pass-through server. This enables authentication to be done even if the pass-through server
is down.
When the password is stored on the local server, it is encrypted using the encryption scheme that is
configured for the server and it must adheres to the local password policy settings, if one exists.
It is important to maintain password consistency between the pass-through server and the local
directory server instance. Inconsistencies between the passwords can pose a potential security threat.
Administrator must ensure that the integrity of passwords in both the directories are maintained. If the
search is successful and returns only one matching DN, then the directory server stores the password
provided during the bind in the userpassword attribute.
The following steps demonstrate how to implement this scenario.
1. To enable PTA for this scenario, issue the the command shown in "Listing 5: Enabling PTA for
scenario 2."
ldapmodify -h <hostname> -p <port> -D <adminDN> -w <adminPWD>
dn: cn=Configuration
changetype: modify
replace: ibm-slapdPtaEnabled
ibm-slapdPtaEnabled: true
Listing 5: Enabling PTA for scenario 2
2.
To configure the PTA interface, use the command shown in "6Listing 6: Configure the PTA for
scenario 2."
idsldapmodify -h <hostname> -p <port> -D <adminDN> -w <adminPWD>
dn: cn=Passthrough Server3, cn=Passthrough Authentication, cn=Configuration
changetype: add
cn: Passthrough Server3
ibm-slapdPtaURL: ldap://<PTA hostname>:<port>
ibm-slapdPtaSubtree: o=sample1
ibm-slapdPtaAttrMapping: uid $ userPrincipalName
ibm-slapdPtaSearchBase: c=in,dc=com
ibm-slapdPtaBindDN: <bind DN>
ibm-slapdPtabindPW: <bind Password>
#Password migration is enabled
ibm-slapdPtaMigratePwd: TRUE
objectclass: top
objectclass: ibm-slapdConfigEntry
objectclass: ibm-slapdPta
objectclass: ibm-slapdPtaExt
Listing 6: Configure the PTA for scenario 2
3.1.3 Scenario 3: Attribute Mapping is Not Configured and the Entry is Not
Present Locally
In this scenario, when the bind request fails to locate the entry in the local TDS server, the directory
server checks to determine if any pass-through interface is configured to service the DN supplied by the
client in the bind. If a pass-through server is configured, the bind DN and password supplied by the
user is sent to the pass-through server. If the bind succeeds at the pass through server, the local server
returns success to the client. Otherwise, the local server returns LDAP_INVALID_CREDENTIALS to
the client. Because the entry is not present locally, the password migration is ignored, even if it is
configured.
The following steps demonstrate how to implement this scenario:
1.
To enable PTA for this scenario, issue the command as shown in "Listing 7: Enable PTA for
scenario 3."
ldapmodify -h <hostname> -p <port> -D <adminDN> -w <adminPWD>
dn: cn=Configuration
changetype: modify
replace: ibm-slapdPtaEnabled
ibm-slapdPtaEnabled: true
Listing 7: Enable PTA for scenario 3
2.
To configure the PTA interface for this scenario, issue the command shown in "Listing 8:
Configure the PTA interface for scenario 3."
idsldapmodify -h <hostname> -p <port> -D <adminDN> -w <adminPWD>
dn: cn=Passthrough Server4, cn=Passthrough Authentication, cn=Configuration
changetype: add
cn: Passthrough Server4
ibm-slapdPtaURL: ldap://<PTA hostname>:<port>
ibm-slapdPtaSubtree: o=sample1
ibm-slapdPtaConnectionPoolSize: 6
ibm-slapdPtaResultTimeout: 100
objectclass: top
objectclass: ibm-slapdConfigEntry
objectclass: ibm-slapdPta
Listing 8: Configure the PTA interface for scenario 3
3.1.4 Scenario 4: Mapping multiple entries in Tivoli Directory Server to one
entry in pass-through server
In this scenario, there are two entries in the local directory server for a same user and one entry for the
user in the pass-through server. In this case, there are two ways to implement this by administrator,
which are demonstrated in the following steps.
1.
To enable PTA for this scenario, issue the command shown in "Listing 9: Enable PTA for scenario
4."
ldapmodify -h <hostname> -p <port> -D <adminDN> -w <adminPWD>
dn: cn=Configuration
changetype: modify
replace: ibm-slapdPtaEnabled
ibm-slapdPtaEnabled: true
Listing 9: Enable PTA for scenario 4
2.
Map multiple entries to a single entry in the PTA directory.
There are two cases for mapping multiple entries in the local server to a single entry in the PTA
directory.
Case 1: Mapping an entry by using the ibm-PtaLinkAttribute:
In this case, assume that there are two entries for the user, Thomas Gray, which the user uses to perform
different roles.
For example, "Listing 10: Entry for Thom456" shows a user entry with uid = Thom456.
dn: cn=Thomas Gray,o=sample1
sn: Gray
uid: Thom456
objectclass: organizationalPerson
objectclass: person
objectclass: top
objectclass: inetOrgPerson
Listing 10: Entry for Thom456
Another user entry for the same user with uid = Thom888 is shown in "Listing 11: Entry for
Thom888."
dn: cn=Thomas Gray1,o=sample1
sn: Gray
uid: Thom888
objectclass: organizationalPerson
objectclass: person
objectclass: top
objectclass: inetOrgPerson
Listing 11: Entry for Thom888
As described in Scenario 1, the attribute mapping is used to map uid=Thom456 in directory server to
userPrincipalName=Thom456 in pass-through server. However, there is no mapping for the other entry
with uid=Thom888 in directory server to an entry in PTA server. If there is a bind request for
uid=Thom888, the bind request would fail because the uid value for the other entry and the
userPrincipalName value in pass-through server are different.
To solve this bind problem, an auxiliary objectclass ibm-ptaReferral can be added to the entry in the
local TDS which can not be mapped using attribute mapping in pass-through server. (In this case
Thom888.) You need to add ibm-PtaLinkAttribute and ibm-PtaLinkValue attributes to the user entry
(must attributes for the ibm-ptaReferral objectclass). An example entry for cn=Thomas Gray1 is shown
in "Listing 12: Thom888 entry with ibm-ptaLinkAttribute set."
dn: cn=Thomas Gray1,o=sample1
objectclass: inetOrgPerson
objectclass: organizationalPerson
objectclass: person
objectclass: top
uid:Thom888
sn: Gray
objectclass: ibm-ptaReferral
ibm-ptaLinkAttribute: userPrincipalName
ibm-ptaLinkValue: Thom456
Listing 12: Thom888 entry with ibm-ptaLinkAttribute set
To configure PTA interface for this scenario, issue the command shown in "Listing 12: Thom888 entry
with ibm-ptaLinkAttribute set."
idsldapmodify -h <hostname> -p <port> -D <adminDN> -w <adminPWD>
dn: cn=Passthrough Server5, cn=Passthrough Authentication, cn=Configuration
changetype: add
cn: Passthrough Server5
ibm-slapdPtaURL: ldap://<PTA hostname>:<port>
ibm-slapdPtaSubtree: o=sample1
ibm-slapdPtaAttrMapping: uid $ userPrincipalName
ibm-slapdPtaSearchBase: c=in,dc=com
ibm-slapdPtaBindDN: <bind DN>
ibm-slapdPtabindPW: <bind Password>
ibm-slapdPtaMigratePwd: TRUE
objectclass: top
objectclass: ibm-slapdConfigEntry
objectclass: ibm-slapdPta
objectclass: ibm-slapdPtaExt
Listing 13: Configure the PTA for Scenario 4, case 1
Case 2: Mapping an entry when a unique attribute is not present
Sometimes it is difficult to identify a unique attribute to use for the mapping. For example, if you want
to map multiple entries in the local directory server to a single entry in pass-through server. In such a
case, the administrator must be aware of an entry DN in the directory server that can be directly
mapped to an entry DN in the pass-through server. The administrator must use the ibmPtaLinkAttribute attribute to set the DN in the passthrough server. Set the ibm-PtaLinkAttribute
attribute to _DN_, and the ibm-PtaLinkValue attribute to the DN of the entry in pass-through server.
This technique is shown in "Listing 14: Thom 888 entry for scenario 4, case 2."
dn: cn=Thomas Gray1,o=sample1
objectclass: inetOrgPerson
objectclass: organizationalPerson
objectclass: person
objectclass: top
uid:Thom888
sn: Gray
objectclass: ibm-ptaReferral
ibm-ptaLinkAttribute: _DN_
ibm-ptaLinkValue: cn=Thom456,c=in,dc=com
Listing 14: Thom 888 entry for scenario 4, case 2
By setting these values in the entry, the PTA interface takes the specified DN value and binds with the
user provided credentials at the pass-through server. However, if an entry also has the ibm-ptaReferral
auxiliary class, then the attribute mapping configured for the entry will be ignored.
To configure PTA interface, issue the command as shown in "Listing 15: Configure the PTA interface
for scenario 4, case 2."
idsldapmodify -h <hostname> -p <port> -D <adminDN> -w <adminPWD>
dn: cn=Passthrough Server5, cn=Passthrough Authentication,
cn=Configuration
changetype: add
cn: Passthrough Server5
ibm-slapdPtaURL: ldap://<PTA hostname>:<port>
ibm-slapdPtaSubtree: o=sample1
ibm-slapdPtaAttrMapping: uid $ userPrincipalName
ibm-slapdPtaSearchBase: c=in,dc=com
ibm-slapdPtaBindDN: <bind DN>
ibm-slapdPtabindPW: <bind Password>
ibm-slapdPtaMigratePwd: TRUE
objectclass: top
objectclass: ibm-slapdConfigEntry
objectclass: ibm-slapdPta
objectclass: ibm-slapdPtaExt
Note: If administrator
does not want PTA to be
performed for a specific
entry, then he must set
the value of the ibmptaLinkAttribute attribute
to "_DISABLE_".
Listing 15: Configure the PTA interface for scenario 4, case 2
3.1.5 Scenario 5: Configuring pass-through authentication to Active
Directory Global Catalog
If a user wants to authenticate to an external server instead of the local server, the user is required to
configure attribute mapping for pass-through authentication.
User must provide information such as the search base (ibm-slapdPtaSearchBase), server URL (ibmslapdPtaURL), bind DN, and other information about the pass-through server against which the user
intends to authenticate.
However, if the user want to authenticate to an Active Directory forest instead of an individual external
server, then the user must specify a search base of "". To search Active Directory Global Catalog, user
must specify the pass-through authentication settings in the configuration.
Please note this scenario is supported from Tivoli Directory Server version 6.3 and above.
To enable PTA for this scenario issue the command shown in "Listing 16: Enable the PTA for scenario
5,"
ldapmodify -h <hostname> -p <port> -D <adminDN> -w <adminPWD>
dn: cn=Configuration
changetype: modify
replace: ibm-slapdPtaEnabled
ibm-slapdPtaEnabled: true
Listing 16: Enable the PTA for scenario 5
To configure PTA interface for this scenario, issue the command shown in "Listing 17: Configure the
PTA interface for scenario 5,"
idsldapmodify -h <hostname> -p <port> -D <adminDN> -w <adminPWD>
dn: cn=Passthrough Server1, cn=Passthrough Authentication, cn=Configuration
cn: Passthrough Server1
ibm-slapdPtaAttrMapping: cn $ uid
ibm-slapdPtaBindDN: <valid_DN>
ibm-slapdPtabindPW: <DN_password>
ibm-slapdPtaSearchBase:
ibm-slapdPtaSubtree: <Local subtree>
ibm-slapdPtaURL: ldap://<PTA hostname>:3268
objectclass: top
objectclass: ibm-slapdConfigEntry
objectclass: ibm-slapdPta
objectclass: ibm-slapdPtaExt
Listing 17: Configure the PTA interface for scenario 5
The value of the ibm-slapdPtaSearchBase attribute must not be set (that is, must be left empty). TDS
performs a search to Active Directory with search base as " " to make it a Global Catalog search. The
search is routed through Global Catalog port, 3268.
To learn more about Active Directory Global Catalog, see the Microsoft TechNet site: Global Catalog
and LDAP Searches.
3.2 Configure a PTA over multiple suffixes
LDAP administrator can configure a PTA server over multiple suffixes / subtrees, but will have to
consider several points:
1.
One PTA server can be configured per subtree. For example, if there is a PTA server configured for
"o=ibm, c=in" subtree, the administrator can not configure second PTA server for same
(o=ibm,c=in) subtree.
Note: Administrator can configure same subtree to multiple PTA servers using advanced PTA
features provided in IBM Security Directory Server Version 6.3.1.5 and above.
2.
You can use one PTA server for more than one subtrees (for example, administrator can have one
PTA server for configuring multiple subtrees such as "o=ibm,c=us", "o=ibm,c=in", etc.).
To enable PTA server, issue the command shown in "Listing 18: Enable PTA for muliple servers.":
ldapmodify -h <hostname> -p <port> -D <adminDN> -w <adminPWD>
dn: cn=Configuration
changetype: modify
replace: ibm-slapdPtaEnabled
ibm-slapdPtaEnabled: true
Listing 18: Enable PTA for muliple servers
To configure PTA servers for mutiple suffixes issue a command similar to the one shown in "Listing
19: Configure multople PTA servers."
dn: cn=Passthrough server, cn=Passthrough Authentication, cn=configuration
cn: Passthrough server
ibm-slapdptaattrmapping: cn $ sAMAccountName
ibm-slapdPtaBindDN: <valid_DN>
ibm-slapdPtabindPW: <DN_password>
ibm-slapdptaconnectionpoolsize: 6
ibm-slapdptamigratepwd: true
ibm-slapdptaresulttimeout: 1000
ibm-slapdptasearchbase:
ibm-slapdptasubtree: o=ibm, c=in
ibm-slapdptaurl: ldap://<PTA host1 or PTA host2 as per requirement>:3268
objectclass: top
objectclass: ibm-slapdPta
objectclass: ibm-slapdConfigEntry
objectclass: ibm-slapdPtaExt
dn: cn=Passthrough server0, cn=Passthrough Authentication, cn=configuration
cn: Passthrough server0
ibm-slapdptaattrmapping: cn $ sAMAccountName
ibm-slapdPtaBindDN: <valid_DN>
ibm-slapdPtabindPW: <DN_password>
ibm-slapdptaconnectionpoolsize: 6
ibm-slapdptamigratepwd: true
ibm-slapdptaresulttimeout: 1000
ibm-slapdptasearchbase:
ibm-slapdptasubtree: o=ibm, c=us
ibm-slapdptaurl: ldap://<PTA host1 or PTA host2 as per requirement>:3268
objectclass: top
objectclass: ibm-slapdPta
objectclass: ibm-slapdConfigEntry
objectclass: ibm-slapdPtaExt
Listing 19: Configure multople PTA servers
New Objectclasses and attributes in PTA
This section describes the object classes and attributes associated with pass-through authentication
interface. The PTA configuration is defined in a TDS instance configuration file "ibmslapd.conf". To
enable or disable PTA, the ibm-slapdPtaEnabled attribute under the "cn=configuration" DN entry must
be modified. The ibm-slapdPtaEnabled attribute must be set to TRUE to enable the PTA feature, and set
to FALSE to disable the PTA feature. A container entry "cn=Passthrough Authentication,
cn=configuration" is present in the configuration file, and all subtree entries specific to PTA
configuration must be one level below this container.
There are structural and auxiliary object classes associated with a PTA entry in the configuration file:
•
Structural objectclass:
ibm-slapdPta: This object class contains a subtree specific to pass-through authentication settings, and
must be added to a PTA entry that is one level below the container entry "cn=Passthrough
Authentication, cn=configuration".
•
Auxiliary objectclass:
ibm-slapdPtaExt: This object class contains attribute mapping settings for the pass-through
authentication subtree entry. This object class must be added to a PTA entry with the ibm-slapdPta
objectclass to specify the attribute mapping.
ibm-PtaReferral: This object class is used to configure the PTA linking attribute for pass-through
authentication in an individual entry with in directory information tree (DIT).
The MUST and MAY attributes associated with the structural and auxiliary object classes.
3.3 Attributes associated with the ibm-slapdPta objectclass
This section describes the attribures for the ibm-slapdPta objectclass.
Attribute name: ibm-slapdPtaURL
Attribute type: MUST
Description : The URL information of the pass-though server. The URL must contain the fully
qualified host name or IP address along with the port information.
Example
: ldap://server:port or ldaps://server:port (for SSL)
Attribute name: ibm-slapdPtaSubtree
Attribute type: MUST
Description : This must-contain, multi-valued attribute defines the sub-tree in the local directory for
which Tivoli Directory Server will perform pass-through authentication. Special sub-trees like
cn=configuration, cn=schema, cn=pwdpolicy,cn=ibmpolicies and cn=changelog are not allowed as
values for this attribute. Nested sub-trees are not allowed to be values for this attribute (i.e., c=US and
o=ibm,c=US both cannot be specified as values for this attribute). If nested sub-tress specified, the
server will fail to start in the normal mode.
Example
: o=sample
Attribute name: ibm-slapdPtaResultTimeout
Attribute type: MAY
Description : This is an optional attribute, which, if specified, defines the time in milliseconds that
Tivoli Directory Server will wait to receive the result of a bind operation against the pass-through
server. If the result is not received within the defined time period, Tivoli Directory Server returns
LDAP_INVALID_CREDENTIALS to the client. Its default value is 1000 ms. A value of 0 indicates
that the bind operation will not wait and will return immediately after checking the result. Only values
in the range of 0 to 60000 ms (1 minute) are supported.
Example
: 1000
Attribute name: ibm-slapdPtaMigratePwd
Attribute type: MAY
Description : This optional attribute indicates that a successful bind request to the pass-through
directory should be followed by a migration of the bind credentials to the local directory (Tivoli
Directory Server). If this attribute is not defined, , the default behavior is to not perform credential
migration. Once the credential migration is performed, subsequent bind operations for that entry would
be executed against the local directory and not against the pass-through directory.
Example
: false
Attribute name: ibm-slapdPtaConnectionPoolSize
Attribute type: MAY
Description : This optional attribute indicates the number of connections to be opened against the
pass-through server to handle frequent bind requests. This attribute is intended to achieve performance
improvements in pass-through authentication by keeping multiple connections open at all times;
however, if the pass-through directory server disconnects inactive connections, creating a connection
pool uisng this option may not be efficient. This attribute supports values ranging from 2 to 15. Any
other value specified for this attribute cause the server to start in configuration mode. If this attribute is
not defined, , a connection pool of size 4 is used.
Example
:4
3.4 Attributes associated with the ibm-slapdPtaExt objectclass
Attribute name: ibm-slapdPtaSearchBase
Attribute type: MUST
Description : This required attribute defines the distinguished name of the sub-tree base in the passthrough server that will be searched when processing bind requests.
Example
: o=sample1
Attribute name: ibm-slapdPtaAttrMapping
Attribute type: MUST
Description : This required attribute stores the attribute mapping for pass-through authentication. For
example, if 'attr1' in Tivoli Directory Server maps to 'attr2' in the pass-through server, this attributes
value will be 'attr1$attr2'.
During server startup, Tivoli Directory Server will check that 'attr1' is a valid attribute in its schema. If
the pass-through server is running, it will also attempt to check that 'attr2' is a valid attribute in the
pass-through server's schema. A warning will be issued if the attempt to verify 'attr2' in the passthrough server fails. Tivoli Directory Server expects that 'attr1' is single-valued. As part of passthrough authentication, the entry in the pass-through server identified by the filter ('attr2' = value of
'attr1' in Tivoli Directory Server) within the sub-tree identified by ibm-slapdPtaSearchBase is looked
up. It is expected that this lookup yields a single entry in the pass-through server. If multiple entries are
returned, it is termed as a bind failure. If a single corresponding entry is found in the pass-through
server, a bind is performed against it.
Example
: <attr1> $ <attr2>
Attribute name: ibm-slapdPtaBindDN
Attribute type: MUST
Description : This required attribute indicates the distinguished name to be used for binding against
the pass-through server when performing a lookup when an attribute mapping has been defined.
Example
: cn=admin1
Attribute name: ibm-slapdPtaBindPW
Attribute type: MUST
Description : This required attribute indicates the bind password to be used for binding against the
pass-through server when performing lookup when an attribute mapping has been defined.
Example
: password123
3.5 Attributes associated with the ibm-PtaReferral objectclass
Attribute name: ibm-PtaLinkAttribute
Attribute type: MUST
Description : If the value of this attribute is _DN_, the value of the corresponding ibm-ptaLinkValue
will be used as the distinguished name of the entry in the pass-through server, thereby eliminating the
need for a lookup.
If the value of this attribute is _DISABLE_, then pass-through authentication is disabled for this entry.
In all other cases, this attribute will store the name of the attribute to be used for lookup in the passthrough server. This is needed because the attribute mapping as defined in the ibmslapdPtaAttrMapping attribute applies to all entries. If an entry needs some special attribute mapping,
that can be achieved through this attribute.
Example
: empNo
Attribute name: ibm-PtaLinkValue
Attribute type: MUST
Description : This required attribute holds the value corresponding to ibm-slapdPtaLinkAttribute.
Example
: E0345
4 Tips for Administrator when configuring PTA
This sections lists some important considerations to keep in mind when configuring PTA.
1. The proxy server does not support pass-through authentication in TDS 6.1 release because the
proxy server does not pass on the given bind DN and password to the backend server.
2. Digest/Kerberos or any customized bind mechanisms are not supported.
3. Referring to the ibmslapd.log file should be the first steps when debugging problems with PTA.
See "Troubleshooting pass-through authentication" for more instight into debugging PTA
problems.
4. TDS performs a search on the PTA server when attribute mapping is configured. If the search
returns more than one entry, an error message is recorded in the logs to trace the reason for
the failure.
5. Administrators must ensure that the DNs are mirrored properly, i.e when entry gets modified on
PTA Server then it should get modified on TDS as well.
6. Administrator can use appropriate tool such as IBM Tivoli Directory Integrator to keep
consistency between TDS and the PTA Server.
7. One PTA server can be configured per subtree. For example, if there is a PTA server configured
for "o=ibm, c=in" subtree, the administrator can not configure second PTA server for same
(o=ibm,c=in) subtree. PTA configuration will fail if administrator configure two PTA servers
for same subtree.
8. Administrator can configure same subtree to multiple PTA servers using advanced PTA features
provided in IBM Security Directory Server Version 6.3.1.5 and above.
9. Administrator can use one PTA server for more than one subtrees (for example, administrator
can have one PTA server for configuring multiple subtrees such as "o=ibm,c=us",
"o=ibm,c=in", etc.).
10.
11. The pass-through server that holds the user credentials can be Active Directory or an LDAP V3
compliant directory (including another Tivoli Directory Server).
12. All configuration changes related to pass-through authentication require a server restart to make
the changes effective. Changes to the ibm-slapdPtaEnabled attribute, a dynamic attribute,
requires a readconfig extended operation to be performed to make the changes effective, as
shown in "Listing 20: Example of a readconfig operation."
idsldapexop -h <hostname> -p <port> -D <adminDN> -w <adminPW> -op readconfig
-scope single "cn=Configuration" ibm-slapdPtaEnabled
Listing 20: Example of a readconfig operation
13. All the entries mentioned in the scenarios must be within a configured subtree.
5 Troubleshooting pass-through authentication
This section documents some guidelines for Administrator to consider when troubleshooting the PTA
configuration. If the problems persists you can contact IBM Support as specified in section "How to
report a PTA problem" below.
5.1 When the server starts is Config-only mode
5.1.1 When error code 81 is reported
When the server starts in Config-only mode, the Administrator may observe messages in ibmslapd.log
(<instance home location>/idsslapd-<instance_name>/logs/ibmslapd.log) file similar to those in
"Listing 21: Return code 81 message."
This indicate that the server is unable to communicate to the PTA server. Here are some steps to try to
resolve the issue: :
07/22/13 11:07:30 GLPSRV175W Unable to check schema of pass-through directory
'ldap://<PTA-server-hostname>:389' for attribute 'sAMAccountName', received
return code 81.
Listing 21: Return code 81 message
- Check to ensure the PTA server is up and running.
- Check to ensure the password value provided for 'ibm-slapdPtaBindDN' attribute in TDS
configuration file is same as password value present in PTA back-end server.
- If SSL is configured, then administrator might need to enable the Server's ASCII traces and check to
look for messages similar to those shown in "Listing 22: ldap_getenv message." if messages similar to
following are observed in trace output file.
202:16:35:30 T1 K21889245 ldap_getenv: TDS_PTA_SERVER_TIMEOUT_MS=NULL
Listing 22: ldap_getenv message
This shows that there might be network latency issue between TDS and the PTA server. To resolve this
latency issue, the Administrator needs to set the SSL_TIMEOUT_MILLISEC environment variable.
Please refer link - http://www-01.ibm.com/support/docview.wss?uid=swg21233758 for more
information.
To enable Server ASCII traces please refer link - http://www-01.ibm.com/support/docview.wss?
uid=swg21268246
5.1.2 When error code 81 is reported (SSL)
When the server starts in configuration only mode, messages similar to the ones shown in "Listing 23:
error code 81" may be recorded in ibmslapd.log file:
02/06/13 12:19:33 GLPSRV175W Unable to check schema of pass-through directory
'ldaps://<PTA-server-hostname>:636' for attribute 'sAMAccountName', received
return code 81.
Listing 23: error code 81
In the trace output file might contain error messages similar to those in "Listing 24: SSL messages."
037:12:19:33 T648251136 open_ldap_connection: SSL In use!
037:12:19:33 T648251136 open_ssl_connection(): set sd=25
037:12:19:33 T648251136 open_ssl_connection(): ld->ld_ssl_cipher == <null>.
037:12:19:33 T648251136 ssl_write: -----> Entering ssl_write
037:12:19:33 T648251136 ssl_write: <----- Leaving ssl_write rc=66
037:12:19:33 T648251136 ssl_read: -----> Entering ssl_read
037:12:19:33 T648251136 ssl_read: <----- Leaving ssl_read rc=5
037:12:19:33 T648251136 ssl_read: -----> Entering ssl_read
037:12:19:33 T648251136 ssl_read: <----- Leaving ssl_read rc=4960
037:12:19:33 T648251136 ssl_write: -----> Entering ssl_write
037:12:19:33 T648251136 ssl_write: <----- Leaving ssl_write rc=7
037:12:19:33 T648251136 Error - open_ssl_connection(): gsk_secure_soc_init() rc=414
GSK_ERROR_BAD_CERT
037:12:19:33 T648251136 In open_ssl_connection(): closing ssl session and freeing
socket buffer resources.
037:12:19:33 T648251136 open_ldap_connection: open_ssl_connection failed with
rc=116
037:12:19:33 T648251136 ldap_write_msg: open_ldap_connection returned error!
037:12:19:33 T648251136 ldap_msg_table_send_message: failed to send request
message, rc=81, removing request msg from table
037:12:19:33 T648251136 ldap_msg_table_release_msgid entered
(table=0x7fbc1c2ea7d0), msgid=1
037:12:19:33 T648251136 ldap_msg_table_release_msgid_direct: entered with msgid=1,
table=0x7fbc1c2ea7d0
037:12:19:33 T648251136 free_msg: msg(0x7fbc1c2e64a0), all(0)
037:12:19:33 T648251136 ldap_err2string: err(81)
037:12:19:33 T648251136 ldap_simple_bind_direct: returning rc=81, error=Can't
contact LDAP server
037:12:19:33 T648251136 ldap_sasl_bind_s: returning rc=81
037:12:19:33 T648251136 ptaConnection::ldapBind: Failed to send bind request, rc=81
Listing 24: SSL messages
These messages indicate that there is an SSL certificate issue. To resolve this kind of problems verify:
1. that SSLis properly configured,
2. that the key file password is not expired,
3. that you have imported CA Root Certificate into GSkit.
5.1.3 No PTA related messages logged in ibmslpad.log, but the server
starts in config only mode
In the trace output file, the Administrator might see messages similar to those shown in "Listing 25:
Decryption failure."
064:09:27:07 T-1208374592 Retrieving values for attribute ibm-slapdptabindpw !
064:09:27:07 T-1208374592 aesDecryptBuffer: Entering. inBuffer = 0x854fca8,
outBuffer = 0xbfad1fe8, cipherName = 0x309a62, keyData = 0x8270070
064:09:27:07 T-1208374592 initIccCrypto: Entering. iccCtx = 0xbfad1e58
064:09:27:07 T-1208374592 initIccCrypto: Leaving. rc = 0
064:09:27:07 T-1208374592 initIccCipher: Entering. iccCtx = 0x827bdf8, cipherCtx =
0xbfad1e50, cipherName = 0x309a62, cipher = 0xbfad1e54
064:09:27:07 T-1208374592 initIccCipher: Leaving. rc = 0
064:09:27:07 T-1208374592 Error - aesDecryptBuffer: ICC_EVP_DecryptFinal() failed.
rc = 1
Listing 25: Decryption failure
These messages indicate that the TDS server is unable to decrypt an encrypted value in the
configuration file.
To resolve this problem refer to: http://www-01.ibm.com/support/docview.wss?uid=swg21392004
5.2 When error code 49 is reported
In this scenario TDS starts successfully but pass-through authentication does not work. The
ibmslapd.log file records messgages similar to those shown in "Listing 26: Error 49."
Oct 18 09:54:14 2013 GLPSRV175W Unable to check schema of pass-through directory
'ldap://9.121.215.190:389' for attribute 'sAMAccountName', received return code
49.
Oct 18 09:54:14 2013 GLPCOM003I Non-SSL port initialized to 4389.
Oct 18 09:54:16 2013 GLPRPL137I Restricted Access to the replication topology is
set to false.
Oct 18 09:54:16 2013 GLPSRV009I 6.3.0.0 server started.
Listing 26: Error 49
To resolve this situation, check the PTA configuration in the ibmslapd.conf file and make sure that the
value of the "ibm-slapdptasearchbase" atrribute is not empty. If port 389 is specified in "ibmslapdPtaURL" attribute then the server always expects a search base value for
"ibm-slapdptasearchbase" attribute.
Note: if the user want to authenticate to an Active Directory forest instead of an individual external
server, then the user must specify a search base of "" with port "3268" in the "ibm-slapdPtaURL"
attribute. For more information refer scenario "Scenario 5: Configuring pass-through authentication to
Active Directory Global Catalog.".
5.3 User password synchronization
If the PTA is configured for password migration (See "Scenario 2: Attribute mapping is configured,
entry is present locally, and password migration is enabled."), the password will be migrated from the
pass-through server to the local TDS server the first time the user is authenticated. After the first
timeTDS will not contact the pass-through server for authentication. The administrator must maintain
password consistency between the pass-through server and the TDS server as explained in " Scenario
2: Attribute mapping is configured, entry is present locally, and password migration is enabled.." The
administrator must either have a way to synchronize the passwords, or the administrator must confiugre
the TDS server to not migrate passwords.
5.4 How to report a PTA problem
You can provide the following information along with clear description of problem to help support
personnel effectively solve your PTA problems:
1. In order to diagnose PTA issue, it is important to collect the log and configuration files. Please
refer http://www-01.ibm.com/support/docview.wss?uid=swg21269702 this link.
2. As specified earlier in some cases Server Ascii traces are required to diagnose the problem.
Please refer http://www-01.ibm.com/support/docview.wss?uid=swg21268246 this link.
Providing the above information would help the support personnel to respond very quickly if it
is a trivial/common problem. To contact IBM Support, please refer link http://www-947.ibm.com/support/entry/portal/support?brandind=Tivoli
6 Resources
1. Pass-through authentication with Proxy server
2. Advanced pass-through authentication scenarios in IBM Security Directory Server 6.3.1.5
3. Tivoli Directory Server 6.1 Pass-through Authentication STE
4. Tivoli Directory Server Documentation
7 About the authors
Amit is a Staff Software Engineer at IBM Software Labs, India. He is working as a part of the IBM
Security Directory Server Level2 Support team. Previously, he worked as a Software Test Engineer for
IBM Security Access Manager for Operating Systems.
Mayur is a Associate Software Engineer at IBM India Software Labs. Currently working as Level 2
Support Engineer on Security Directory Server and IBM Security Access Manager for Enterprise
Single Sign-on. Previously worked as Software Test Engineer on IBM Security Access Manager for
Enterprise Business.