August 8, 2014

What is a SharePoint Custom Claims Provider and Why Do I Need One?

Have you ever encountered a security requirement that just does not seem to be resolved completely by the use of Active Directory Security groups? We have run up against this particularly when we need to have a security situation where a user must be in two AD Groups. In the case of something like a SharePoint site, if two AD Groups are provided access, a user only need to be in in one of the two groups. We generally refer to this as belonging to Group A–OR–Group B. How would you handle a situation when a user must be in Group A–AND–Group B?

Some examples of where we have used this approach was to support International Traffic Arms Regulation (ITAR), a complex HR Benefits Grouping, and even access to Students and class information by using a Custom Claims provider.

The custom claims you create are claims that are not created when the user authenticates using the site’s authentication provider; these are claims that you can create to meet your specific needs and augment the claims which are provided from the site’s authentication provider. These custom claims can be created by using the authenticated user’s id and querying other data sources / applications to create custom claims. These custom claims can then be used within SharePoint to provide additional security.

A custom claims provider is used to augment custom claims and also provides a way for the People Picker control to find and resolve your custom claims.

How To Do It

Suppose you have a SharePoint site using windows authentication, and you need to create SharePoint sites that require security based on an internal business application. In addition, you want your SharePoint site security to automatically reflect security changes made in the internal business application.

You start with a new empty SharePoint project (deployed as a farm solution) and add a new class to the project which implements the SPClaimProvider class.


using Microsoft.SharePoint.Administration.Claims;
namespace SharePointProject1 {
public class MyCustomClaimProvider: SPClaimProvider {
}
}


Augmenting Claims

The logic for creating the custom claims is done by overriding the FillClaimsForEntity method.


protected override void FillClaimsForEntity(Uri context, SPClaim entity, System.Collections.Generic.List claims)

The input <SPClaim entity> is the user’s identity claim created when authenticating to the configured authentication provider. This claim contains the login id, which can then be used to query other sources of data.

Using the data retrieved from the other data source(s), a new claim (or claims) based on business logic are created and added to the input <System.Collections.Generic.List<SPClaim> claims> collection.

For example, if the internal business system contained information on which customers a user is assigned to, a claim for each customer would be added to the claims collection, setting the claim value to the customer number.

 Claim TypeClaim Value
http://www.mycompany.org/identity/claims/customer023-001
http://www.mycompany.org/identity/claims/customer223-993

In SharePoint, there is a site for each customer and security on the sites is based on the customer claims, not the individual user. So to get to the site for customer 223-993, the logged in user must contain the claim type of http://www.mycompany.org/identity/claims/customer with a value of 223-993.

Each time the user logs on; these custom customer claims will be created for that user based on data in the internal business system. So if the user is transferred to another customer, or is assigned an additional customer in the internal business system, the claims created at login will be created based on this data, and security in SharePoint will then be reflected based on this user’s new customer claims.

For the example where security in SharePoint should be setup for users that are members of 2 AD Groups, logic would be added in the FillClaimsForEntity method to use the logged in user’s id and query Active Directory to determine if the user is in both Group A and Group B. If so, a claim would be created for this.

Claim TypeClaim Value
http://www.mycompany.org/identity/claims/adclaimsGroupA-AND-GroupB (e.g. USCitizen-AND-ITARCertified)

Searching / Resolving Claims from People Picker


protected override void FillSearch(Uri context, string[] entityTypes, string searchPattern, string hierarchyNodeID, int maxCount, SPProviderHierarchyTree searchTree)

When you type search text into the People Picker control, the control will call the FillSearch method of each configured claim provider, passing in the search pattern to query the data sources with. For each item found for the search pattern, a PickerEntity object is created with the claim and added to input searchTree.

For example, if the user types “223”, the internal business system would be queried to find all customers where the customer number starts with “223”.    

In addition, logic could also be added to query the customers based on customer name. So if the user enters “Acme” in the People Picker, all customers where the customer name starts with “Acme” would be returned.

Once a claim is selected in the People Picker control, the control calls the FillResolve method of the claim provider, which is used to add the specific claim to the list of resolved PickerEntity item collection.


protected override void FillResolve(Uri context, string[] entityTypes, string resolveInput, System.Collections.Generic.List resolved)

protected override void FillResolve(Uri context, string[] entityTypes, SPClaim resolveInput, System.Collections.Generic.List resolved)

Logic can be added to these methods to provide a display name to the People Picker Entity.  

For example, using the claim value of the resolve Input, which is the customer number, the internal business system can be queried to get the customer name, so that the customer name is displayed along with the customer number in the People Picker.

Summary

The creation of custom claims allows you to address security situations that were difficult or impossible to address using simple AD security. Custom Claims are a .NET solution to meet those security requirements. (Enhance and secure your Modern Workplace)

Additional Information/Resources

More detailed development steps, as well as how to deploy the custom claims provider can be found in the following links:

http://msdn.microsoft.com/en-us/library/office/ff699494(v=office.14).aspx

http://msdn.microsoft.com/en-us/library/office/ee537299(v=office.15).aspx

Subscribe to our Newsletter

Stay informed on the latest technology news and trends

Relevant Insights

The 6 Major Stages of a Successful Cloud Migration: A Walkthrough

As organizations attempt to stay ahead of an ever-evolving competitive landscape, IT is under mounting pressure from the business to...

Top 7 Highlights from Microsoft Ignite 2021

At Ignite 2021 conference this month, Microsoft unveiled new updates and features for the Microsoft 365 Platform tools including Teams,...

Does Your Security Licensing Match Your Security Posture?

The last thing you want to think about when dealing with IT security is licensing, but it can make a...
X