Introducing the SharePoint 2010 Get-SPClaimTypeEncoding and New-SPClaimTypeEncoding cmdlets

Tags: SharePoint 2010

A couple of months back, when the weather was grey and it was cold (well, it still is here in Sweden, glad I did a tour to the Riviera last week), I wrote a post about how Claims encoding works in SharePoint 2010, simply called "How Claims encoding works in SharePoint 2010". In that post I discussed how SharePoint encoded Claims from relatively long descriptive claims, containing URN's, to a smarter and shorter format - smaller to store, faster to compare format etc. While there are tons of defined claim types only a selected few are "pre-encoded" in SharePoint. Here are a few examples:

Claim Type

Encoded value

http://schemas.microsoft.com/sharepoint/2009/08/claims/userlogonname

#

http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier

?

http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress

5

Once you start adding providers and Claim Types to SharePoint 2010 using you might start using Claim Types that are not pre-defined by SharePoint. In this case SharePoint automagically assigns the encoded Claim Type a unicode character starting with the 0x01F5 (500 or ǵ) and then incrementing that value with 1 for each and every Claim Type. (Note that it's not just incremental, it can't be uppercase characters or whitespaces.) This is really important to know since if you ever going to move information from one farm to another then you need to configure them in exactly the same order, otherwise your Claim Types encodings, or SharePoint for that matter, won't work.

Until the June 2012 Cumulative Update there was no (good) way to find out what the encodings were that you've added and there was no way to specify the encoding for a Claim Type. But from now on we have two sleek cmdlets; the Get-SPClaimTypeEncoding and the New-SPClaimTypeEncoding.

Get-SPClaimTypeEncoding

The Get-SPClaimTypeEncoding is a lightweight cmdlet that allows you to list all the defined Claim Type encodings in your farm - both the pre-defined ones and the ones you've added yourself. Just run the cmdlet like this to list all the Claim Type encodings:

Get-SPClaimTypeEncoding

This will give you the following output:

Get-SPClaimTypeEncoding

Note that I have two custom Claim Types, both listed with a question mark (PowerShell can't print Unicode characters - eeek!). Both of these are ones that have been added when I've fiddled with Claims and they have both been automatically been assigned an encoding character. To get a better idea of the encoded character, just run the following PowerShell:

Get-SPClaimTypeEncoding | ft @{Label="Character";Expression={[Convert]::ToInt32($_.EncodingCharacter)}}, ClaimType

This will show us, exactly which double-byte character that has been used for the encoding:

No more ?

New-SPClaimTypeEncoding

Using the New-SPClaimTypeEncoding cmdlet we can also add our own encodings, not that we can use any fancy vanity encodings, but at least they can be specified. The cmdlet takes two arguments the -EncodingCharacter which is the encoded value and the -ClaimType. Here's an example on how you can use it:

New-SPClaimTypeEncoding -EncodingCharacter ([Convert]::ToChar(517)) -ClaimType "urn:another-claim-type"

After answering Yes two times you'll now have the Claim Type encoding in your farm, and once you use it for a mapping it will not generate a new encoding.

I'm encoded!

Note; if you get an ArgumentException it can be one of many reasons. Make sure that your character is not used in another encoding, it is above 500 (0x01F5) and not an uppercase or whitespace character.

Summary

That was it, two small but quite powerful and really useful cmdlets. Whenever you need to script environments and are doing Claim Type mappings, make sure that you utilize what you got in the toolbox!

6 Comments

  • Markus Wehr said

    haha vanity encoding characters. I cant wait to use the smilie as identifier and the female sign for some special claim. :)

    Do you know if with jun 2012 CU its still true to better use either UPN or email as identifier because with unicode we will get trouble while redirecting to mysites?


  • Gustavo Carpaneses said

    Great Post Wictor! Excelent!

    Do you know if there is a way to change the Encoding Character of an existing Claim Type? We've different Encoding Character for the same Claim Type between our farms.

    Tks Very Much!

  • Shadrick Bowe said

    Hi Wictor,

    Thank you for posting the super helpful information. One question I do have is the following:

    If you can't change the encoding character, then how can you delete the custom Claim Type?

    I was able to temporarily change the encoding character by doing the following however it didn't actually take after the fact:
    $claimTypeEncoding = Get-SPClaimTypeEncoding
    $claimTypeEncoding | FT @{Label="EncodingCharacter";Expression={[Convert]::ToInt32($_.EncodingCharacter)}}, ClaimType -auto
    #Take note of existing Encoding Character then perform below to see it change
    #Enter whatever your actual claim is ..
    $claimType = $claimTypeEncoding | ?{$_.ClaimType -eq "http://schemas.xmlsoap.org/claims/CustomClaimName"}
    #Enter the Encoding Character number you'd like to see ..
    $claimType.EncodingCharacter = ([Convert]::ToChar(123))
    #To see the change rerun this
    $claimTypeEncoding | FT @{Label="EncodingCharacter";Expression={[Convert]::ToInt32($_.EncodingCharacter)}}, ClaimType -auto

    Now if there was a way to make this stick .. that would be great.

    Thanks,
    Shad

Comments have been disabled for this content.

About Wictor...

Wictor Wilén is the Nordic Digital Workplace Lead working at Avanade. 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 seven consecutive years.

And a word from our sponsors...