Checklist for Issues with Custom Claims Providers in SharePoint 2010 and 2013

  • Article

As I was going round and round a few weeks ago trying to figure out why my custom claims provider was not working as I anticipated, one of our great developers (Chris R.) gave me a list of things to look at to try and diagnose the issue. After spending about 5 minutes on his list I realized where the problem was, so I thought I would share his list as food for thought, and throw out a couple of other things I've seen and do as well. This will be a living list, so as Chris or I come up with other suggestions we'll just update this posting. Also, if you folks have tips that you find useful I would encourage you to add them in the comments below. I can't offer any prizes other than a "thanks" from your fellow SharePoint developers! :-) 

So, that being said, here's the list:

  1. Are you logging the call to FillClaimsForEntity? This is a great way to make sure that you can ensure all the claims you think should be getting added, are getting added. I wrote a post about a pretty straightforward way to add logging to your applications some time ago, and it can be found here: https://blogs.technet.com/b/speschka/archive/2011/02/04/tips-for-uls-logging-part-2.aspx.
  2. Look at a list of what claims are being added by your custom claims provider by emitting the encoded claim values. For example, after you add your claims in FillClaimsForEntity you can enumerate through all of the claims for the user with code that looks something like this: foreach (SPClaim c in claims) { Debug.WriteLine(c.ToEncodedString()); }. Once you have the encoded claims that have been added, how can you use them? See tip #3 for that.   
  3. What claims have been added to the site? Go into your Site Settings and find a claim that you have added to a Site Group. Click on it so you can get to the claim details, and it will show you the encoded claim value. Does that encoded claim value that has been added to the Site Group match one of the encoded claims you have added via augmentation (that you've captured in tip #2)? If not, then that may be why users cannot access the site.
  4. Are you sure your claim provider is active and enabled? Use the Get-SPClaimProvider cmdlet to look at your provider. If it IsEnabled is true, but IsUsedByDefault is false, then you should check to make sure it is used in the zone where you are expecting to use it. You can use the ClaimProviderActivation tool for this, which I originally blogged about here: https://blogs.technet.com/b/speschka/archive/2010/06/03/configuring-a-custom-claims-provider-to-be-used-only-on-select-zones-in-sharepoint-2010.aspx and then updated for SharePoint 2013 here: https://blogs.technet.com/b/speschka/archive/2012/09/07/important-change-for-custom-claims-providers-in-sharepoint-2013-and-refresh-of-some-favorite-claims-tools.aspx.
  5. You can also check ALL of the claims that the current user has by using my HttpModule that writes out the users claims to the ULS logs. Again, it provides all the encoded claim values even if a person is denied access to the site, you can see what claims they presented and use tips 2 and 3 above to try and reconcile why access has been denied. This was originally posted here: https://blogs.technet.com/b/speschka/archive/2010/02/13/figuring-out-what-claims-you-have-in-sharepoint-2010.aspx, and was updated for SharePoint 2013 here: https://blogs.technet.com/b/speschka/archive/2012/09/07/important-change-for-custom-claims-providers-in-sharepoint-2013-and-refresh-of-some-favorite-claims-tools.aspx.
  6. A fairly common practice in custom claims providers is to check in the FillResolve methods to see if the entityTypes collection contains FormsRole and if not, to exit. However, if you do this then your custom claims provider will not work when SharePoint is expecting an identity claim only - for example, when selecting a Site Collection Owner or using the Check Perms page in Site Settings. So instead of checking for FormsRole only, IF you have developed a custom claims provider that is the default claims provider, so you are issuing identity claims, then you should check to see if the entityType contains either FormsRole OR User.
  7. Make sure you have all your custom claim provider code in try blocks because an untrapped failure it will result in your and other providers not resolving names at all. If you start seeing that claim values aren't resolving at all, for any provider, it's a good bet that this is the problem. Note that you are most likely to see this when trying to resolve an individual user. Not always, but that's the more common case.
  8. If you get an error along the lines of "user does not exist or is not unique" it usually means that your FillResolve method is returning 0 or 2 or more claims when SharePoint is expecting only one. This one is more difficult to track down, and most times requires a debugger (or really good logging) to figure out what the issue is. This is also an example of an error that you will generally only see when trying to add a user - that's why I try and test so thoroughly on the Site Collection Owner and Check Perms pages whenever I develop a custom provider.

That's the list for now - as I said, we'll keep updating this as we have more things to add. Also, please add your suggestions in the comments too! Hope this helps someone, somewhere, out there.