Grant permissions via custom AD FS claims

In the times of classic authentication, you could only grant permissions to users by grouping them into Active Directory groups or by granting permissions directly to users. With claims authentication we can now virtually use any claim that the users have to grant permissions.

The high level view of this process would be:

1. Identify which claims the users have and which one you want to use.
2. Build the claim value you will use to grant permissions.
3. Add the claim to the item permissions.

Identify the current claims

Depending on the authentication provider configured in the web application the users will have some claims when they log in. After login, SharePoint augments those claims with several claim providers which add more claims to the user identity. One of these claim providers is the User Profile application and this is why it makes sense to have a running User Profile Application to keep the user properties up to date. 

You can use the following PowerShell to get the installed claim providers in the farm:

Get-SPClaimProvider | ft -auto DisplayName,IsEnabled,IsUsedByDefault,IsVisible

DisplayName                 IsEnabledIsUsedByDefaultIsVisible

-----------                 --------- --------------- ---------

System                           True            True      True

Active Directory                 True           False      True

All Users                        True            True      True

Forms Auth                       True           False      True

User Profile Claim Provider      True            True      True

LDAPCP                           True            True      True

The way to check which claims a user has, would be to use a custom web part to show those claims based on the current user. This is an example of such a web part (Helloitsliam.ClaimsViewerWebPart.wsp, can't find the current link for download):

In the example I'm going to use for this post, I want to be able to give permissions to sites using the Department the users have in Active Directory. My lab uses AD FS to authenticate the users.

If you check the screenshot above, you can see that there is no Department claim that we can use to grant permissions so we are going to have to add the claim there.

Adding a custom claim

This is the overview of the steps we need to do to make AD FS forward a new claim to SharePoint and make SharePoint use that claim when authenticating the user:

1. Check if AD FS supports the claim we want to use. If not, create a new Claim description.
2. Modify the AD FS Relying Party to add the claim to the token sent to SharePoint.
3. Modify the trust relationship in SharePoint to accept this new claim and use it in the Claims Identity.

Adding a Claim description in AD FS

We open the AD FS Management console and go to AD FS -> Service -> Claim Descriptions. Here we can find the list of claims supported by AD FS. I don't see a Department claim, so we are going to have to add it.

A new Claim description can be added directly via the console or with PowerShell. My preferred method is always PowerShell so we use the following command:

Add-AdfsClaimDescription -Name Department -ShortName department -ClaimTypehttp://custom-claims/department -IsAccepted $true -IsOffered $true

You can find the documentation of this command here.

After this, we can see the claim in the list and use it in our relying party:

Add the new claim to the Relying party

Just like any LDAP attribute, we need to modify the current Claim rules in the Relying party to pass this claim to SharePoint. Just open the current claim rules and add the new claim to the current rules. You will most probably have a "Send LDAP attributes as claims" so you can directly add the new claim there or add a new rule if you want.

From now on, every new login will include the new claim.

Add the claim to the SharePoint trust

Now that the security token sent by AD FS includes the new token, we need to make SharePoint aware of this new claim.

When we set up AD FS in SharePoint, we create a Trusted Identity Token Issuer. In this issuer object, we define the claims accepted by SharePoint from it and define some mappings from the claim type to the internal claim type.

So, what claim types are currently accepted by SharePoint? As usual, we use PowerShell for this:

Get-SPTrustedIdentityTokenIssuer | % { Write-Host $_.Name; $_.ClaimTypes | ft -auto }

And this is the current output:

ADFS UPN

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

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

http://schemas.microsoft.com/ws/2008/06/identity/claims/role

http://schemas.microsoft.com/ws/2008/06/identity/claims/primarysid

To add the new claim type we do the following:

$ctype = "http://custom-claims/department"

# First, weneed to define the new encodingcharacter for this new claim

# Make sure that your character is not used in another encoding, it is above 500 (0x01F5) and not an uppercase or whitespace character.

New-SPClaimTypeEncoding -EncodingCharacter ([Convert]::ToChar(501)) -ClaimType $ctype

# Add the mapping

$ti = Get-SPTrustedIdentityTokenIssuer "ADFS UPN"

$ti.ClaimTypes.Add($ctype)

$map = New-SPClaimTypeMapping -IncomingClaimType $ctype -IncomingClaimTypeDisplayName "Department" –SameAsIncoming

Add-SPClaimTypeMapping–Identity $map–TrustedIdentityTokenIssuer $ti

# Confirm the mapping works, the following should return an encoded claim.

(New-SPClaimsPrincipal -TrustedIdentityTokenIssuer "ADFS UPN" -ClaimValue "Dept 1" -ClaimType "http://custom-claims/department").ToEncodedString()

Fromnowon, SharePoint acceptstheincomingDepartmentclaimfrom AD FS and addsit to theclaimsidentitythatrepresentsthelogged in user.

Wecouldevenchecktheclaimsviewerwebpartagain and wewillnowseethe new claim in theidentity:

Grantingpermissionsusingthe new claim

Thenextstep, once theclaimwewant to use isavailable, is to grantpermissionusingthisclaim. Ideally, wewouldlike to directlytypethevalue of the new claim in PeoplePicker and getitcorrectly resolved byPeoplePicker. Unfortunately, SharePoint doesnot do thisout of the box and wewillneed to use a customclaimproviderifwewantthisfeature.

Out of the box we can use PowerShell to grantpermissions.

$web = Get-SPWebhttps://team.2013.net

# Thiswill use theClaimProviderusedbytheTrustedIdentityTokenIssuer

$claim = New-SPClaimsPrincipal -TrustedIdentityTokenIssuer "ADFS UPN" -ClaimValue "Dept 1" -ClaimType "http://custom-claims/department"

## Ifthereis no ClaimProviderthat can resolvetheclaim, New-SPUserwillfailbutwe can directlygrantpermissionsusingRoleAssignments

# Example: directlygrantReadpermissionsonthe web

[Microsoft.SharePoint.SPRoleAssignment] $roleAssignment = New-ObjectMicrosoft.SharePoint.SPRoleAssignment($claim.ToEncodedString(), "", "Department 1", "")

$roleAssignment.RoleDefinitionBindings.Add($web.RoleDefinitions["Read"])

$web.RoleAssignments.Add($roleAssignment)

# Example: addtheclaim to a SharePoint group

$group = $web.Groups["members"]

$group.AddUser($claim.ToEncodedString(), "", "Department 1", "")

However, thebest and more userfriendlyapproachis to use a customclaimproviderthat can be configured to resolvecustomclaims. LDAPCPistrulyawesome.

With it, we just have to configure a new claim mapping…

 …and People Picker will work like a charm: