This post is migrated from previous hosting provider. There are still some issues with old posts. Please make a comment on this post with any issues.

How Claims encoding works in SharePoint 2010

Tags: SharePoint 2010

I've seen it asked numerous times on forums and I've been asked over and over how to interpret the encoded claims - so here it is: a post which will show you all the secrets behind how claims are encoded in SharePoint 2010.

Updates: - 2012-03-09 Added Forms Authentication info. - 2012-03-11 Updated with information about how the claim type character is generated for non-defined claims

Background

If you have been using previous versions of SharePoint 2007, been working with .NET or just Windows you should be familiar with that (NETBIOS) user names are formatted DOMAIN\user (or provider:username for FBA in SharePoint). When SharePoint 2010 introduced the claims based authentication model (CBA) these formats was not sufficient for all the different options needed. Therefore a new string format was invented to handle the different claims. The format might at first glance look a bit weird...

How it works?

The claim encoding in SharePoint 2010 is an efficient and compact way to represent a claim type and claim value, compared to writing out all the qualified names for the claim types and values. I will illustrate how the claim are encoded in SharePoint 2010 focused on user names, but this claim encoding method could be used for basically any claim. Let's start with an illustrative drawing of the format and then walk through a couple of samples.

The format

The format is actually well defined in the SharePoint Protocol Specifications in the [MS-SPSTWS] document, read it if you want a dry and boring explanation, or continue to read this post...

The image below shows how claims are encoded in SharePoint 2010, click on the image for a larger view of it.

The SharePoint 2010 claim encoding format

Let's start from the beginning. The first character must be an I for an identity claim, otherwise it has to be c. Note that the casing is important here. The second character must be a : and the third a 0. The third character is reserved for future use.

It's in the fourth character the interesting part starts. The fourth character tells us what type of claim it is and the fifth what type of value. There are several possible claim types. The most common are; user logon name (#), e-mail (5), role (-), group SID (+) and farm ID (%). For the claim value type a string is normally used and that is represented by a . character. The sixth character in the sequence represents the original issuer and depending on the issuer the format following the sixth character varies. For Windows and Local STS the seventh character is a pipe character (|) followed by the claim value. The rest of the original issuers have two values separated by pipe characters, the name of the original issuers and then the claim value. Easy huh?

Note: the f (Forms AuthN) as trusted issuer is not documented in the protocol specs, and this is what SharePoint uses when dealing with membership providers (instead of m and r). For more info see SPOriginalIssuerType.

For full reference of claim types and claim value types, look into the [MS-SPSTWS} documentation.

Charmap(Added 2012-02-13) If you are creating custom claim providers or using a trusted provider (as original issuer), you will see that you get some "undocumented" values in the Claim Type (4th) position (that is they are not documented in the protocol specs). The most common character to see here is ǵ (0x01F5). If the claim encoding mechanism in SharePoint cannot find a claim type it automatically creates a claim type encoding for that claim. It will always start with the value of 500 increment that value with 1 which results in 501. 501 is in hex 01F5 which represents that character. It will continue to increase the value for each new (and to SharePoint not already defined) claim type. The important thing here to remember is that these claim types and their encoding is not the same cross farms, it all depends on in which order the new claim types are added/used. (All this is stored in a persisted object in the configuration database)

Update 2012-07-13: Make sure to read the "Introducing the SharePoint 2010 Get-SPClaimTypeEncoding and New-SPClaimTypeEncoding cmdlets" post to see how you can improve the custom claim type encoding experience in SharePoint 2010 June 2012 CU and forward.

Some notes: the total length must not exceed 255 characters and you need to HTML encode characters such as %, :, ; and | in the claim values.

Some samples

If this wasn't clear enough, let's look at a few samples.

Standard Windows claim

Windows claim

Another common claim. This time it's not an identity claim but an identity provider claim, and this is how NT AUTHORITY\Authenticated Users is represented.

Authenticated users claim

This is how a Windows Security Group is represented as a claim. The value represents the SID of the group.

Security Group claim

If we're using federated authentication (as in the Azure AuthN series I 've written) we can see claims like this. It's an e-mail claim from a trusted issuer called Azure.

E-mail claim

Here's how a claim can be encoded if we're having a role called facebook in the trusted issuer with the name Azure.

