LDAP Troubleshooting Checklist

1. Product Basics
LDAP (Lightweight Directory Access Protocol), is an internet protocol for querying and modifying directory services running over TCP/IP. Many Enterprises use the LDAP system, as well as a dedicated LDAP server to create their user account to provide single sign on where one login for a user is shared between many services. Agile supports:

Microsoft Active Directory Server Sun One Directory Server Oracle Internet Directory (after 9.3.1 version) All users except supplier users can be migrated from LDAP to Agile Note: Supplier users are created only in web client as Database Users with restricted roles by default. If the customer would like to convert supplier users to LDAP users, they would need to create supplier users on their LDAP server first then we can manually convert these users by altering database values. Agile/LDAP integration is a one-way communication, which means Agile queries data from LDAP and writes to Agile, but we don't touch LDAP server.
Log files: oc4j or default_group log Ldap-migration.log How it flows: PLM client enters login ID LDAP engine makes connection to the db to check whether this is a db user or LDAP user

Starts an ldap session by connecting to LDAP server If is ldap user over port 389 or 663, based on the ldap configuration Uses ldap user and password to authenticate and logs into LDAP server

Authentication succeeds and logs into Agile

Use the search filter to find the user in LDAP server

2. Configuration
2.1 Configuration file : Sample configuration file

LDAP Troubleshooting Checklist

Page 1 of 16

2.2 Step by step configuration verification Filed Name ID What is it?

Unique string identifying the LDAP server. The string must be less than 30 characters and

How to Verify? Ex: agile001, agile002

LDAP Troubleshooting Checklist

Page 2 of 16

cannot be changed once in use.

Descrip Information about the server configuration tion Agent

The Directory Server used for authentication; valid values are SunONEDirectory or ActiveDirectory The URL for the authentication agent The authentication string when using Active Directory Server in the format of xyz.com Username (does not need to be the LDAP Administrator)

any
--SunONEDirectory or -- ActiveDirectory

URL Domai n

ex: ldap://SLDC01.sl.agilesoft.com:389 -- double check with Ad admin to get correct Server URL Domain based on the above server URL. --ex: sl.agilesoft.com

Userna me

User path

Tree under which all Agile users can be found; this property should be set to the node closest to the root of the Directory Tree structure; any user that is not found under the subtree starting at this node should not be on the Agile system.

This user needs to have discover, read and query privilege to the LDAP server. --ex: Ldapuser1@sl.agilesoft.com --use this username and password to log into LDAP server to navigate --Ask the customer to send you a tree structure to verify the path. --common tools we use: 1. direct connection to the AD server 2. popular LDAP browser : Search google for Softerra LDAP Browser 3. read path from bottom to top -SLDC01.sl.agilesoft.com -OU=LDAP Test -CN=LDAP User1 Path: cn=LDAP User1,ou=LDAP Test,dc=sl,dc=agilesoft,dc=com

Search scope

Scope of search for Agile users under the user-path node; valid values are ONE_LEVEL or SUB_TREE; this property should be set to ONE_LEVEL only if all users in the organization are directly under the User Path node

ONE_LEVEL or SUB_TREE

LDAP Troubleshooting Checklist

Page 3 of 16

Search filter

Search filter for Agile users under the <user-path> node; this must be a valid LDAP search filter that matches all Agile users under the scope defined by <auth.ldap.user.path> and <auth.ldap.user.search.scope >; users not matching this filter are considered invalid users on the Agile system; a valid LDAP search filter must be enclosed in parentheses. Authentication mechanism supported by the directory server; valid values are "simple" or "strong"

Ex: (objectclass=person) All users (objectclass=group) All groups (cn= LDAP User1) Only this user (OU=Support) Only Support group

Mecha nism

simple

2.3 Whats the difference between User search and Group search? Customer has options to use either user search filter, group search filter or both. Path, scope, filter setting will determine how many users will be synchronized. In the following example: 1. If using only user search filter, only users will be migrated: User1 to User10; 2. If using only group search filter, only LDAPGroup1, LDAP Group 2 and LDAP Group 3 will be migrated and all users within these groups; 3. If using both, then all Ten users and three groups will be migrated.
LDAP tree structure

LDAP Troubleshooting Checklist

Page 4 of 16

Example 1: With the following configuration of searching only for users, Only users will be migrated

LDAP Troubleshooting Checklist

Page 5 of 16

LDAP Troubleshooting Checklist

Page 6 of 16

