Configure Pass-Through Authentication on IBM Tivoli Directory Server

Transcription

1 Configure Pass-Through Authentication on IBM Tivoli Directory Server Amit Aherao Staff Software Engineer, IBM India Software Labs. Mayur Boob Software Engineer, IBM India Software Labs. 5 th May 2014, Rev th 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.

2 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 The basic scenarios Scenario 1: Attribute mapping is configured and the entry is present locally Scenario 2: Attribute mapping is configured, entry is present locally, and password migration is enabled Scenario 3: Attribute Mapping is Not Configured and the Entry is Not Present Locally Scenario 4: Mapping multiple entries in Tivoli Directory Server to one entry in pass-through server Scenario 5: Configuring pass-through authentication to Active Directory Global Catalog Configure a PTA over multiple suffixes Attributes associated with the ibm-slapdpta objectclass Attributes associated with the ibm-slapdptaext objectclass Attributes associated with the ibm-ptareferral objectclass Tips for Administrator when configuring PTA Troubleshooting pass-through authentication When the server starts is Config-only mode When error code 81 is reported When error code 81 is reported (SSL) No PTA related messages logged in ibmslpad.log, but the server starts in config only mode When error code 49 is reported User password synchronization How to report a PTA problem Resources About 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 Listing 3: myuniqueattribute added to local server entries...7 Listing 4: Configure PTA for Scenarion 1, case Listing 5: Enabling PTA for scenario Listing 6: Configure the PTA for scenario Listing 7: Enable PTA for scenario Listing 8: Configure the PTA interface for scenario Listing 9: Enable PTA for scenario 4...9

3 Listing 10: Entry for Thom Listing 11: Entry for Thom Listing 12: Thom888 entry with ibm-ptalinkattribute set...11 Listing 13: Configure the PTA for Scenario 4, case Listing 14: Thom 888 entry for scenario 4, case Listing 15: Configure the PTA interface for scenario 4, case Listing 16: Enable the PTA for scenario Listing 17: Configure the PTA interface for scenario 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 Listing 24: SSL messages...20 Listing 25: Decryption failure...21 Listing 26: Error

4 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

5 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 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::

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

7 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: 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: ibm-slapdconfigentry objectclass: ibm-slapdpta objectclass: ibm-slapdptaext Listing 4: Configure PTA for Scenarion 1, case 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.

8 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: ibm-slapdconfigentry objectclass: ibm-slapdpta objectclass: ibm-slapdptaext Listing 6: Configure the PTA for scenario 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.

9 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: ibm-slapdconfigentry objectclass: ibm-slapdpta Listing 8: Configure the PTA interface for scenario 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.

10 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: 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: 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."

11 dn: cn=thomas Gray1,o=sample1 objectclass: inetorgperson objectclass: organizationalperson objectclass: person 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: 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 ibm- PtaLinkAttribute 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."

12 dn: cn=thomas Gray1,o=sample1 objectclass: inetorgperson objectclass: organizationalperson objectclass: person 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: ibm-slapdconfigentry objectclass: ibm-slapdpta objectclass: ibm-slapdptaext Listing 15: Configure the PTA interface for scenario 4, case 2 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_" 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.

13 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: 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, 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 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.":

14 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: 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: 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,

15 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

16 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 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 : 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

17 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 : password 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

18 Description : This required attribute holds the value corresponding to ibm-slapdptalinkattribute. Example : E 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 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.) 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.

19 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 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 K 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 - for more information. To enable Server ASCII traces please refer link - uid=swg 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:

20 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 T open_ldap_connection: SSL In use! 037:12:19:33 T open_ssl_connection(): set sd=25 037:12:19:33 T open_ssl_connection(): ld->ld_ssl_cipher == <null>. 037:12:19:33 T ssl_write: -----> Entering ssl_write 037:12:19:33 T ssl_write: <----- Leaving ssl_write rc=66 037:12:19:33 T ssl_read: -----> Entering ssl_read 037:12:19:33 T ssl_read: <----- Leaving ssl_read rc=5 037:12:19:33 T ssl_read: -----> Entering ssl_read 037:12:19:33 T ssl_read: <----- Leaving ssl_read rc= :12:19:33 T ssl_write: -----> Entering ssl_write 037:12:19:33 T ssl_write: <----- Leaving ssl_write rc=7 037:12:19:33 T Error - open_ssl_connection(): gsk_secure_soc_init() rc=414 GSK_ERROR_BAD_CERT 037:12:19:33 T In open_ssl_connection(): closing ssl session and freeing socket buffer resources. 037:12:19:33 T open_ldap_connection: open_ssl_connection failed with rc= :12:19:33 T ldap_write_msg: open_ldap_connection returned error! 037:12:19:33 T ldap_msg_table_send_message: failed to send request message, rc=81, removing request msg from table 037:12:19:33 T ldap_msg_table_release_msgid entered (table=0x7fbc1c2ea7d0), msgid=1 037:12:19:33 T ldap_msg_table_release_msgid_direct: entered with msgid=1, table=0x7fbc1c2ea7d0 037:12:19:33 T free_msg: msg(0x7fbc1c2e64a0), all(0) 037:12:19:33 T ldap_err2string: err(81) 037:12:19:33 T ldap_simple_bind_direct: returning rc=81, error=can't contact LDAP server 037:12:19:33 T ldap_sasl_bind_s: returning rc=81 037:12:19:33 T 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 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."

21 064:09:27:07 T Retrieving values for attribute ibm-slapdptabindpw! 064:09:27:07 T aesdecryptbuffer: Entering. inbuffer = 0x854fca8, outbuffer = 0xbfad1fe8, ciphername = 0x309a62, keydata = 0x :09:27:07 T initicccrypto: Entering. iccctx = 0xbfad1e58 064:09:27:07 T initicccrypto: Leaving. rc = 0 064:09:27:07 T initicccipher: Entering. iccctx = 0x827bdf8, cipherctx = 0xbfad1e50, ciphername = 0x309a62, cipher = 0xbfad1e54 064:09:27:07 T initicccipher: Leaving. rc = 0 064:09:27:07 T 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: 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: GLPSRV175W Unable to check schema of pass-through directory 'ldap:// :389' for attribute 'samaccountname', received return code 49. Oct 18 09:54: GLPCOM003I Non-SSL port initialized to Oct 18 09:54: GLPRPL137I Restricted Access to the replication topology is set to false. Oct 18 09:54: GLPSRV009I 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.

22 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 this link. 2. As specified earlier in some cases Server Ascii traces are required to diagnose the problem. Please refer 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 Resources 1. Pass-through authentication with Proxy server 2. Advanced pass-through authentication scenarios in IBM Security Directory Server 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.