The Rules of AD FS Claims Rules

Many people think of AD FS as merely a federated authentication service. And with a name like Active Directory Federation Services, it’s easy to see why. However, it also has the capacity to make authorisation decisions within its Claims Engine. This may be most familiar as the Office 365 Client Access Policies, but those policies are basically just a flavour of AD FS Issuance Authorisation Rules. An AD FS Issuance Authorisation rule provides a gate at AD FS, where permissions can be granted or denied to authentic users, per-Relying Party, before giving the user Claims for the requested Relying Party. In most cases we will think about these rules as coarse controls, to block a wide category of requests, such as those originating from outside the network, for members of a group, or for any combination of request-based, device-based and user attribute-based Claims. We can even create authorisation rules based on the user’s Identity Provider, or from additional factors of authentication. We will typically still implement most of our authorisation logic within the Relying Parties we are authenticating to, but in some cases it’s very useful to control access at this intermediary tier – especially if a large class of users, devices or networks should be treated as higher risk.

These concepts are not new, and the TechNet documentation I reference here dates back to the earliest wave of AD FS 2.0 RTW content:

• The Role of Claims
  
• The Role of the Claims Pipeline
  
• The Role of the Claims Engine
  
• When to Use an Authorization Claim Rule

Ultimately, I think these articles do answer the question of how to create an AD FS Issuance Authorisation rule, but I can’t point very clearly to the place on these pages that spells it out, and I do think there is a lot of confusing information about this in other places which may lead people astray. Namely, there is a lot of information that only concerns itself with the default Active Directory Claims Provider Rules and the Claims that come from request headers. Also, some of the most referenced AD FS + SharePoint content seems to have been written without authorisation rules in-mind. I want to try to clear some of that up in this post.

UPDATE 24/2/2015
I’ve added a fairly significant update regarding the new MFA stage in the pipeline half-way down this post.

The inbound Claims set for Authorisation rule processing

Most articles about Authorisation Rules are focused on request header information or Group SID – probably because these are the most common Client Access Policy scenarios. As it happens, Authorisation rules for these scenarios can be successfully created without worrying about the Claims Provider configuration. However, if you want to make an authorisation decision on some other LDAP data that isn’t in the default Claims Rules for the Active Directory Claims Provider, then a Send LDAP Attributes as Claims rule should be added to the Claims Provider rule set in order to issue that Claim before authorisation processing takes place. I don’t think this is particularly well understood based on the way that this is typically explained, but if you refer back to the TechNet links above, you will see that Authorisation rule processing acts on the output of the Claims Provider rule set, before Issuance rule processing takes place. This means that a Send LDAP Attributes as Claims rule or a transformation rule in the Issuance Transformation rule set will not be used during Issuance Authorisation rule processing.

Issuance rules then determine which Claims will be passed on to a Relying Party. Those rules can be constructed from Add or Issue statements, where Add rules are only used inside AD FS for further processing, but the Issue rules will be used both inside AD FS for further processing and then issued to the Relying Party. I find the current documentation about all of this pretty confusing, so I’m putting forward an alternative way of thinking about this, which hopefully simplifies without oversimplifying:

1. Acceptance rule processing: The Claims Provider rule set is processed for the user that’s signing on. The resultant Claims are passed on for Authorisation. ->
   
2. Authorisation rule processing: The resultant set of Claims Provider rules are processed for permit and deny rules. These are processed sequentially. This includes both Issuance Authorisation rules and Delegation Authorisation rules, although the latter will be less common. If the signed-on user is permitted to access the Relying Party, then (and only then) the Issuance Transformation rules will execute. ->
   