Example 2: With the following configuration of searching only for groups, Only users in the groups will be migrated

LDAP Troubleshooting Checklist

Page 7 of 16

Example 3: With the following configuration of searching for both users and groups, All 10 users, 3 user groups, will be migrated

LDAP Troubleshooting Checklist

Page 8 of 16

LDAP Troubleshooting Checklist

Page 9 of 16

Group will not be shown in the preview window; you will need to go to Users |User Group to find the groups

LDAP Troubleshooting Checklist

Page 10 of 16

2.4 How to map additional attributes? By default, the following attributes are synchronized from LDAP to Agile.

Customers can map additional fields between LDAP and Agile by clicking green + sign. Currently we only support page two fields.

LDAP Troubleshooting Checklist

Page 11 of 16

LDAP Troubleshooting Checklist

Page 12 of 16

2.5 Multiple domains need multiple LDAP nodes.

2.6 How to setup failover configuration? Server replication improves the availability of a directory service. When the primary directory server goes down, users can still be authenticated via the backup server. On the Edit LDAP page, in the URL field, type a semicolon (;) after the existing URL, then (with no space) type the URL of a backup or secondary server. Syntax as below:
<url>ldap://SLDC01.sl.agilesoft.com:389; ldap://SLDC02.sl.agilesoft.com:389</url>

2.7 Syntax to query multiple groups There are times that a customer wants to sync multiple groups under the same domain. For example, under LDAP Test tree, you only want to sync users in Group 1 and Group 2 but not Group3. You can specify this in the Group filter and here is the syntax: Group Filter: (&(objectCategory=Group)(|(cn=LDAP Group 1)(cn=LDAP Group 2)))

3. General Troubleshooting
1. Is LDAP enabled? In 9.2.2.4, LDAP is by default enabled. No need to modify agile.properties file, as long as the configuration is valid in Java Client, agile will sync the users. 2. Is LDAP group enabled ? To sync groups, modify agile.properties file Under j2ee\home\....\App-INF
LDAP Troubleshooting Checklist Page 13 of 16

Set: Auth.ldap.group.enabled=true
--With User Group "sync" function enabled, you cannot remove or add users in UI on a user group's Users tab that have been synchronized (that is, where users have been added to a user group via LDAP). --With LDAP group sync enabled, you can no longer add ldap users to any Agile Groups.

3. General troubleshooting path on the problem of users not able to login:

yes

Is this a new implementation?

no Find out whats changed? 1. Make sure users are active in LDAP; 2. make sure users are under correct user path and group path on AD server
still not work

Check the configuration one by one. The best way is to use Softerra with specified username and password to login and follow the path specified no Does preview work?
yes

few user

Is this login problem for all users or few user?

1. Double check user path/filter and group path/filter. Reference:

all users Note 569003.1 2. Check log files for detail errors

LDAP Troubleshooting Checklist

Check DB: >select loginid, auth_src, guid from agileuser where loginid=xxxx; --auth_src should =LDAP_xxx; --guid=unique numbers

fix

Reset values in db and re-sync. See Reference: Note 569483.1

still fails

Time to contact Support

Page 14 of 16

4. Common requests and Known Issues

--How to covert database users to LDAP users?
See Note: Note 568607.1

--How to hide LDAP node? LDAP node by default is visible. Defect on the doc of The LDAP node may not be visible in your out-of-box Administrator tree. If your company does not use an LDAP system, the node is not needed. The node is made visible through the AppliedTo capability; see Administrator Privilege and the AppliedTo Capability (on page 187). --LDAP users synchronize properly but cannot logon See note: Note 569003.1 --9.2.2.4 HF6 --Not able to sync users after initial implementation --Configuration for BEA weblogic First is to configure Java Client LDAP node and make sure the Preview works. Second is to configure Weblogic console. See PLM admin guide for detail configuration. --A new feature introduced after 9227 release. Disable Agile User if not found in LDAP. This can be found in the LDAP configuration window. --Agile utilities: Utility Checkldapconfig.cmd Migrateuserstodb.cmd Migrateuserstodb r Migrateuserstodb R

Why use it? To check the connection and LDAP config To bring users over from LDAP To clear all LDAP user values in the db To clear all DB user values in the db

Other References: --Agile PLM Administrator Guide

LDAP Troubleshooting Checklist

Page 15 of 16

--Search filter syntax http://msdn.microsoft.com/en-us/library/aa746475(VS.85).aspx

LDAP Troubleshooting Checklist

Page 16 of 16