AD FS 2.0 Issuance Authorization Rules

I had to create a couple of issuance authorization rules in my last engagement and it took me a little longer than it should have to get the syntax correct so I thought I’d post a couple of examples that might be of interest to others.

Firstly, lets clarify what I’m talking about.  Taken from When to Use an Authorization Claim Rule in the AD FS 2.0 Design Guide:

You can use this rule in Active Directory Federation Services (AD FS) 2.0 when you need to take an incoming claim type and then apply an action that will determine whether a user will be permitted or denied access based on the value that you specify in the rule. When you use this rule, you pass through or transform claims that match the following rule logic, based on either of the options you configure in the rule:

To wrap some further context around this post you define issuance authorization rules on relying party trusts.  These rules are applied early on in the claims pipeline process.  You use issuance authorization rules to determine whether or not a user has access to an relying party application. 

A common issuance authorization rule is the permit access to all users rule template.  If you look at the underlying claim rule language for this template you will see the following:

=> issue(Type = “http://schemas.microsoft.com/authorization/claims/permit”, Value = “true”);

Nice and easy.  Issue a claim of the type http://schemas.microsoft.com/authorization/claims/permit with a value of true. 

It’s worth pointing out here that the value is irrelevant.  The authorisation engine only looks for the type of claim, allowing access if there is a claim with a type of http://schemas.microsoft.com/authorization/claims/permit, and not allowing access if there’s no permit claim type or if there is a claim with a type of  http://schemas.microsoft.com/authorization/claims/deny present.  More information on this here.

The purpose of this post is to share two simple examples.  I just designed an AD FS solution and made use of authorization rules to achieve the requirement of all users in domain-a have access to RP application XYZ.  In this environment there were three domains in the forest.  We only wanted users in one of the domains to access the application.  I achieved this by creating a rule with the Send Claims Using a Custom Rule template and the following rule:

c:[Type == “http://schemas.microsoft.com/ws/2008/06/identity/claims/windowsaccountname”, Value =~ “^(?i)CORP\\.+$”]
=> issue(Type = “http://schemas.microsoft.com/authorization/claims/permit”, Value = “true”);

To explain the rule lets assume we have the following domains in the forest: corp.contoso.com, partner.contoso.com, and emea.corp.contoso.com.  The above claim rule only permits access to a relying party if the Windows account name (http://schemas.microsoft.com/ws/2008/06/identity/claims/windowsaccountname) claim type has a value of CORP\something, e.g. CORP\paulw or CORP\chucn.

Next we had a similar requirement that we achieved with a rule around the value of the UPN claim type.  We wanted partners to be able to access an RP.  Non-employee accounts in the directory had a different UPN suffix to employees and contractors (non-employee accounts are created in partner.contoso.com if the partner organisation doesn’t have federation infrastructure).  In this scenario we decided to permit access to an RP application for all users with a UPN of something@partner.contoso.com.  Here’s an example:

c:[Type == “http://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn”, Value =~ “^(?i).+@partner\.contoso\.com$”]
=> issue(Type = “http://schemas.microsoft.com/authorization/claims/permit”, Value = “true”);

Hopefully this will help someone.  It took me longer than it should have to get the regex right.  Smile

Just in case you need a little more guidance on how to create these rules…

If you’re new to AD FS and have just read the above and are thinking awesome, I really want to use that UPN rule but…I have no idea how to create it here goes…

  1. Open AD FS 2.0 management console, click Relying Party Trusts, click the RP trust that you want to configure and click Edit Claim Rules… in the actions bar.
  2. The Edit Claim Rules for <RP name> dialog opens.  Click the Issuance Authorization Rules tab (the middle tab).  If you’re accessing the RP presently you likely have a single rule called Permit Access to All Users with an issued claims of Permit in the list.  Remove this rule and click Add Rule…
  3. Choose the Send Claims Using a Custom Rule template and click Next.
  4. Supply a name and then paste your syntax into the custom rule input.  Click Finish.

If you consider the following rule:

c:[Type == “http://schemas.xmlsoap.org/ws/2005/05/identity/claims/upn&#8221;, Value =~ “^(?i).+@partner\.contoso\.com$“]
=> issue(Type = “http://schemas.microsoft.com/authorization/claims/permit&#8221;, Value = “true”);

The part that you need to configure is the regex –the contents within the quotes after =~ e.g. ^(?i).+@partner\.contoso\.com$.

Regarding the regex.

  • (?i) makes the pattern case insensitive.
  • ^ means starts with.
  • .+ means anything one or more times.
  • @partner\.contoso\.com is the URL with an escape sequence for the dot (or period).
  • $ means ends with.
About these ads

About Paul Williams

IT consultant working for Microsoft specialising in Identity Management and Directory Services.
This entry was posted in AD FS and tagged , , , , . Bookmark the permalink.

3 Responses to AD FS 2.0 Issuance Authorization Rules

  1. Troy says:

    This is great! Do you know if there is a way to use this to insure 2 attributes match? ie UPN, and email.

  2. Pingback: AD FS 2.0 Issuance Authorization Rules: ensure two attributes match | Yet another identity management blog

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s