Understanding AD FS claim rules in combination with Azure AD

Azure AD Connect helps administrators create their own AD FS Farm and to connect it to Azure AD. But when you are using Azure AD Connect in combination with AD FS to authenticate users or administrators against Azure AD, you will find it very difficult to understand the claim rules set by Azure AD Connect. For AD FS “newbies,” claim rules in general are hard to understand. And there may be none harder to grasp for beginners than the so-called custom claim rules. Let’s dive into the automatically generated claim rules so you can get an overview on the AD FS architecture. In this tutorial, you’ll learn how claim rules work and what they are doing when an identity is authenticating against Azure AD.


Take a look at the following architecture:

Azure AD Connect authentication and synchronisation workflow


This architecture shows you the authentication and synchronization workflow and involved components, which will be set up by the Azure AD Connect setup (refer to the “On Premise” rectangle). This describes the different parts in Azure, which are involved or can be involved, for example Web-Apps. In this example, we are looking at a single domain forest that has the same DNS domain registered in Azure.


The registered DNS domain in Azure is federated and, therefore, the claims or identity provider is the local Active Directory and not Azure AD. This means once a user signs into the Azure Portal or a Web-App hosted on Azure configured to authenticate with Azure AD, they will be redirected to the AD FS Farm. When the user types the username in the dedicated text-box and leaves the password text-box, the so-called Home Realm Discovery takes place, as you can see below:

Microsoft Azure Home Realm Discovery step 1Microsoft Azure Home Realm Discovery step 2

Microsoft Azure Home Realm Discovery step 3 - AD FS propassing

Azure is searching using the domain suffix “propassig.com” for the right identity provider and ends up at the AD FS Farm. If you want to know more about the different architecture regarding identity, you can find additional resources on Microsoft Technet.

Let’s start building and bring life to this architecture!

AD FS Farm

Using the Azure AD Connect installer, it is easy to create a simple AD FS-Farm as shown below. On Channel 9 you can find a very good tutorial presented by @ArturoLucatero on setting up an AD FS Farm with Azure AD Connect.

After following the tutorial you will have more or less the same setup that is shown in the architecture diagram. The setup automatically creates a Relying Party trust to Azure AD and also defines claim rules to that Relying Party within AD FS.

Nice to know AD FS terms:

  • Relying Party is pretty much nothing more than an application (in our case Azure AD) that you want to send claims to authenticate users or administrators.
  • claim provider is usually the Active Directory that stores the attributes needed for authentication. In some cases it can also be another Identity provider, for example an SAML 2.0 Identity provider, which sends an SAML response to AD FS.
  • claim, however, is an attribute that can identify an identity. For example, the Active Directory attribute User-Principal-Name (UPN).

Claim rules overview

Inside AD FS claim rules act on the claims provider side and on the relying party side.

Claims Provider sideRelying Party side

In general there are five types of claim rules:

  • Send LDAP Attributes as claims: These kinds of rules simply issue LDAP attributes such as UPN or mail. These will be added to the claim response sent to the relying party.
  • Send Group Membership as a claim: Almost the same as the first rule type, but it issues AD group memberships to the response sent to the relying party.
  • Transform an incoming claim: This rule transforms already set claims. For example, the Claim response from the claims provider (AD) has the claim E-Mail Address issued, but the relying party is expecting the value to be in the claim Name ID. Then I can use this rule to pass the values from one claim to another.
  • Pass through or filter an incoming claim: This rule is able to pass through claims sent by the claims provider or filter/edit values, for example change the domain suffix.
  • Custom Claim rules: The most complex rules are custom rules, because they can combine all the previous rules and work with regular expressions.

Default claims provider claim rules

Let’s have a look at the default claim rules for the claims provider: 

Claim Rules for Active Directory

As you can see, it’s pretty easy to understand. While logging into the AD FS webpage with your passwords, all these claims are issued using your login credentials.

Default relying party claim rules

On the other hand, the relying party rule set is much more complex:

Relying party claim rules

First claims provider claim rule

Notice that all the rules are custom rules. Let us have a look at the first rule:

First claims provider claim rule

Let’s start at the top:

c:[Type == "http://schemas.microsoft.com/ws/2008/06/identity/claims/windowsaccountname"]

This we are expecting an incoming claim of the type windowsaccountname which is basically the following value: DOMAIN\Username.

The second part:

issue(store = "Active Directory", types = ("http://schemas.xmlsoap.org/claims/UPN", "http://schemas.microsoft.com/LiveID/Federation/2008/05/ImmutableID")

means, using the claim defined in the first paragraph (windowsaccountname) we want to issue two new claims (UPN and ImmutableID) by using Active Directory as the attribute store. ImmutableID is the attribute which has been chosen to be the source anchor in the Azure AD Connect setup earlier. This ID is used as a unique identifier to authenticate an identity within the Azure AD tenant.

The third part of the rule is the query we use to browse the AD and find our desired values. I highlighted the two parameters which will be used in the query:

 , query = "samAccountName={0};userPrincipalName,objectGUID;{1}", param = regexreplace(c.Value, "(?<domain>[^\\]+)\\(?<user>.+)", "${user}"), param = c.Value);

I think it is best explained using SQL. The same query would look something like the following in SQL:

SELECT userPrincipalName,objectGUID FROM 'Active Directoy' WHERE samAccountName='Username';

The values we get will then be saved in the claims UPN and ImmutableID. 

Second claims provider claim rule

The following rule is the last one we need to authenticate users. All the other rules defined in the set are used to authenticate/identify Windows 10 computers that are Azure AD joined. See Azure AD Join on Windows 10 devices for more information.

Second claims provider claim rule

In this rule we simply issue the claim called nameidentifier and set the value of this claim to be the same as the value that is stored in the ImmutableID claim. Additionally, we add another property to this claim. This is done by using the keyword “Properties.” This sets the format of the claim to be “urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified,” which Azure AD expects.

By the way: You can also define you own claimtypes like “http://temp.org/DomainName” to save values/attribute into it!

There we have it! All the claims we issued (UPN, ImmutableID, nameidentifier) will be sent to Azure AD. Azure AD checks if the identity is allowed to browse the Azure Portal and authorize the identity if configured. AD FS uses the SAML token format to send the response to Azure AD, which can be seen when tracing the flow using fiddler.

You are now ready to tackle custom claim rules in AD FS in combination with Azure AD / Connect.

About The Author

1 thought on “Understanding AD FS claim rules in combination with Azure AD”

  1. Hi Lennart

    Good demonstration on how to pass a new claim to Azure AD while sign-in. But can you tell me how these new claims can be consume by Azure AD, like in conditional access ?

Leave a Comment

Your email address will not be published. Required fields are marked *

This site is protected by reCAPTCHA and the Google Privacy Policy and Terms of Service apply.

Scroll to Top