SharePoint People-Picker and Active Directory Part 1

[UPDATED on 12/04/2012]

Introduction

In organizations operating SharePoint with multiple Active Directory forests/domains, configuring the people picker can be a challenge, particularely if trust relationships between the domain hosting SharePoint and the domain(s) hosting the users are "one-way".

I must confess that only documentation is poor and blog posts were sometimes unclear to me. Therefore I decided to make a digest but comprehensive attempt to document the people picker behavior and configuration in and AD/Integrated Windows Authentication (IWA) configurations/Classic Mode. Note: what applies to IWA also applies to Basic, Digest and client certificate mapping authentication as long as AD is used as repository for authentication information. It is critical to correctly understand how AD, domains, forests and trusts are working in order to get your people-picker working correctly (displays what you effectively want to see), rapidly (does not take ages to return a result) and reliably (its behavior is predictable and persistent over time).

Default Behavior

The people-picker is a SharePoint interface responsible for querying repositories for users or groups in order to grant them permission in the SharePoint application. It is implemented as part of the WFE role, this means that when you’re using it, the WFE you’re connected to will attempt to contact AD in order to returns items matching your query’s criteria. Here is, step by step, how it works:

1. A user submits a query to the people-picker
2. The SharePoint contacts a domain controller of the domains it belongs to in order to retrieve the list of trusted forests/domains with which a 2-way trust is established. Note: to do so, the system function DsEnumerateDomainTrusts is called.
3. For each Forest/Domain retrieved as previous steps, The SharePoint (WFE) will perform the steps 4 to 6 hereunder
4. The SharePoint performs a DNS query in order to locate a domain controller hosting the Global Catalog Service (in case of a Forest) or LDAP service (in case of a Domain). There are actually two possible DNS queries: The first query will include the server’s Active Directory site name, in order to locate a domain controller that reside on the same site or “covers” it (does not reside in the same site but is configured as a candidate to receive request from originating from that site).If that first query succeeds, there’ll be no secondone. It it fails and the DNS reports that there is no such name, a second query will take place without any reference to the server’s site.Note that, like with any DNS record resolution attempt in Windows, the result is cached according to the TTL of the record or put in the negative cache if the query failed
5. With the IP address of a DC hosting GC or LDAP service in hand, SharePoint (WFE) will initiate a connection over port 3368 (Global Catalog LDAP over TCP for a forest) or 389 (LDAP over TCP for a Domain) against the selected domain controller. This first request, which is is anonymous, is necessary for the LDAP client and server to agree on a set of elements necessary for the protocol to work such as authentication, capabilities.This first contact is often known as the Root or RootDSE
6. Once SharePoint know how to talk to an AD, it will perform a query whose part of the parameters are based on the user's input. This query is powered by the System.DirectoryService Namespace. If the AD requires authentication, which is by default the case, SharePoint will authenticate using the context of the IIS application pool the SharePoint web application runs under. It can be Local system or Network Service (DOMAIN\SERVERNAME$ is used) or a domain user used as service account
7. SharePoint aggregates the results with user information which could already exist in the site the user originally accessed and initiated the people-picker from
8. SharePoint displays the results to the user

The query, as stored in the code:

• (&(objectCategory=person)(objectClass=user)(!(userAccountControl:1.2.840.113556.1.4.803:=2))(|(name={0}*)(displayName={0}*)(cn={0}*)(mail={0}*)(sn={0}*)(SamAccountName={1}*)(proxyAddresses=SMTP:{0})(proxyAddresses=sip:{0}){2}))", "(&(objectCategory=person)(objectClass=user)(!(userAccountControl:1.2.840.113556.1.4.803:=2))(|(name={0})(displayName={0})(cn={0})(mail={0})(samAccountName={0})(proxyAddresses=SMTP:{0})(proxyAddresses=sip:{0})))", "(&(objectCategory=person)(objectClass=user)(!(userAccountControl:1.2.840.113556.1.4.803:=2))(|(mail={0})(proxyAddresses=SMTP:{0})))"), new SearchParameter("(&(objectCategory=group)(|(name={0}*)(displayname={0}*)(cn={0}*)(SamAccountName={1}*)(mail={0}*)(proxyAddresses=SMTP:{0}){2}))", "(&(objectCategory=group)(|(name={0})(displayname={0})(SamAccountName={0})(mail={0})(proxyAddresses=SMTP:{0})))", "(&(objectCategory=group)(|(mail={0})(cn={0})(proxyAddresses=SMTP:{0})))"), new SearchParameter("(&(objectCategory=group)(groupType:1.2.840.113556.1.4.803:=2147483648)(|(name={0}*)(displayname={0}*)(cn={0}*)(SamAccountName={1}*){2}))", "(&(objectCategory=group)(groupType:1.2.840.113556.1.4.803:=2147483648)(|(name={0})(displayName={0})(cn={0})(samAccountName={0})))

