People Picker overview (SharePoint Foundation 2010)

 

Applies to: SharePoint Foundation 2010

The People Picker control is used to find and select people, groups, and claims when a site, list, or library owner assigns permissions in Microsoft SharePoint Foundation 2010. This article describes the People Picker control and how it works, its relationship to authentication and claims providers, and how to plan for People Picker. For information about how to configure People Picker, see Configure People Picker (SharePoint Foundation 2010).

Before reading this article, you should understand the concepts described in Plan authentication methods (SharePoint Foundation 2010)and in The Role of Claims (https://go.microsoft.com/fwlink/p/?LinkID=208326). For additional information about claims-based authentication, see SharePoint Claims-Based Identity (https://go.microsoft.com/fwlink/p/?LinkID=196647).

In this article:

  • Uses and benefits

  • Architecture

  • About the People Picker control

  • People Picker and authentication

  • People Picker and claims providers

  • Configuring People Picker

  • Using People Picker with multiple forests or domains

  • Considerations for People Picker

Uses and benefits

The People Picker control is used to select users, groups, and claims to grant permission to items such as lists, libraries, and sites. For example, your site has a document library that you want to restrict to a certain list of users. When you use the library permissions page to give users permission levels for the library, you use the People Picker control either to type user names and verify that the user accounts are valid, or to search for a name or partial string and return a list of users, groups, or claims that match the value you entered. For more information about permissions, see Plan site permissions (SharePoint Foundation 2010).

Architecture

The People Picker control is a central component of SharePoint Foundation 2010. The control provides basic functionality for finding and selecting users, groups, and claims to assign permissions in a site. The exact sources of those users, groups, and claims depend on the authentication method used by the Web application that contains the site collection. For more information about authentication methods, see People Picker and authentication later in this article.

People Picker is configured at the zone level for a farm by using the Stsadm setproperty operation. By configuring the settings for the control, you can filter and restrict the results that are displayed when a user searches for a user, group, or claim. Those settings will apply to every site within a specific site collection. For more information about configuring People Picker, see Configure People Picker (SharePoint Foundation 2010).

Note

There are no Windows PowerShell commands to configure People Picker.

When a Web application is configured to use claims-based authentication, People Picker uses claims providers to resolve and display users, groups, and claims in the Select People and Groups dialog box. The information that is displayed in the Select People and Groups dialog box depends on the claims provider used by the authentication method that was configured for the Web application. For more information about claims providers, see Custom claims providers for People Picker (SharePoint Foundation 2010).

About the People Picker control

The People Picker control consists of a text box and two buttons: the Check Names button and the Browse button. The following illustration shows an example of the People Picker control.

People Picker editor

The user types a user name, group name, or claim (such as an e-mail address) into the text box, and then clicks the Check Names button to resolve the search item exactly as it was entered. If People Picker is able to resolve the search item, the name is replaced with a resolved identity. If the search item cannot be resolved exactly as entered, People Picker performs a search. If no match is found, or if more than one match is found, a red underline is displayed under the search item and the following error message appears: No exact match found. Click the item(s) that did not resolve for more options. When the item is clicked, a pop-up menu displays a list of available users, groups, or claims that match the query, if applicable. The menu also contains a Remove button to remove the resolved user, group, or claim from the text box, and a More Names button, which opens the Select People and Groups dialog box.

If the user clicks the Browse button, the Select People and Groups dialog box is displayed. The user types a full or partial user name, group name, or claim into the text box, and then presses Enter. The results of the query are displayed in the dialog box. The claims providers that People Picker interacts with determine the query results and the way those results are displayed in the dialog box. The user selects a resolved identity, clicks Add, and then clicks OK. The selected user, group, or claim is then added to the text box in the People Picker control.

When a Web application is configured to use Windows authentication, you can limit the results that are displayed to users in the Select People and Groups dialog box by using the Stsadm setproperty operation to change the settings for the People Picker control. For example, you can configure People Picker to return only users, groups, and claims that belong to a certain Active Directory domain or are members of a specific site collection. For more information about configuring the People Picker control, see Configure People Picker (SharePoint Foundation 2010).

People Picker and authentication

People Picker relies on the authentication method used by the Web application that contains the site collection from which it is queried to determine what results to display to a user. If the Web application is configured to use Windows authentication in classic mode, SharePoint Foundation 2010 treats user accounts as Active Directory Domain Services (AD DS) accounts. If the Web application is configured to use claims-based authentication, you can specify whether to use Windows authentication, forms-based authentication (FBA), or Security Assertion Markup Language (SAML) token-based authentication. In claims mode, People Picker searches and resolves queries based on the claims provider that is specified for the authentication method used by the Web application and zone. The following sections describe People Picker behavior for both classic-mode authentication and claims-based authentication. For more information about zones and authentication, see Plan authentication methods (SharePoint Foundation 2010).

Classic-mode authentication

When Windows classic-mode authentication is used, the People Picker control queries Active Directory to retrieve a list of users, groups, or claims that match the search item typed in the text box. You can configure People Picker to query Active Directory by using Lightweight Directory Access Protocol (LDAP) queries, which enables you to apply custom Active Directory filters, limit the scope of search queries, and search across forests and domains.

By default, when the Browse button is clicked, the Select People and Groups dialog box displays the following fields:

  • Display Name

  • Title

  • Department

  • E-mail

  • Mobile Number

  • Account Name

The following image shows the Select People and Groups dialog box when Windows authentication is used in classic mode for the Web application.

Select People and Groups - Classic Mode

For more information about classic-mode authentication, see Plan authentication methods (SharePoint Foundation 2010). For information about how to create a Web application that uses classic-mode authentication, see Create a Web application that uses Windows-classic authentication (SharePoint Foundation 2010).

Claims-based authentication

When claims-based authentication is used, People Picker uses the claims provider that is specified for the authentication method used by the Web application and zone to retrieve a list of users, groups, or claims that match the search item typed in the text box. For more information about claims mode authentication and zones, see Plan authentication methods (SharePoint Foundation 2010).

By default, when the Browse button is clicked, the Select People and Groups dialog box displays a tree view on the left that lists the claims providers that People Picker will query. The right side of the dialog box is where query results are displayed. When claims-based authentication is used, the results are displayed in one of two views: Detailed View or List View. By default, Detailed View is displayed.

The following illustration shows the Select People and Groups dialog box when Windows authentication is used in claims mode for a Web application.

Select People and Groups - Win Claims Mode

In Detailed View, the query results are grouped by the sources where the query results were found. For example, if a search item is found in a SharePoint group and in Active Directory, the results are organized into a list of SharePoint groups followed by a list of Active Directory users and groups.

In List View, the query results are returned in a list that contains the following fields:

  • Display Name

  • E-mail Address

  • Title

  • Department

  • Presence

  • Work Phone

  • Location

You can write a custom claims provider to control what information is displayed and what results are returned in response to a query from the People Picker control. When a custom claims provider is registered on the server, you can also configure it for use in a specific Web application and zone. This means that a custom claims provider that is configured for only one zone will only be displayed in the Select People and Groups dialog box for Web sites in that zone. For more information about custom claims providers, see Custom claims providers for People Picker (SharePoint Foundation 2010).

Note

In the Central Administration Web site, People Picker will return users, groups, and claims from all claims providers used in all Web applications in the farm, regardless of the Web application or zone in which the claims providers are configured.

By default, when you use SAML token-based authentication, all queries entered in the text box are automatically displayed as if they had been resolved, regardless of whether they are valid users or groups. If your SharePoint Foundation 2010 solution will use SAML token-based authentication, you should plan to create a custom claims provider that will implement custom search, name resolution, and list features. For more information about custom claims providers, see Custom claims providers for People Picker (SharePoint Foundation 2010).

For information about how to create a Web application that uses claims-mode authentication, see Create a Web application that uses Windows-claims authentication (SharePoint Foundation 2010). For information about configuring claims-based authentication for Web applications, see Configure claims authentication (SharePoint Foundation 2010).

People Picker and claims providers

A claims provider lists, resolves, searches, and determines the "friendly" display of users, groups, and claims in the People Picker when claims-based authentication is used. If your Web application uses claims-based authentication, you must decide whether to use one of the default claims providers or create a custom claims provider that will meet the business needs of your organization.

For more information about how claims providers are related to the People Picker control, see Custom claims providers for People Picker (SharePoint Foundation 2010).

Configuring People Picker

The information in this section applies only to Web applications that use Windows authentication in either classic mode or claims mode.

You can configure People Picker to filter query results and to restrict the directories that People Picker uses as a source of those results by using property names for the Stsadm setproperty operation. To see what property settings have been configured, use the Stsadm getproperty operation. For more information, see Peoplepicker: Stsadm properties (Office SharePoint Server 2007). The settings for People Picker are applied to each URL zone for a Web application.

Note

There are no Windows PowerShell commands to configure People Picker.

The following table describes the properties that can be used to configure People Picker.

Property name Description

Peoplepicker-activedirectorysearchtimeout

Configures the timeout when a query is issued to Active Directory. The default timeout value is 30 seconds. For more information, see Peoplepicker-activedirectorysearchtimeout.

Peoplepicker-distributionlistsearchdomains

Restricts the search of a distribution list to a specific subset of domains. For more information, see Peoplepicker-distributionlistsearchdomains.

Peoplepicker-nowindowsaccountsfornonwindowsauthenticationmode

Specifies not to search Active Directory when the current port is using forms-based authentication. For more information, see Peoplepicker-nowindowsaccountsfornonwindowsauthenticationmode.

Peoplepicker-onlysearchwithinsitecollection

Displays only users who are members of the site collection when the Select People and Groups dialog box is used. For more information, see Peoplepicker-onlysearchwithinsitecollection.

Peoplepicker-peopleeditoronlyresolvewithinsitecollection

Displays only users who are members of the current site collection when the Check Names button is clicked. For more information, see. Peoplepicker-peopleeditoronlyresolvewithinsitecollection: Stsadm property (SharePoint Foundation 2010).

Peoplepicker-searchadcustomfilter

Enables a farm administrator to specify a unique search query. For more information, see Peoplepicker-searchadcustomfilter.

Peoplepicker-searchadcustomquery

Permits the administrator to set the custom query that is sent to Active Directory. For more information, see Peoplepicker-searchadcustomquery.

Peoplepicker-searchadforests

Permits a user to search from a second one-way trusted forest or domain. For more information, see Peoplepicker-searchadforests.

Peoplepicker-serviceaccountdirectorypaths

Enables a farm administrator to manage the site collection that has a specific organizational unit (OU) setting as defined in the Setsiteuseraccountdirectorypath setting. For more information, see Peoplepicker-serviceaccountdirectorypaths.

For more information about configuring People Picker, see Configure People Picker (SharePoint Foundation 2010).

Using People Picker with multiple forests or domains

By default, People Picker will only return users, groups, and claims from the domain on which SharePoint Foundation 2010 is installed. If you want People Picker to return query results from more than one forest or domain, you must either have a two-way trust between the forests or domains, or you must configure People Picker to use an encrypted account and password for a one-way trust between forests and domains. For more information about trusts, see Managing Trusts (https://go.microsoft.com/fwlink/p/?LinkId=207573).

To configure People Picker for a one-way trust, you must first use the Stsadm setapppassword operation to set the password for use on the trusted forest or domain, and then use the Peoplepicker-searchadforests property for the setproperty operation to specify the forest or domain to search. Remember that the settings for People Picker are configured per zone for a Web application, so if you have more than one forest or domain in your farm, you must combine the accounts and passwords into a single command for the setproperty operation. For more information, see Peoplepicker-searchadforests: Stsadm property (Office SharePoint Server).

Note

A ne way trust in this article is defined as a SharePoint_Domain that trusts an External_Domain (outgoing trusts) where an External_Domain\User can access Resources (that is, Sharepoint) in the Sharepoint_Domain domain .
An External_Domain trusts Sharepoint_Domain should not be useful since an External_Domain\User will not be able to access a SharePoint resource.

Considerations for People Picker

Planning for People Picker largely depends on what forests and domains you want users to be able to query, and what users, groups, and claims you want to display in query results. As you plan for the forests and domains you want users to query, consider the following questions:

  • Do users need to query across a forest or a domain?

  • What is the DNS name for each forest or domain you want users to query?

  • Will your forest or domain have a one-way or two-way trust with other forests or domains?

  • If you will be using a one-way trust, what credentials will be used to query the other farms or domains

Planning for the users, groups, and claims you want to display in the query results in People Picker will help you determine how to configure People Picker to return and display results from claims providers. As you plan for the users, groups, and claims you want to display in query results, consider the following questions:

  • Are there certain LDAP filters you want to apply to query results?

  • Do you want to restrict the query results to users, groups, or claims in a specific site collection?

  • Do you want to restrict the query results to users, groups, or claims in a certain Active Directory organizational unit (OU)

See Also

Concepts

Plan authentication methods (SharePoint Foundation 2010)
Custom claims providers for People Picker (SharePoint Foundation 2010)
Configure People Picker (SharePoint Foundation 2010)

Other Resources

Resource Center: Security and Authentication for SharePoint Foundation 2010