Claim Rules

Claim rules are what actually issuing claims, regardless if it's from Active Directory or a custom Attribute Store like the Attribute Store for FIM. Issuing claims from Active Directory has it's own GUI but that can' be used for issuing claims from a custom attribute store therefore you'll have to author these rules by hand and these rules are called Custom Rules.

There's a good guide on how the claim rules works can be found at TechNet: http://technet.microsoft.com/en-us/library/dd807118(WS.10).aspx
It might look advanced to start with but it's actually pretty simple...

Add Claims Rule
So the attribute store is configured and hopefully you have tested it by using the Test Client but you must author claim rules for your Relying Party Trusts or Claims Provider Trusts in order for it to start issuing claims and here's a couple of examples how this is done for the Attribute Store for FIM. First of all we anticipate you already have a Relying Party Trusts set up and that you wish to start issuing claims from FIM. The Test Client is very useful for testing the query parts of your claim rules against FIM when you are creating them.

Walkhrough of the building blocks of a simple Custom Rule
Lets have a look how a simple rule is built up but first we make sure to issue "SAM-Account-Name" from AD to the http://schemas.microsoft.com/ws/2008/06/identity/claims/windowsaccountname" claim in our first rule and here we can use the LDAP claim rule GUI.

Lets start with how we add an LDAP claim rule:
  1. Select Trust RelationShips/Relying Party Trusts in the tree
  2. Click Add Claim Rules... in the Actions list
  3. Click Add Rule...
  4. Configure Claim Rule
    1. Select Send LDAP Attributes as Claims and click Next
    2. Enter rule name for example "AD LDAP Attributes"
    3. Add a mapping from the LDAP attribute "SAM-Account-Name" to "Windows account name"
    4. Click Finish

Your rule is ready to use and it should look like this before you hit finish:
AD Claim rule.png

Lets continue with how we add a Custom claim rule:
  1. Select Trust RelationShips/Relying Party Trusts in the tree
  2. Click Add Claim Rules... in the Actions list
  3. Click Add Rule...
  4. Configure Claim Rule
    1. Select Send Claims Using a Custom Rule and click Next
    2. Enter rule name
    3. In the custom rule, use the text from one of the examples below or something like it.
    4. Click finish

This rule takes a Windows account name (sAMAccountName in AD) issued by a previous LDAP rule and looks up the owner of it in FIM and issues it's FIM ObjectID (ResourceID), DisplayName and EmployeeID.
c:[Type == "http://schemas.microsoft.com/ws/2008/06/identity/claims/windowsaccountname"]
=> issue(
      store = "FIM",
      types = ("http://schemas.xmlsoap.org/ws/2005/05/identity/claims/privatepersonalidentifier", 
                   "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name", 
                   "http://fimattributestore.codeplex.com/FIM_EmployeeID"),
      query = "/Person[AccountName='{0}'];ObjectID, DisplayName, EmployeeID",
      param = c.Value);


This part of the claim rule is a condition that makes sure there's a claim of the type http://schemas.microsoft.com/ws/2008/06/identity/claims/windowsaccountname available with a Windows account name claim issued by a previous claim rule and if it is it stores it in the variable c.
c:[Type == "http://schemas.microsoft.com/ws/2008/06/identity/claims/windowsaccountname"]


