I’ve had a few conversations recently about the strangeness of LDAP query syntax so I thought a post some useful information and links here. You might not have had the need to know anything about LDAP query syntax as part of working with PeopleSoft though. PeopleSoft’s delivered LDAP integration does a good job of providing some rich functionality (authenticating users, caching profiles, role memberships, etc.) without forcing you to deal with LDAP query syntax.
LDAP Queries generated by PeopleTools
For example, in the PeopleSoft Authentication Map page ( PeopleTools -> Security -> Directory -> Authentication Map ) you can select which attribute in the directory (such as sAMAccountName) should be used for looking up the user trying to log in. Under the covers, the following LDAP query string is generated (if chrisheller is trying to login):
That’s a pretty simple example though. Looking up the group membership in order to do PeopleSoft role assignment for a user shows slightly more complex LDAP queries.
These get generated for you automatically in the delivered PeopleCode. There are some other more complicated examples, but those get the basics across.
LDAP Query Syntax
Instead of having the queries written in a form similar to how you might speak, (attribute1=value1)&(attribute2=value2), the operator (‘&’ for AND, ‘!’ for NOT, ‘|’ for OR) gets pulled to the front and the whole thing wrapped in parentheses. A good reference is Microsoft’s page on MSDN for search filter syntax, which even includes how do things like bitwise comparisons in LDAP queries. Another good article is Unlocking the LDAP Search Filter which has some good explanations to go along with the syntax.
Another good way to get familiar with some of the possibilities for LDAP queries is to look at other examples that have been posted on the internet. JiJiTechnologies has a nice list of some example LDAP search queries. For example, here is a query that returns users that do not have a manager in the directory.
(&(objectCategory=person)(objectClass=user)(!sAMAccountType=805306370)(!manager=*))and here is a query that returns accounts that will expire in a certain amount of time (see below for more on generating datetime values for LDAP queries)
What can I do with a custom LDAP query?
Well, you might want to do some custom LDAP processing yourself from PeopleCode. Maybe you want to audit the manager entry in the LDAP directory with what is stored within your PeopleSoft HCM database. You might generate LDAP queries like the following to check on a one-by-one basis
(or you might dump the employee/manager attributes from the directory in bulk instead).
Maybe you want to the delivered LDAP authentication to only login users that won’t have their account expire in the next day. You could change the delivered PeopleCode in FUNCLIB_LDAP.LDAPAUTH.FieldDefault to include that check as part of the LDAP query used (note that this is a customization; there is not a place for you to add this without customizing).
As part of our Desktop Single Signon for PeopleSoft product, we also provide the ability to use attributes in an LDAP directory as part of the process of mapping a network login to a PeopleSoft account. In the LDAP configuration there are “prepend” and “append” hooks in place to be able to modify the LDAP query that our code generates.
The feature was originally added because of a PeopleSoft customer that only wanted Single Signon to apply to users that were required to login with a Smartcard. If the user’s account wasn’t setup to require a Smartcard to login, then they wanted Single Signon to not establish their PeopleSoft session, and instead leave them at the PeopleSoft login page.
The attribute in Active Directory that contains the needed information is called userAccountControl. Unfortunately, this attribute is actually a bitfield, so we have to apply the bitwise operators that I mentioned above. In the Single Signon configuration they added a prepend value of (&(userAccountControl:1.2.840.1135126.96.36.1993=262144) and the append value of ) (that’s a single parentheses to close off the query).
At runtime, the generated LDAP query would have been (sAMAccountName=chrisheller), but with the prepend and append values added in, the query becomes (&(userAccountControl:1.2.840.1135188.8.131.523=262144)(sAMAccountName=chrisheller)).
In case you haven’t memorized the MSDN documentation link from above yet (it’ll be on the midterm), the “:1.2.840.1135184.108.40.2063” part is the bitwise AND operator, which we are applying to the userAccountControl attribute. The 262144 is the decimal value for the “Smart card required for login” setting (also known as ADS_UF_SMARTCARD_REQUIRED). Here is a good list of the various different bitvalues that can be in the userAccountControl field.
So now when the LDAP query runs as part of the Single Signon user mapping, if the user’s account does not mandate Smartcard login, then the LDAP query will not return a match, which means that the user will not be automatically logged in to PeopleSoft.
Converting date/time values between Active Directory and PeopleCode
I have some PeopleCode written for this, but it’s getting late so I’ll save that for another post. If you’re interested in it, leave a comment. For now, I’ll just leave it as saying that this writeup on Active Directory’s Integer8 attributes by Richard Mueller was extremely helpful in coming with it.
(update : here is a post that provides the PeopleCode for handling all of the datetime conversions between ActiveDirectory format and PeopleCode datetime variables).
Labels: 2008, LDAP, Security