Sdílet prostřednictvím

Custom claims providers for People Picker (SharePoint Foundation 2010)

  • Článek

 

Applies to: SharePoint Foundation 2010

A claim consists of information about the identity of a user, such as a name, e-mail address, or group membership. A claims provider in Microsoft SharePoint Foundation 2010 issues claims, which SharePoint Foundation 2010 then packages into security tokens for users. When a user signs in to SharePoint Foundation 2010, the user's token is validated and then used to sign in to SharePoint Foundation 2010. Claims providers are displayed in the user interface of the Select People and Groups dialog box in the People Picker control. They provide the functionality used to find and select users, groups, and claims when permissions are assigned to items such as lists, libraries, and sites in SharePoint Foundation 2010. For information about the People Picker control, see People Picker overview (SharePoint Foundation 2010).

This article describes the use and benefits of claims providers, their architecture, special considerations for custom claims providers, and how to plan for them. It does not explain how to create or configure custom claims providers. For information about how to create a custom claims provider, see Claims How Tos (https://go.microsoft.com/fwlink/p/?LinkId=207578) and Creating Custom Claims Providers in SharePoint 2010 (https://go.microsoft.com/fwlink/p/?LinkId=211324).

Before reading this article, you should understand the concepts described in Plan authentication methods (SharePoint Foundation 2010) and 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) and A Guide to Claims-based Identity and Access Control (https://go.microsoft.com/fwlink/p/?LinkID=187911).

In this article:

  • Uses and benefits

  • Architecture

  • About custom claims providers

  • Deploying and configuring custom claims providers

  • Using custom claims on more than one farm

  • Considerations for custom claims providers

Uses and benefits

A claims provider in SharePoint Foundation 2010 is used primarily for two reasons:

  • To augment claims

  • To provide name resolution

In the augmentation role, a claims provider augments a user token with additional claims during sign-in. For more information about claims augmentation, see Claims Provider (https://go.microsoft.com/fwlink/p/?LinkID=207579).

In the picking role, a claims provider lists, resolves, searches, and determines the "friendly" display of users, groups, and claims in the People Picker. Claims picking enables an application to surface claims in the People Picker, for example when configuring the security of a SharePoint site or SharePoint service. For more information about People Picker, see People Picker overview (SharePoint Foundation 2010).

You can use the claims providers that are included with SharePoint Foundation 2010, or you can create your own custom claims providers to provide additional claims in the security token for a user or to connect to additional sources of claims. For example, if you have a CRM application that contains roles that are not found in the user repository in Active Directory, you can create a custom claims provider to connect to that database and add CRM role data to a user's original claims token. For more information about claims provider usage scenarios, see Claims Provider (https://go.microsoft.com/fwlink/p/?LinkID=207579).

Architecture

When a Web application is configured to use claims-based authentication, SharePoint Foundation 2010 automatically uses two default claims providers:

Depending on the authentication method selected for a zone of a Web application, SharePoint Foundation 2010 also uses one or more of the default claims providers listed in the following table.

Authentication method Claims provider

Windows authentication

SPActiveDirectoryClaimProvider (https://go.microsoft.com/fwlink/p/?LinkID=208325)

Forms-based authentication

SPFormsClaimProvider (https://go.microsoft.com/fwlink/p/?LinkId=210013)

Security Assertion Markup Language (SAML) token-based authentication

SPTrustedClaimProvider (https://go.microsoft.com/fwlink/p/?LinkId=210014)

These claims providers are displayed in the Select People and Groups dialog box for People Picker. You can see a list of claims providers for a farm by using the Get-SPClaimProvider Windows PowerShell cmdlet.

Note

When a Web application is configured to use SAML token-based authentication, the SPTrustedClaimProvider class does not provide search functionality to the People Picker control. Any text entered in the People Picker control will automatically be displayed as if it had been resolved, regardless of whether it is a valid user, group, or claim. If your SharePoint Foundation 2010 solution will use SAML token-based authentication, you should plan to create a custom claims provider to implement custom search and name resolution.

Claims providers are registered on a server farm as features that are deployed to the farm. They are scoped at the farm level. Each claims provider object uses the SPClaimProviderDefinition class to include information about the claims provider, such as display name, description, assembly, and type. Two important properties of the SPClaimProviderDefinition class are IsEnabled and IsUsedByDefault. These properties determine whether a registered claims provider is enabled for use in the farm, and whether the claims provider is used by default in a particular zone. By default, all claims providers are enabled when they are deployed to a server farm. For information about the SPClaimProviderDefinition class, see SPClaimProviderDefinition Class (https://go.microsoft.com/fwlink/p/?LinkId=207595).

For more information about zones and authentication, see Plan authentication methods (SharePoint Foundation 2010).

For information about how to write a custom claims provider, see Creating Custom Claims Providers in SharePoint 2010 (https://go.microsoft.com/fwlink/p/?LinkID=211324) and Claims Walkthrough: Writing Claims Providers for SharePoint 2010 (https://go.microsoft.com/fwlink/p/?LinkId=207589). For information about how to override the default claims provider, see How to Override the Default Name Resolution and Claims Provider for SharePoint 2010 (https://go.microsoft.com/fwlink/p/?LinkId=207591).

About custom claims providers

By default, the information that is resolved in People Picker when a query is performed depends on the information supplied by the claims provider. You cannot change what information is supplied and how it is displayed when you use an out-of-box claims provider. To do this, you must have a developer create a custom claims provider that will meet the needs of your solution for finding and selecting users, groups, and claims when a user assigns permissions to items such as a site, list, or library.

For example, if your Web application uses SAML authentication and you also want to resolve users from Active Directory, you will need to create a custom claims provider. For additional examples of claims provider use scenarios, see Claims Provider (https://go.microsoft.com/fwlink/p/?LinkID=207579).

When you create a custom claims provider, you can control what information is displayed and what results are returned in response to a query from the People Picker control. By default, you configure the Web application to use claims authentication, and then register the claims provider on the server.

Note

You cannot control the order in which claims providers are displayed in the Select People and Groups dialog box in People Picker.

For information about how to write a custom claims provider, see How to: Create a Claims Provider (https://go.microsoft.com/fwlink/p/?LinkId=207588) and Claims Walkthrough: Writing Claims Providers for SharePoint 2010 (https://go.microsoft.com/fwlink/p/?LinkId=207589). For information about how to override the default claims provider, see How to Override the Default Name Resolution and Claims Provider for SharePoint 2010 (https://go.microsoft.com/fwlink/p/?LinkId=207591).

Deploying and configuring custom claims providers

By default, when you register a custom claims provider on the farm, the IsEnabled and IsUsedByDefault properties are both set to True. Unless the IsUsedByDefault property is set to False, the custom claims provider is displayed in the Select People and Groups dialog box in People Picker for all zones. Depending on the number of zones needed for your SharePoint Foundation 2010 solution, the authentication methods used by each zone, and the users for each zone, you may want to limit the zones in which your custom claims provider is displayed in People Picker.

Because claims providers are scoped at the farm level and enabled at the zone level, you must carefully plan the zones in which you want the custom claims provider to be displayed. In general, you should make sure that the IsUsedByDefault property is set to False, and then configure the SPIisSettings class for each zone in which you want to use the custom claims provider. To configure a custom claims provider for select zones, you can create a Windows PowerShell script that sets the claims provider for a zone by using the SPIisSettings.ClaimsProviders property, or you can create a custom application to allow you to enable a custom claims provider for select zones. For information about the SPIisSettings.ClaimsProvider property, see SPIisSettings.ClaimsProvider Property (https://go.microsoft.com/fwlink/p/?LinkId=207597). For information about how to create a custom application to configure claims providers for select zones, see the TechNet blog post, Configuring a Custom Claims Provider to be Used only on Select Zones in SharePoint 2010 (https://go.microsoft.com/fwlink/p/?LinkId=207592).

For example, consider a scenario where there are two Web applications: The first Web application, PartnerWeb, has two zones — one intranet that uses Windows claims-based authentication and one extranet that uses forms-based authentication — and is used for collaboration among employees and partners. The second Web application, PublishingWeb, has only one zone that uses forms-based authentication and is an Internet publishing site for employees, business partners, and customer partners. Now, suppose that for the extranet zone on PartnerWeb, you want employees to be able to collaborate with business partners but not customer partners. To do this, you write a custom claims provider that determines whether the current user is a business partner or customer partner, based on the user's identity. In this example, users from fabrikam.com are business partners, while users from contoso.com are customer partners. When a user who is a business partner is authenticated in the PartnerWeb Web application, a claim for a role called BusinessPartner is added to the claim token; when a customer partner is authenticated, a claim for a role called CustomerPartner is added to the claim token. To make sure that customer partners are never added to the extranet collaboration site, you add a Web application policy on the PartnerWeb Web application for the extranet zone that explicitly denies access to any user who has a claim for a role called CustomerPartner. The custom claims provider would also need to implement search and type-in support for the Web application policy to resolve the CustomerPartner role claim so it can be added to the Web application policy. Finally, to enable this functionality on the extranet zone, you configure the SPIisSettings class for that zone to use the custom claims provider. The following diagram illustrates the authentication methods and claims provider settings for each Web application and zone.

SPIisSettings diagram

Note

On the Central Administration Web site, all claims providers are displayed in the Select People and Groups dialog box in People Picker, regardless of whether the IsUsedByDefault property is set to True.

You can set the IsUsedByDefault property by configuring it in a feature receiver that you create for your custom claims provider. For information about how to use a feature receiver to deploy a custom claims provider, see Sample: Feature Receiver to Deploy a Claims Provider (https://go.microsoft.com/fwlink/p/?LinkId=207590).

You can also override the settings of the IsEnabled and IsUsedByDefault properties by using the Set-SPClaimProvider Windows PowerShell cmdlet.

Important

Changing the IsEnabled property to False will disable the claims provider for the entire server farm. This can be useful if you need to troubleshoot issues that might be caused by a custom claims provider. However, in general, the IsEnabled property should be set to True.

Using custom claims on more than one farm

Claim values are a combination of the claim itself, the claims provider name, and the order in which the claims provider was installed on the server. Therefore, if you want to use a claim across multiple farms or environments, you must install the claims providers in the same order on each farm in which you want to use the claim. Use the following steps when you have installed a custom claims provider on a farm and you want to use the same claim on additional farms.

  1. Register the claims providers on the additional farms in the same order that they were registered on the first farm.

  2. Perform a backup of the first farm. For information about how to back up a farm, see Back up a farm (SharePoint Foundation 2010).

  3. Use the back up from the first farm to restore the other farms. For information about how to restore a farm, see Restore a farm (SharePoint Foundation 2010).

Considerations for custom claims providers

As you plan custom claims providers for use with People Picker in your SharePoint solution, consider the following questions:

  • What zones does your Web application have, and what authentication methods are used in each zone?

  • Are there any custom claims that should be added to users to enable more advanced security scenarios?

  • Will you be using SAML authentication with a trusted identity provider?

  • What will be the source of the values for the users and roles that will be displayed in People Picker query results?

  • What claim data do you want to resolve in the Select People and Groups dialog box?

The SharePoint Foundation 2010 Content Publishing team would like to thank Steve Peschka for contributing to this article. His blog can be found here (https://go.microsoft.com/fwlink/p/?LinkId=210274).

See Also

Concepts

Plan authentication methods (SharePoint Foundation 2010)