=> issue(... tells ADFS it should issue claims
c:[Type == "http://schemas.microsoft.com/ws/2008/06/identity/claims/windowsaccountname"]
=> issue(...


store = "FIM"... tells ADFS it should get claims to issue from an attribute provider named "FIM". In this case "FIM" is the name of the FIM Attribute store we gave it when we configured it in ADFS.
c:[Type == "http://schemas.microsoft.com/ws/2008/06/identity/claims/windowsaccountname"]
=> issue(
      store = "FIM"...


types = ... tells ADFS what type the claims issued are going to have. The first two types are coming with ADFS 2.0 out of the box but the last one is a custom type that we have created under Service/Claim Descriptions in ADFS 2.0 Management console.
c:[Type == "http://schemas.microsoft.com/ws/2008/06/identity/claims/windowsaccountname"]
=> issue(
      store = "FIM",
      types = ("http://schemas.xmlsoap.org/ws/2005/05/identity/claims/privatepersonalidentifier", 
                   "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name", 
                   "http://fimattributestore.codeplex.com/FIM_EmployeeID")...


query = ... is where we define the query against FIM. The query is made up of two parts, first an XPath expression /Person[AccountName='{0}'] that is understood by FIM and then a comma separated list of attributes ObjectID, DisplayName, EmployeeID we wish to retrieve from FIM, these two parts are surrounded by quotes and separated with a semi-colon. If you wish to know more on how to write XPath queries against FIM, check out this article: http://msdn.microsoft.com/en-us/library/ee652287.aspx
c:[Type == "http://schemas.microsoft.com/ws/2008/06/identity/claims/windowsaccountname"]
=> issue(
      store = "FIM",
      types = ("http://schemas.xmlsoap.org/ws/2005/05/identity/claims/privatepersonalidentifier", 
                   "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name", 
                   "http://fimattributestore.codeplex.com/FIM_EmployeeID"),
      query = "/Person[AccountName='{0}'];ObjectID, DisplayName, EmployeeID")...


param = ... enables us to use the incoming claim value as a parameter in our query to FIM, and the value will replace the {0} of the query part by ADFS 2.0.
c:[Type == "http://schemas.microsoft.com/ws/2008/06/identity/claims/windowsaccountname"]
=> issue(
      store = "FIM",
      types = ("http://schemas.xmlsoap.org/ws/2005/05/identity/claims/privatepersonalidentifier", 
                   "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name", 
                   "http://fimattributestore.codeplex.com/FIM_EmployeeID"),
      query = "/Person[AccountName='{0}'];ObjectID, DisplayName, EmployeeID",
      param = c.Value);

Our claim rule is complete...
If the opening condition evaluates to true and the "FIM" attribute store is able to fetch the values specified in the query, ADFS 2.0 will issue claims of the types specified in types from the three values. If any of the value would be a null value, ADFS won't issue that specific value.

Retrieve a list of groups for a person and issue it as claims
This custom claim rule works pretty much as the one in the walkthrought above except it requires and takes a http://schemas.xmlsoap.org/ws/2005/05/identity/claims/privatepersonalidentifier claim that in this example is the FIM ObjectID/ResourceID we queried FIM for in the walkthrought above. It then queries FIM for the groups the person that owns the ObjectID is a member of and issues the DisplayName of the groups returned as one or more http://schemas.xmlsoap.org/claims/Group claims. This query could of course be changed into issuing DisplayName of Sets or if you have a Role as a resource or a multi-value attribute in FIM.
c:[Type == "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/privatepersonalidentifier"]
=> issue(
      store = "FIM", 
      types = ("http://schemas.xmlsoap.org/claims/Group"), 
      query = "/Group[ComputedMember = '{0}']; DisplayName", 
      param = c.Value);


Issuing a single-valued attribute together with a multi-valued attribute as claims
This rule might not very useful but I've added it to show that claims can be issued from FIM without having a condition/param, this means if that you add this rule it will issue claims regardless who claims are issued for. I also want to show that single-valued attribute together with multi-valued attributes can be issued together and in this case it takes a single-valued DisplayName attribute and a multi-valued UsageKeyword attribute and issues them as custom claim types.
=> issue(
      store = "FIM", 
      types = ("http://fimattributestore.codeplex.com/FIM_SearchScope_DisplayName",
                   "http://fimattributestore.codeplex.com/FIM_SearchScope_UsageKeyWord"), 
      query = "/SearchScopeConfiguration[ObjectID='2d66d066-47ed-4736-bce1-b840eb7156d4']; DisplayName, UsageKeyword");

When running this query against FIM using the attribute store it will return a table that looks like this:
DisplayName UsageKeyword
All Users BasicUI
null customized
null Global
null Person
null MailEnabledSecurity
null Security
null Distribution

ADFS 2.0 will not issue null values so these are the claims that will be issued:
http://fimattributestore.codeplex.com/FIM_SearchScope_DisplayName = All Users
http://fimattributestore.codeplex.com/FIM_SearchScope_UsageKeyWord = BasicUI
http://fimattributestore.codeplex.com/FIM_SearchScope_UsageKeyWord = customized
http://fimattributestore.codeplex.com/FIM_SearchScope_UsageKeyWord = Global
http://fimattributestore.codeplex.com/FIM_SearchScope_UsageKeyWord = Person
http://fimattributestore.codeplex.com/FIM_SearchScope_UsageKeyWord = MailEnabledSecurity
http://fimattributestore.codeplex.com/FIM_SearchScope_UsageKeyWord = Security
http://fimattributestore.codeplex.com/FIM_SearchScope_UsageKeyWord = Distribution

Last edited Dec 8, 2010 at 5:48 AM by HenrikNilsson, version 4

Comments

No comments yet.