The query criteria in clear:

• A user or a group
• If it is user, at least of of the following attribute must begin with the input the user provided: name, displayName, cn, mail, sn, SamAccountName, proxyAddresses (with SMTP or sip)
• It it is a user it must not be disabled
• If it is a group, at least of of the following attribute must begin with the input the user provided: name, displayname, cn, SamAccountName
• if it is a group, it must be a security group (domain local, global or universal), not a distribution group

The following attributes are requested for each record found:

• objectSID
• mail
• displayName
• title
• department
• proxyAddresses
• cn
• samAccountName
• groupType
• userAccountControl
• distinguishedName

Key points:

• By default, SharePoint only knows about the AD domain its server(s) belong(s) to and the other forest or domains trusted by that domain
• SharePoint uses DC locator DNS records to locate a DC, attempting to honor Active Directory's site awareness principle
• SharePoint queries AD using the Global Catalog or LDAP Service
• The same LDAP filter is used for every domain

Prerequisites for the people picker to work:

• The SharePoint Server(s) must be able to resolve DNS names from the remote forests/domains
• The network connectivity must be allowed from the SharePoint Server(s) and the Domain Controller of the remote forest/domain
• A two-way trust relationship must be in-place. For one-way, see the section below

Custom Configuration for Querying Specific Forest/Domains

In some situation, you may want to restrict the forests/domain queried by the people. In this case, the list of forests/domains must be configured on a per web application-basis using the command STSADM.exe -o setproperty -pn peoplepicker –searchadforests. For each forest/domain, you need to gather the information below:

• Do you query a forest or a domain
• The DNS name of the forest or domain to be queried

Then, based on the information above, you can assemble the parameter correctly. The configuration of each forest or domain to be queried must be separated with a semi-colon and inside the configuration, the first word must be forest: or domain: and it must be followed by a valid DNS name. Example:

• STSADM.exe -o setproperty -pn peoplepicker–searchadforests –pv “forest:dune.local;domain:carthag.local;domain:tuono.local”

Key points:

• Using a custom configuration completely replaces the default behavior
• SharePoint will not retrieve the list of forest/domain with which a 2-way trust is in place anymoire like it does at step 2 of Default Behavior
• If you specify a forest, a forest trust must be in place, if you specify a domain, an external trust will be sufficient
• If you still wish to query the forest/domain SharePoint belongs to, you’ll have to add it as part of the parameter too
• If you configure a forest to be queried, it is not necessary to declare all or some child domains separately, they will be queried as well
• If “forest” is specified, the Global Catalog Service will be used to perform the query while with domain, it will use the LDAP service
• While the STSADM command is to be execute on one SharePoint server, an ISRESET must be performed on each SharePoint server for the configuration must be applied

Custom Configuration with One-Way trust Scenario

This configuration is identical to the above except that since the IIS application pool identity is unable to authenticate against the remote forest/domain due to the limitation imposed by one-way trust, alternate credentials must be supplied. Those credentials must be from the forest/domain to be queried or from a trusted domain, as long as it is allowed to authenticate.

The tough part of the job in this case is to apply the configuration.

First, a key must be generated in order to encrypt/decrypt the alternate credentials that will be used, in order to do so, you have to run the command hereunder on every SharePoint server:

• STSADM.exe -o setapppassword -password MYPASSWORD. where MYPASSWORD is the key –> While it makes sense that the more complex, the better, it seems that too complex will prevent the people picker from working. Note: the complexity is not ruled by the Windows password policy

Secondly, you have to provide the list of forest/domains to be queried as well as the credentials to do so. Each block is separated by semi-colons and each element in a block is separated by comma. Example:

• STSADM.exe -o setproperty -pn peoplepicker–searchadforests –pv “forest:dune.local,DUNE\PAULA,PasswordOfPaulA;domain:carthag.local,CARTHAG\Gurney,PasswordOfGurney;domain:tuono.local,TUONO\SHANIA,PasswordOfShania”

Key points:

• Do not forget to execute STSADM.exe -o setapppassword on each SharePoint server
• Make sure you have valid credentials for each forest/domain
• Make sure each forest/domain element is correctly structured
• Sure you can combined forest/domain with and without explicit credentials. If ceredentials are not supplied, the context of the IIS application pool account running the web application will be used

Worth Mentionning

The people picker configuration is not only used by the web interface of sites but also by some STSADM commands, Powerhsell Cmdlets and API's. Therefore, user or group-related interactions may faild if the configuration is incorrect or if the people picker is not operating correctly.

Moreover, if you wish to assign permission to users in the central admin (site collection owner, policy for web application...), it will also require people picker configuration, unless the default behavior is sufficient.

Some Troubleshooting Guidance

Useful tools

