Sharepoint 2013 : Claims-based authentication, federated identities, and OAuth (part 5) - SharePoint trusted IPs - Creating a custom claims provider

3.3 Creating a custom claims provider

When SharePoint authenticates a user via claims-based authentication, it engages a claim provider, which is a class providing claims augmentation and name resolution utilities. Claims augmentation allows for adding some custom claims to the security token retrieved by the authentication infrastructure. Name resolution allows for adding capabilities to search, resolve, and provide friendly values for claims, people, and roles in the PeoplePicker control.

Depending on the authentication type you use, SharePoint will access one of three default claims providers:

The claims provider engaged for SAML-based tokens provides claim augmentation capabilities, but it does not provide real name-resolution functionality. In fact, when you shared your site with people and groups, as shown in Figure 9, you were simply using a fake model for claims and name resolution. The PeoplePicker control accepts any text value you provide to it and resolves it as if it is a real claim value provided by the federated IP/STS. Unfortunately, this behavior can lead to confusion for the end users. Usually, when using SAML-based authentication, you should also implement a custom claims provider to fix this standard behavior.

To better experience this issue, open SPCA and select the Manage Web Applications menu item in the Application Management menu group. Then select the web application you previously configured for using the external IP/STS, and click User Policy on the ribbon. If you add a new user policy from the resulting dialog box, and you choose to search for a specific set of users or roles while within the PeoplePicker control, you will see the search dialog box shown in Figure 10.

Figure 10. The Select People And Groups dialog box of a PeoplePicker control.

Within the Select People And Groups dialog box, you can search for people and groups, based on claims values. You will be able to write any text value, however, even if that value does not exist or is not handled by the federated IP/STS. To fix this behavior, you will need to implement a custom claims provider.

A custom claims provider, like those available out of the box, is just a class that provides claims augmentation and name resolution capabilities. An excerpt of a sample claims provider class for supporting custom claims provides an excerpt of a sample claims provider class, supporting the claims provided by the custom IP/STS illustrated previously.

public class DevLeapClaimsProvider: SPClaimProvider {
    private static String genderClaimType =
        "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/gender";
    private static String favoriteColorClaimType =
        "http://schemas.devleap.com/SampleIPSTS/claims/favoritecolor";
    private static String fidelityProgramLevelClaimType =
        "http://schemas.devleap.com/SampleIPSTS/claims/fidelityProgramLevel";
    public DevLeapClaimsProvider(String displayName)
        : base(displayName) {
    }
    public static String ProviderDisplayName {
        get { return "DevLeap Claims Provider"; }
    }
    internal static String ProviderInternalName {
        get { return "DevLeapClaimsProvider"; }
    }
    public override String Name {
        get { return ProviderInternalName; }
    }
    // Available values for the Gender claim
    private String[] genderValues = new String[] { "Male", "Female" };
    // Available values for the FavoriteColor claim
    private String[] favoriteColorValues = new String[] { "White", "Green", 
    "Yellow", "Red", "Blue", "Black" };
    // Available values for the FavoriteColor claim
    private String[] fidelityProgramLevels = new String[] { "Bronze", "Silver", 
        "Gold", "Platinum" };
    // Code omitted for the sake of brevity …
}

The class was created in a .NET 4.5 Class Library project, which references the basic Microsoft.SharePoint.dll assembly and the Microsoft.IdentityModel.dll assembly for WIF 1.0. The basic idea of this sample claims provider is to provide predefined values for the gender and favoriteColor claims, as well as to augment the security token of authenticated users with a fidelityProgramLevel claim, which can assume only four values: Bronze, Silver, Gold, or Platinum.

Although the companion code provides claims augmentation and name resolution functions, the code illustrated in An excerpt of a sample claims provider class for supporting custom claims simply defines the basic infrastructure of the class. As you can see, the custom claims provider class inherits from the SPClaimProvider abstract class, which is available in the Microsoft.SharePoint.Administration.Claims namespace of the Microsoft.SharePoint.dll assembly. The SPClaimProvider base class provides many members that can be overridden, depending on the type of capabilities you want to provide through your custom claims provider. First of all, and regardless the type of claims provider you are implementing, you need to override the Name property to provide a name unique at the farm level for the custom claims provider.

