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.

23 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.

  • Wictor said

    @Alan - you're correct. It has been removed from the new (which is the 2013 Preview) documentation.

  • 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?

  • Sergey Azarkevich said

    Wictor, I found claim on SP with unknown 'claim type':

    c:0(.s|true

    what '(' means ?

    P.S. Thanks for great article.

  • 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

  • グッチ 財布 メンズ アウトレット said

    Boyle said that yesterday evening I tune in to, I feel pretty useful. Tell the story of one's friends? No, it's the story of any tomato and cucumber. I slept last night so, overheard. Sleep...... This patch? Not too hot?
    [url=http://gucci.ehoh.net/]グッチ 財布 メンズ アウトレット[/url]

  • グッチ 新作 2014 said

    I immediately turned to the kitchen, but see a knight knife shows, stand stands a weight teacher, left hand over the solitary spoon, right hand waving some sort of spatula. I approached, a bent over his or her shoulder li ye. What brings you the following? His shy smile to state I am here available, you here are some sort of sight for sore face.
    [url=http://gucci.huuryuu.com]グッチ 新作 2014[/url]

  • グッチ 新作 2014 said

    To outsiders, this sentence sounds could be nothing, but I think his / her every word, seemingly smooth surface integrity, but together with the actual dark, until the words bouncing suddenly collapse when it comes to me open the agnail, dumb to Pierce the skin, and to grow. He this sentence implies that he thinks I don't write the content is useless, useless, I can go to waste youth, wasted time, because my time in addition to youth also useless is usually useless. Asked by his dad this evaluation, in addition to the sand and blame I also should hand out another mood?
    [url=http://gucci.bake-neko.net]グッチ 新作 2014[/url]

  • グッチ アウトレット 店舗 said

    A few years later, a miracle never occurred. Your life gradually restores peaceful, as he sank down the river. Mix are not negative, you have a partner. Live a life connected with nine to five each day, like a normal person. The first two several years, the people in the location have been shouting for you to stray, in your opinion, as a group involving boys are singing the moment.
    [url=http://gucci.goraikou.com]グッチ アウトレット 店舗[/url]

  • グッチ 財布 新作 2014 said

    Don't know when you head over to school ever experience considering that the class a of the person you like, even don't like to study, even have a fever a cold, will be voluntary, happily go to classes, because the man is actually hope Boyle said.
    [url=http://gucci.ehoh.net/]グッチ 財布 新作 2014[/url]

  • グッチ 時計 メンズ アウトレット said

    The end of the, if you are one, many people speculated until this is speculation, male guest on the spur from the moment, they will break upward soon. Wu Yi responded to your account about the program, we have no individual, I like and perfumed (our anger courageously) beverage chat, you can talk for some hours. I think, she is an classy and noble, there is the legend of an woman. I hope that isn't just my confidante, and my little brother, can close in cardiovascular, which can help myself in wisdom.
    [url=http://gucci.husuma.com]グッチ 時計 メンズ アウトレット[/url]

  • http://gucci.gokenin.com said

    Night market remains an entire day hold down stench, corruption leaves SAO quality taste, chickens, ducks, and farmers to the scent of sweat and couldn't say for sure route. Aunt lying on the spring bed blowing admirer, in a daze is usually fast asleep, suddenly heard a tone of voice hushed, don't you come over, I used to. If you broke my heart. By the light of street lamps comes in, Boyle saw a cucumber not work skipping to jump to be able to his stall. At the same moment, the aunt left, a tomato quietly thoroughly to stall edge coming over. Cucumber scampering to booth, tried a few times always can't hop on the stall.
    [url=http://gucci.gokenin.com]http://gucci.gokenin.com[/url]

  • ブランド サングラス said

    Nevertheless,, what we see is this world, love to love the very best answer.
    [url=http://sunglasses.ashigaru.jp/]ブランド サングラス[/url]

  • グッチ 時計 メンズ アウトレット said

    You really love is also not never seen your pet. Popping a year associated with winter night, someone knocks on ones door, he was standing with the door, a bearded. You this just located. He wearing slippers every one of the year round. Which has a undesirable cold. You didn't say something, into the kitchen for your first two packages involving instant noodles, whisk two eggs. He also says almost nothing. Cleaning is finished. In this world, a person is ready to give you see he's ugly overall look, you only be pleased. You look at his / her drunk unconscious, then take care of him as being a man; You what all do not ask, only said 1 or to stop, find a likeness in the person together. He said confused together with going tired, but can't stop.
    [url=http://gucci.hishaku.com]グッチ 時計 メンズ アウトレット[/url]

  • グッチ アウトレット 店舗 said

    Registration is a principal culture of li ye. The action is almost and literacy. But he talked about for the river's lake thing, like a broad in addition to deep scholar.
    [url=http://gucci.cho-chin.com]グッチ アウトレット 店舗[/url]

Add a Comment

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