ADFS has the concept of claim rules which allow you to enumerate, add, delete, and modify claims. This is useful when you want for example introduce extra claims (based on data in a database or AD) or transform incoming claims. I wrote about claim rules before but I want to give a heads up about some of the lessons I learned along the way.
Lesson 1 - Claim rules can be configured at 2 levels
There are 2 locations in ADFS where you can configure claim rules. The first one is at the level of the relying party:
The second is at the level of the claims provider:
If you don’t know what either is, a short explanation:
In Active Directory Federation Services (ADFS), a claims provider is the entity that authenticates users and issues claims about them. This can be Active Directory but also another IP-STS.
A relying party is an application or service that relies on the claims provided by the claims provider to make authorization decisions.
Essentially, the claims provider verifies the user’s identity and the relying party uses this information to grant or deny access to its resources.
Lesson 2 - No claims are passed by default
Every incoming claim goes through a pipeline where it first passes the claims provider rules and afterwards the relying party rules. Important to notice is that no claims are passed by default so you either have to explicitly specify a claim rule for every claim you want to pass on;
Or you create a custom rule that passes all claims(I would not recommend this to avoid unexpected behavior):
Lesson 3 - There is the concept of an input claim set and output claim set
When working with claims both at the claims provider and relying party level, you need to understand that there is an input claim set and an output claim set. That also explains lesson number 2. Incoming claims end up in the input claim set and the example rules we used above copy these claims from the input claim set to the output claim set.
Only the claims in the output claim set are passed on.
The important keyword here is the ‘issue’ keyword:
c:[Type == "http://schemas.microsoft.com/ws/2008/06/identity/claims/windowsaccountname"]
=> issue(claim = c);
This will copy the claim to the output claim set.
It is also possible to add claims to the input claim set that can be used in later rules. To do that we need to use the ‘add’ keyword instead:
c:[Type == "http://schemas.microsoft.com/ws/2008/06/identity/claims/windowsaccountname"]
=> add(claim = c);
Now this claim is accessible in later rules but will not be passed on.
Lesson 4 - Multiple instances of the same claim type can be returned
If you specify a claim rule with a condition, all claims matching that condition will be returned.
For example if we take a look at the following rule:
This will return a groupsid claim for every group the user is part of in Active Directory.
Remark: Unaware of this behavior I got into trouble when I tried to read a claim value in my application using the following code:
It sometimes returned a different value and I couldn’t understand why until I checked the full list of claims returned and noticed the same claim type being returned multiple times.
Lesson 5 - There is no if-then-else condition but we can ‘fake’ it
There is no if-then-else construct available out-of-the box, a rule can has a condition, an operator and an issuance statement and that’s it.
The “if statement” condition:
c:[Type ==”http://schemas.microsoft.com/ws/2008/06/identity/claims/windowsaccountname”]
The operator:
=>
The issuance statement:
issue(claim = c);
However you can ‘fake’ an if-then-else condition by first issuing an input claim using a NOT EXISTS check:
Remark: the exact value of the claim doesn’t matter.
And then use this input claim in a second claim rule:
Bonus lesson
As a bonus lesson, I would like to point to the great blogpost by Rory Braybrook who shared a list of tips & tricks that can help you in defining your ADFS claim rules. A must read!
More information
ADFS Claim rules (bartwullems.blogspot.com)
Tips and tricks with ADFS claims rules | by Rory Braybrook | The new control plane | Medium
AD FS 2.0 Claims Rule Language Primer - Microsoft Community Hub