Role claim

This final example shows how the encoded claim for the Local Farm looks like. It's a Farm ID claim from the system Claim Provider and the claim value is the ID of the farm.

Farm claim

This is how a forms authenticated user claim looks like. image

Summary

I hope this little post showed you all the magic behind the claims encoding in SharePoint. It's quite logical...yea really.

12 Comments

  • Markus said

    Good Article. so there are only 2 options to choose the id claimtype (and the encoded character) for trusted providers: email (5) and upn (e). Other claim types like http://schemas.microsoft.com/sharepoint/2009/08/claims/useridentifier lead to unicode characters (i:0ǵ.t) What seem to lead to Problems in some circumstances. The New-SPTrustedIdentityTokenIssuer cmdlet doesnt accept the user logon name claim Type. can you clarify on this?

  • Markus said

    thank you very much. so.. http://schemas.microsoft.com/sharepoint/2009/08/claims/useridentifier was a typo. misleading.. one should better use UPN/email as identifier claim type

  • Nik Patel said

    Have you tried to use SPWeb.EnsureUser to lookup claims token for people picker? I wonder how you can access it in code for custom STS (e.g. i:0ǵ.t|customprovider|nikspatel)

  • Andy Daniel said

    Wictor, one thing you might want to add is that the latin lowercase g with acute is a double byte character and gets encoded as such in ReturnURL scenarios (redirect to different web app where account name is passed and ADFS authentication is in play). Therefore you need an HTTPModule to catch and re-encode correctly to %C7%B5 as opposed to ǵ which gets encoded TWICE in a redirect and breaks because that gets encoded in two double bytes :). In this case, Mysite profile redirection from a search result breaks because the user cannot be found. Nik, VS editor is UTF so there's no issue coding against that character. Just make sure you copy and paste it from the SP UI and keep it in a safe UTF text file for reference. :)

  • Alan Cox said

    "For full reference of claim types and claim value types, look into the [MS-SPSTWS} documentation."

    Is that the correct document? I don't see any discussion in the current version (v20120630) of that doc.

  • ConcernedUser said

    How does this come into play in a DR scenario with a warm standby farm at a remote location? Say content databases are being moved over using logshipping or mirroring and then brought online on that second farm. The SharePoint Configuration database isn't moved over in this type of a scenario.....any ideas?

  • Thomas Carpe said

    When overriding FillClaimsForEntity in SPClaimProvider, I sometimes get claims with OriginalIsser="SecurityTokenService" where the claim value is missing the leading "i:" or "c:". Instead they have the prefix "0e.t|". What's the 'e' for? and what gives with the weird format? I am running the CU from Feb 2013 and this seems to be recent behavior.

  • Kalai said

    How do I search for a user with his/her user name in the claims authentication enabled site?

    As of now, for classic mode authentication site, we use CAML query to search a user in Userinfo table.

    For claims authentication enabled site, we need to pass identity claims encoding type information(e.g. i:0#.w or i:0#.f|fba|) along with the user name to get the user. Either I have to append the encoding information to the user name, before passing it to CAML query or I have to find an alternate way for search.

    Information available with me are

    Web application id
    Zone
    Type of search [e.g. username, email, etc.]

    Based on the available information, how do I get the identity claims encoding information?

    (Or)

    Do we have any user control (like people picker), in which we will set the web application id , site URL, search text and it will return the users with their provider information?

  • Sarat said

    Hi Wictor


    I'm using the trail version of Office 365 site. In the view source of the page I found one of the value in the "_spPageContext" that looks similar to..
    "i:0h.f|membership|email@live.com"
    What does the "h" (i:0"h") stand for???


    -Regards,
    Sarat

Comments have been disabled for this content.

AWS Tracker

About Wictor...

Wictor Wilén is a Director and SharePoint Architect working at Connecta AB. Wictor has achieved the Microsoft Certified Architect (MCA) - SharePoint 2010, Microsoft Certified Solutions Master (MCSM) - SharePoint  and Microsoft Certified Master (MCM) - SharePoint 2010 certifications. He has also been awarded Microsoft Most Valuable Professional (MVP) for four consecutive years.

And a word from our sponsors...

SharePoint 2010 Web Parts in Action