3. Issuance rule processing: After authorisation rules have processed and a user has a “permit” Claim, the original Acceptance Rules are processed for issuance. “Issuance” in this context means the Claims that will be returned to the user for access to the Relying Party. AD FS already knows this user is permitted (from step #2), so this step is all about the data that will be sent out. This is where I will pass through my Claims Provider Claims, issue new LDAP queries or transform incoming Claims. This set of Claims should be the minimum set of Claims necessary to make authorisation decisions in the Relying Party – by which I mean we don’t want to disclose unnecessary data to this party.
   

When I read the TechNet content, I feel like some of the pieces of this puzzle are missing or unclear. The most succinct statement I can find about this makes sense in retrospect, but I really didn’t get the specific significance for Authorisation rules at a glance:

Claim rules process incoming claims either directly from a claims provider (such as Active Directory or another Federation Service) or from the output of the acceptance transform rules on a claims provider trust.

I also think that the AD FS management console is structured poorly here, since the Authorisation and Delegation Claims rule tabs are to the right of the Transform rules. This is unintuitive:

UPDATE 24/2/2015
Having spent a bit more time with AD FS Conditional Access Policies since originally writing this, I need to clarify that there is a new MFA stage in the Claims Pipeline in AD FS 2012 R2. Those rules are “Additional Authentication Rules”, which process in between Acceptance Rule Processing and Authorisation Rule Processing. The Additional Authentication Rules stage has its own logic like the Acceptance Rule stage before it. After MFA conditions have been satisfied those new MFA Claims will be added to the set that can be used for Authorisation processing. This all makes sense because we want to make sure users are authentic and that they can meet all conditions before spending compute on further Claims processing.

In order to invoke this stage of processing you can use the AD FS Management Console for simple rules evaluation, Set-AdfsAdditionalAuthenticationRule for complex Global MFA Policies or Set-AdfsRelyingPartyTrust –AdditionalAuthenticationRules for Relying-Party-specific “custom” authentication rules. This has all been explained with very helpful scenario-based examples by Ramiro Calderon and Mylo.

The only facet of this that took a while for me to grasp is that Issuance Authorisation Rules may be much simpler than you would expect once the Additional Authentication Rules have been factored in. For instance, in Mylo’s first example we can enforce Device Authentication on registered devices for users outside the network, and issue an MFA challenge for all other external users. The rule itself is clear enough but what surprised me is that the Issuance Authorisation Rules can be dialled right back to “Permit All Users” (in its simplest form). This is pretty elegant. This diagram from Ramiro Calderon’s post is exceptionally helpful for wrapping your head around the entire flow:

Early SharePoint + AD FS content

On a totally different vector, some of the most relevant early SharePoint 2010 + AD FS content suggests that the “Send LDAP Attributes as Claims” rules should be created at the Relying Party. Or rather, there are no suggestions that it might be preferable to configure these rules at the Claims Provider Trust, and pass them through at the Relying Party. I know we relied heavily on Steve Peschka‘s and Travis Nielsen‘s content in the early days of the SharePoint 2010 lifecycle, so I don’t intend to disparage this in any way, but anyone who followed this guidance to the letter will find that Authorisation rules will not process correctly for the “Send LDAP Attributes as Claims” rules. By configuring these rules within the Issuance Transformation process, the queried LDAP attributes will only be sent out to the Relying Party. They will not be available for Authorisation rule processing.

To illustrate, if I want to make an Authorisation rule based on Group SID values, it will work, since this is passed through from the default Claims Rules for the Active Directory Claims Provider, but if I want to make an Authorisation decision on E-mail Address, department or extensionAttribute13, it won’t work unless I add Send LDAP Attributes as Claims rules for these attributes to the Claims Provider rule set.

This is not to say that it will always be the right decision to create all of my Send LDAP Attributes as Claims rules on the Claims Provider Trust. If I have five Relying Parties with different outbound Claim Types, I would be adding a lot of unnecessary LDAP query weight at sign-on. But if I have a common set of Claim Types across my Relying Parties (as is probable in the SharePoint world), then it will probably make sense to move my Send LDAP Attributes as Claims rules over to the Claims Provider rule set, which has the added benefit of making these claims available for authorisation decisions. Before porting these rules to the Claims Provider rule set, I would update the Relying Parties to pass through these Claims, then delete the original Send LDAP Attributes as Claims rules after everything has been ported.

One point of reference that’s informative to me is the Device Registration Service Claims rules in AD FS 2012 R2. This is the one Relying Party that ships with AD FS, and it is configured to pass through Claims from the Claims Provider, rather than issuing a separate query. Based on this reference, I think that passing through should be the default approach, unless there are benefits to separating out.

Screenshot of DRS RP Trust

Further confusion about Conditional Access Policies

To add a bit more mud to the water, if we fast-forward the AD FS 2012 R2 TechNet article on Manage Risk with Conditional Access Control (which includes Authorisation Rules), there is a long list of, “the claim types available in AD FS in Windows Server® 2012 R2 to be used for implementing conditional access control”. What I find confusing is that we can always add Claim Descriptions beyond those listed here. These are just the default Claim Descriptions that ship with AD FS. We aren’t limited to making authorisation rules on this set. To make things a bit more confusing, if we look at page 34 of this Tech-Ed presentation, “Claims available for conditional access control”, the list is even smaller. In short, this is a red herring, but a confusing one if you’re trying to figure out why authorisation rules aren’t working.

Update 24/2/2015
Perhaps this list is intended to describe the Claims available for “Additional Authentication Rule” processing, as described by Ramiro Calderon in his post, but it certainly isn’t clear if that’s the case. I will try to answer this question in due course.

When to pass through and when to use a Send LDAP Attributes as Claims rule

To sum all of this up, other than the TechNet articles at the top of this post, nearly all of the good blogs on the syntactical difficulties of the AD FS Claims Rules Language focus on the construction of Authorisation Rules and Issuance Transformation with Add and Issue statements. I’m not finding any definitive documentation that goes in to detail about the Active Directory Claims Provider. I think we can assume rule #9 comes from a certificate when certificate authentication is used, but this leaves an open question about where this Claims Provider “passes through” the other nine of its ten default attributes from.

Ten default Active Directory Claim Provider Rules

I think we have to assume these data don’t come from an LDAP query, or else these would be Send LDAP Attributes as Claims rules. Based on the specific attributes in those ten rules, I think it’s safe to assume that these Claims are extracted at authentication, without issuing an LDAP query specifically – but this is just a hunch. My colleague Ben Athawes suggested comparing this to a SharePoint Web Application in Windows Claims mode. On one of my Web Application with NTLM authentication, the SharePoint STS extracts these Claims from Windows Authentication:

• http://schemas.microsoft.com/ws/2008/06/identity/claims/primarysid
  
• http://schemas.microsoft.com/ws/2008/06/identity/claims/primarygroupsid
  
• http://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn
  
• http://schemas.microsoft.com/sharepoint/2009/08/claims/userlogonname
  
• http://schemas.microsoft.com/ws/2008/06/identity/claims/groupsid
  

I think this is a strong clue. It would be good to know more concretely whether any other Claims can be passed through here, or if all other Active Directory Claims need to be constructed as Send LDAP Attributes as Claims rules. For now I am assuming that they must be, as the attributes I’ve tested only worked as Send LDAP Attributes as Claims rules. If anyone else has more definitive information about this I would welcome it. At any rate, I hope this helps clear up how to construct Authorisation rules, as I’ve incurred some cranial bruising along this path.