SharePoint 2013 Grant permissions via custom ADFS 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                 IsEnabled IsUsedByDefault IsVisible

———–                 ——— ————— ———

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 –ClaimType http://custom-claims/departmentIsAccepted $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, we need to define the new encoding character 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-SPClaimTypeEncodingEncodingCharacter ([Convert]::ToChar(501)) –ClaimType $ctype

 

# Add the mapping

$ti = Get-SPTrustedIdentityTokenIssuer “ADFS UPN”

$ti.ClaimTypes.Add($ctype)

$map = New-SPClaimTypeMappingIncomingClaimType $ctypeIncomingClaimTypeDisplayNameDepartment” –SameAsIncoming

Add-SPClaimTypeMappingIdentity $mapTrustedIdentityTokenIssuer $ti

 

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

(New-SPClaimsPrincipalTrustedIdentityTokenIssuer “ADFS UPN” –ClaimValueDept 1″ –ClaimTypehttp://custom-claims/department“).ToEncodedString()

 

From now on, SharePoint accepts the incoming Department claim from AD FS and adds it to the claims identity that represents the logged in user.

 

We could even check the claims viewer webpart again and we will now see the new claim in the identity:

 

 

 

Granting permissions using the new claim

The next step, once the claim we want to use is available, is to grant permission using this claim. Ideally, we would like to directly type the value of the new claim in People Picker and get it correctly resolved by People Picker. Unfortunately, SharePoint does not do this out of the box and we will need to use a custom claim provider if we want this feature.

Out of the box we can use PowerShell to grant permissions.

 

$web = Get-SPWeb https://team.2013.net

 

# This will use the Claim Provider used by the TrustedIdentityTokenIssuer

$claim = New-SPClaimsPrincipalTrustedIdentityTokenIssuer “ADFS UPN” –ClaimValueDept 1″ –ClaimTypehttp://custom-claims/department

 

## If there is no Claim Provider that can resolve the claim, New-SPUser will fail but we can directly grant permissions using RoleAssignments

# Example: directly grant Read permissions on the web

[Microsoft.SharePoint.SPRoleAssignment] $roleAssignment = New-Object Microsoft.SharePoint.SPRoleAssignment($claim.ToEncodedString(), “”, “Department 1″, “”)

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

$web.RoleAssignments.Add($roleAssignment)

 

# Example: add the claim to a SharePoint group

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

$group.AddUser($claim.ToEncodedString(), “”, “Department 1″, “”)

 

However, the best and more user friendly approach is to use a custom claim provider that can be configured to resolve custom claims. LDAPCP is truly awesome.

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

 

 

 and People Picker will work like a charm:

 

 

 

Comments (8)

  1. Joao Ricardo Carvalho says:

    Super clear tutorial! Thanks

  2. Martin says:

    Hi,

    thanks for this tutorial. Unfortunately the link to the ClaimsViewerWebPart.wsp is down 🙁 Could you upload it as a zip file? Thanks 🙂

  3. Martin says:

    The most links to the WebPart are currently down. Here is the link to download it from Liams Website:

    http://www.helloitsliam.com/downloads-and-links

    1. Hi Martin,
      Thanks for the link. If you are interested in the code, I have a similar claims viewer webpart in my github account: https://github.com/jesusfer/FedRolesCP

  4. LATHANIEL DILLON says:

    How do I add or modify the claims list to my token issuer?

    1. I think what you mean is explained in the section “Add the claim to the SharePoint trust”.

  5. Jack says:

    Great information but your powershell on the last part is unclear – You use “Department 1” rather than “dept 1” or department – i am assume you meant “dept 1” ? I am just trying to get my head around use an Trusted Ip – wanting to use roles/groups rather than requiring users to be added individually – are you saying any claim will be evaluated and in theory you can add any claim for a group?

    I am actually use an external STS which brokers all the authentication ADFS, OAUTH etc and then remaps to SAML for SP – using groups is the last piece of the puzzle

    Thanks !!!

    1. If you mean “Department 1” in the AddUser method, then it’s just the display name.

Skip to main content