To implement name resolution, you need to override the following abstract methods:

protected abstract void FillSchema(SPProviderSchema schema);
protected abstract void FillClaimTypes(List<String> claimTypes);
protected abstract void FillClaimValueTypes(List<String> claimValueTypes);
protected abstract void FillEntityTypes(List<String> entityTypes);

To implement claims augmentation, you must override the following members:

public abstract bool SupportsEntityInformation
protected abstract void FillClaimsForEntity(Uri context, SPClaim entity,
    List<SPClaim> claims);

Optionally, you can override members to support hierarchies, to resolve claims, or to support searching claims:

public abstract bool SupportsHierarchy
protected abstract void FillHierarchy(Uri context, String[] entityTypes,
    String hierarchyNodeID, int numberOfLevels, bool includeEntityData,
    SPProviderHierarchyTree hierarchy);
public abstract bool SupportsResolve
protected abstract void FillResolve(Uri context, String[] entityTypes,
    String resolveInput, List<PickerEntity> resolved);
protected abstract void FillResolve(Uri context, String[] entityTypes,
    SPClaim resolveInput, List<PickerEntity> resolved);
public abstract bool SupportsSearch
protected abstract void FillSearch(Uri context, String[] entityTypes,
    String searchPattern, String hierarchyNodeID, int maxCount,
    SPProviderHierarchyTree searchTree);

As you may gather from the names of the abstract properties, you need to declare your support for any specific functionality. For example, if you want to support search capabilities, you will need to override the Boolean SupportsSearch property, returning a value of true, and then you will have to override the FillSearchAn excerpt of a sample claims provider class, showing the FillSearch custom method shows a code excerpt of the implementation of the FillSearch method, which is invoked by the PeoplePicker control when searching for a specific value. method.

protected override void FillSearch(Uri context, string[] entityTypes,
    string searchPattern, string hierarchyNodeID, int maxCount,
    Microsoft.SharePoint.WebControls.SPProviderHierarchyTree searchTree) {
    // Check if the picker is requesting the types we effectively return
    // Because this custom claims provider returns roles
    // simply continue in case the request is for role claims
    if (!EntityTypesContain(entityTypes, SPClaimEntityTypes.FormsRole))
        return;
    // Nodes where we will stick our matches
    Microsoft.SharePoint.WebControls.SPProviderHierarchyNode matchNode = null;
    #region Fidelity Program Levels
    // Look to see if the value that is typed in matches any of the claims values
    foreach (string level in fidelityProgramLevels) {
        if (level.ToLower().StartsWith(searchPattern.ToLower())) {
            // We have a match, create a matching entity
            PickerEntity pe = GetPickerEntity(level,
                fidelityProgramLevelClaimType, "Fidelity Program Level");
            // Add the level node where it should be displayed too
            if (!searchTree.HasChild(level)) {
                // Create the node so we can show our match in there too.
                matchNode = new
                    SPProviderHierarchyNode(
                    DevLeapClaimsProvider.ProviderInternalName,
                    level,
                    level,
                    true);
               // Add it to the tree
                searchTree.AddChild(matchNode);
            }
            else
                // Get the node for this team.
                matchNode = searchTree.Children.Where(theNode =>
                    theNode.HierarchyNodeID == level).First();
            // Add the match to our node.
            matchNode.AddEntity(pe);
        }
    }
    #endregion
    // The same is done for gender and favoriteColor claims
    // Code omitted for the sake of brevity
}

Now you are ready to deploy the custom claims provider implementation. To achieve this, you need to create a SharePoint farm-level solution with a custom feature and a feature receiver in it. The only goal of the farm-level solution is to copy the assembly containing the custom claims provider into the Global Assembly Cache (GAC) of the servers in the SharePoint farm.

Moreover, you will have to implement a specific kind of feature event receiver that inherits from the SPClaimsProviderFeatureReceiver class. You will use it to enable the claims provider on the farm by settings its IsUsedByDefault property to a value of true. By default, when you install a claims provider onto a target farm, it is configured as disabled. An excerpt of the feature receiver for deploying a custom claims provider details the feature receiver used to deploy the custom claims provider described in this section.

public class ProvisioningFeatureEventReceiver : SPClaimProviderFeatureReceiver {
    private void ExecBaseFeatureActivated(
        Microsoft.SharePoint.SPFeatureReceiverProperties properties) {
        base.FeatureActivated(properties);
    }
    public override string ClaimProviderAssembly {
        get { return typeof(DevLeapClaimsProvider).Assembly.FullName; }
    }
    public override string ClaimProviderType {
        get { return typeof(DevLeapClaimsProvider).FullName; }
    }
    public override string ClaimProviderDisplayName {
        get { return DevLeapClaimsProvider.ProviderDisplayName; }
    }
    public override string ClaimProviderDescription {
        get { return "A sample provider to augment claims and resolve " +
            "claims provided by sample IP/STS"; }
    }
    public override void FeatureActivated(SPFeatureReceiverProperties properties) {
        ExecBaseFeatureActivated(properties);
        SPClaimProviderManager cpm = SPClaimProviderManager.Local;
        foreach (SPClaimProviderDefinition cp in cpm.ClaimProviders) {
            if (cp.ClaimProviderType == typeof(DevLeapClaimsProvider)) {
                cp.IsUsedByDefault = true;
                cpm.Update();
                break;
            }
        }
    }
}

After installing and deploying the solution and activating the feature, you will have to map the custom claims provider with the target web application in which you want to use the provider. To map a web application to a specific claims provider, you can use a small PowerShell script like the one A PowerShell script for registering a custom claims provider onto a target web application.

Add-PSSnapin Microsoft.SharePoint.PowerShell -erroraction SilentlyContinue
$AuthNAppHostHeader = "claims.sp2013.local"
$Zone = "Default"
$cp = Get-SPClaimProvider | where-object {$_.TypeName -eq "DevLeap.IPSTS.Providers.DevLeapClaimsProvider"}
$webApp = Get-SPWebApplication "http://$AuthNAppHostHeader"
if ($webApp.IisSettings.ContainsKey($Zone)) {
    $settings = $webApp.GetIisSettingsWithFallback($Zone) 
    $providers = $settings.ClaimsProviders 
    if( -not($providers.Contains($cp))) {
        $providers += $cp
        Set-SPWebApplication -Identity $webApp -Zone $Zone
            -AdditionalClaimProvider $providers
        Write-Host "Registered" $cp.DisplayName "on" $webApp.Url "in zone $Zone"
    } else {
        Write-Host $cp.DisplayName "already registered on" $webApp.Url 
        "in zone $Zone"
    }
}

Now you are ready to check the result. Back on the User Policy page of the web application, check the new capabilities that you will find in the Select People And Groups dialog box. Figure 11 illustrates the new layout of the dialog box. By searching a particular value, like the value Gold for the fidelity program level, you will see the result highlighted in the proper claim node.

Figure 11. The Select People And Groups dialog box of a PeoplePicker control with the custom claims provider configured.

Consider that the sample claims provider discussed in this section augments claims, too. In fact, after installing the custom claims provider in the list of users’ claims, you will find a fidelityProgramLevel claim. Figure 11 shows the presence of the new custom claim provider, as you can see in the DevLeap Claims Provider item in the hierarchy on the left side of the screen.

While in Figure 12 you can see the claims of the currently logged in user, in particular you can see the gender, favoriteColor, and fidelityProgramLevel claims.

Figure 12. The list of claims related to a logged-in user, after claims augmentation.