Skip to main content

ADFS claim rules - Lessons learned

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

Popular posts from this blog

Azure DevOps/ GitHub emoji

I’m really bad at remembering emoji’s. So here is cheat sheet with all emoji’s that can be used in tools that support the github emoji markdown markup: All credits go to rcaviers who created this list.

Kubernetes–Limit your environmental impact

Reducing the carbon footprint and CO2 emission of our (cloud) workloads, is a responsibility of all of us. If you are running a Kubernetes cluster, have a look at Kube-Green . kube-green is a simple Kubernetes operator that automatically shuts down (some of) your pods when you don't need them. A single pod produces about 11 Kg CO2eq per year( here the calculation). Reason enough to give it a try! Installing kube-green in your cluster The easiest way to install the operator in your cluster is through kubectl. We first need to install a cert-manager: kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.14.5/cert-manager.yaml Remark: Wait a minute before you continue as it can take some time before the cert-manager is up & running inside your cluster. Now we can install the kube-green operator: kubectl apply -f https://github.com/kube-green/kube-green/releases/latest/download/kube-green.yaml Now in the namespace where we want t

DevToys–A swiss army knife for developers

As a developer there are a lot of small tasks you need to do as part of your coding, debugging and testing activities.  DevToys is an offline windows app that tries to help you with these tasks. Instead of using different websites you get a fully offline experience offering help for a large list of tasks. Many tools are available. Here is the current list: Converters JSON <> YAML Timestamp Number Base Cron Parser Encoders / Decoders HTML URL Base64 Text & Image GZip JWT Decoder Formatters JSON SQL XML Generators Hash (MD5, SHA1, SHA256, SHA512) UUID 1 and 4 Lorem Ipsum Checksum Text Escape / Unescape Inspector & Case Converter Regex Tester Text Comparer XML Validator Markdown Preview Graphic Color B