• NTLTEST command-line: (part of the windows Server 2008 Support tools or built-in Windows Server 2008)
• Wireshark network capture utility
• LDP.exe simple LDAP client (part of the windows Server 2008 Support tools or built-in Windows Server 2008)
• Active Directory User and computer (ADUC) Console
• ADInsight from MS Sysinsternals (not super reliable alas)

Global Approach

The most straightforward way to trace the behavior of the people picker is to take a network capture while performing the search from the Web GUI, taking care of flushing the DNS resolver cache (ipconfig /flushdns). Take this capture of the WFE your target with your tests and filter the results as follows:

Apply a display filter to show only DNS requests, you should see requests like the following:

If you attempt to query a domain: _ldap._tcp.Site-Name._sites.domain.local: type SRV, class IN (first attempts, in order to locate a DC in the same site) or _ldap._tcp.domain.local: type SRV, class IN (any DC in that domain, regardless of the site)

If you specified to query a forest, you should see _gc instead of _ldap

If you don’t see those DNS request or if you see them but they fail, make sure the SharePoint servers are able to resolve names from remote domains ad are configured with the correct DNS Servers and optionally with a list of suffixes

Once name resolution is working fine, go back to the capture and make sure you see LDAP (port 389) or GC (same as LDAP but on port 3268).

for each domain or forest, you should see a “bindRequest” with a successful response followed by a “seachRequest” followed by a successful response as well. drill-down into the search request for the details about the query submitted: the filter and conditions applied in particular

Retrieving the server’s AD site

Execute the command “NLTEST /dsgetsite”. It should return the AD site the SharePoint server belongs to. If it does not, there is a serious AD configuration problem ;)

Retrieving a DC for a given domain

Execute the command “NLTEST /dsgetdc:mydomain.local

If the list of flags it return includes the following, you’re ok:

• CLOSE_SITE= the DC is in the same AD site as the SharePoint server or is “covering” that site
• LDAP: the DC is LDAP server (all DCs are but must advertise it)
• GC: the DC is also global catalog (NOT all DCs are but if they are, they must advertise it too)

Note: Other information returned by the command might also be useful for troubleshooting: Name and IP address of the DC…

Simple LDAP connection test

1. On the SharePoint server, start ldp.exe

2. Go to the menu “Connection” and click “Connect”. Enter the IP or the host name of the remote DC. You should test with a FQ host name in order to test DNS too. Select port 389 for LDAP or 3268 for GC. If it works, it will return a list of server-related information

3. Repeat this test for each DC SharePoint would potentially target

Testing the credentials to connect to a remote domain using LDAP (one-way trust scenario)

If the test above works, proceed to this one:

1. Return to the menu “connection” then click “Bind” then enter the credential of the remote domain to be browsed (including the domain name in the 3^rd textbox

2. If it fails, you’ll see a message such as

res = ldap_bind_s(ld, NULL, &NtAuthIdentity, 1158); // v.3

               {NtAuthIdentity: User=’myuser’; Pwd= <unavailable>; domain = ‘mydomain’.}

Error <49>: ldap_bind_s() failed: Invalid Credentials.

3. If it succeeds, it will report

res = ldap_bind_s(ld, NULL, &NtAuthIdentity, 1158); // v.3

               {NtAuthIdentity: User=’myuser’; Pwd= <unavailable>; domain = ‘mydomain’.}

Authenticated as dn:’myuser’.

People-Picker Reliability/Performance Killers

• The more forest/domains there are two query, the slower it will be to get results
• Problematic Name Resolution Process: In order to resolve DC locator records, Windows will exhaust all possible name resolution methods, from DNS to broadcast… And this for each declared forest/domain
• Unresponsive DC brings major slow down
• Suboptimal/Inconsistence AD Site configuration: Site-awareness is a key factor, this makes sure SharePoint always query the nearest DC
• Network devices/Security devices breaking the TCP traffic: from broken NIC to firewall, anything generating TCP retransmit or “forcibly closing” connections
• Load on Active Directory/Domain controller or security settings on the domain controller (preventing DoS attacks for example)
• If custom filter is used: Improperly written filter: make sure the complexity of criteria remains reasonable, only indexed attributed are queried and of course if the GC is used, only attributed that are part of the partial attribute set

Additional information’s

• MS TechNet LDAP Query Basics
• MS TechNet Select users from multiple forest domains
• MS TechNet Peoplepicker-searchadforests: Stsadm property (Office SharePoint Server)
• MS TechNet Active Directory Trust Types
• MS KB How to query Active Directory by using a bitwise filter
• Joel Oleson Multi Forest/Cross Forest People Picker peoplepicker-searchadcustomquery
• Bill Baer Configuring SharePoint Products and Technologies for Cross-Forest Deployments

What’s next?

In the next posts, I will cover:

• Additional filtering capabilities of LDAP searches
• Detailed configuration for each scenario
• how people picker is related to authentication and profile import (MOSS only)
• Guidance to optimize people-picker in different scenario’s

Happy people-picking!

Marc