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 logLdap-migration.log

How it flows:

If is ldap user

2. Configuration

2.1 Configuration file : Sample configuration file

LDAP Troubleshooting Checklist Page 1 of 16

LDAP engine makes connection to the db to check whether this is a db user or LDAP user

PLM client enters login ID

Starts an ldap session by connecting to LDAP server over port 389 or 663, based on the ldap configuration

Uses ldap user and password to authenticate and logs into LDAP server

Use the search filter to find the user in LDAP server

Authentication succeeds and logs into Agile

2.2 Step by step configuration verification

Filed Name

What is it? How to Verify?

ID Unique string identifying the LDAP server. The string must be lessthan 30 characters and cannot be changed once in use.

Ex: agile001, agile002

LDAP Troubleshooting Checklist Page 2 of 16

Description

Information about the server configuration

any

Agent The Directory Server used for authentication; valid values areSunONEDirectory or ActiveDirectory

--SunONEDirectory or-- ActiveDirectory

URL The URL for the authentication agent ex: ldap://SLDC01.sl.agilesoft.com:389-- double check with Ad admin to get correct Server URL

Domain

The authentication string when using Active Directory Server in theformat of xyz.com

Domain based on the above server URL. --ex: sl.agilesoft.com

Username

Username (does not need to be the LDAP Administrator)

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

User path

Tree under which all Agile users can be found; this property shouldbe 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 nodeshould not be on the Agile system.

--Ask the customer to send you a tree structure to verify the path.--common tools we use:1. direct connection to the AD server2. 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; validvalues are ONE_LEVEL or SUB_TREE; this property should be setto ONE_LEVEL only if all users in the organization are directly underthe User Path node

ONE_LEVEL or SUB_TREE

Search filter

Search filter for Agile users under the <user-path> node; this mustbe a valid LDAP search filter that matches all Agile users under thescope defined by <auth.ldap.user.path> and<auth.ldap.user.search.scope>; users not matching this filter areconsidered invalid users on the Agile system; a valid LDAP searchfilter must be enclosed in parentheses.

Ex:(objectclass=person)All users(objectclass=group)All groups

(cn= LDAP User1)Only this user

LDAP Troubleshooting Checklist Page 3 of 16

(OU=Support)Only Support group

Mechanism

Authentication mechanism supported by the directory server; validvalues are "simple" or "strong"

simple

2.3 What’s 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 groupsThere 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 ona user group's Users tab that have been synchronized (that is, where usershave 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 ofusers not able to login:

yes

no

no

yes

few user

all users

still not work

still failsfix

LDAP Troubleshooting Checklist Page 14 of 16

Is this a new implementation?

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

Does preview work?

Find out what’s changed?

1. Double check user path/filter and group path/filter. Reference:Note 569003.12. Check log files for detail errors

Is this login problem for all users or few user?

1. Make sure users are active in LDAP;2. make sure users are under correct user path and group path on AD server

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

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

Time to contact Support

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 logonSee note: Note 569003.1

--9.2.2.4 HF6 --Not able to sync users after initial implementation

--Configuration for BEA weblogicFirst 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 Why use it?

Checkldapconfig.cmd To check the connection and LDAP config

Migrateuserstodb.cmd To bring users over from LDAP

Migrateuserstodb –r To clear all LDAP user values in the db

Migrateuserstodb –R To clear all DB user values in the db

Other References:--Agile PLM Administrator Guide

LDAP Troubleshooting Checklist Page 15 of 16

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

LDAP Troubleshooting Checklist Page 16 of 16