When to Use a Send LDAP Attributes as Claims Rule

Applies To: Windows Server 2012

You can use this rule in Active Directory Federation Services (AD FS) when you want to issue outgoing claims that contain actual Lightweight Directory Access Protocol (LDAP) attribute values that exist in an attribute store and then associate a claim type with each of the LDAP attributes. For more information about attribute stores, see The Role of Attribute Stores.

When you use this rule, you issue a claim for each LDAP attribute that you specify and that matches the rule logic, as described in the following table.

The following sections provide a basic introduction to claim rules. They also provide details about when to use the Send LDAP Attributes as Claims rule.

About claim rules

A claim rule represents an instance of business logic that will take an incoming claim, apply a condition to it (if x then y) and produce an outgoing claim based on the condition parameters. The following list outlines important tips that you should know about claim rules before you read further in this topic:

• In the AD FS Management snap-in, claim rules can only be created using claim rule templates

• 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.

• Claim rules are processed by the claims issuance engine in chronological order within a given rule set. By setting precedence on rules, you can further refine or filter claims that are generated by previous rules within a given rule set.

• Claim rule templates will always require you to specify an incoming claim type. However, you can process multiple claim values with the same claim type using a single rule.

For more detailed information about claim rules and claim rule sets, see The Role of Claim Rules. For more information about how rules are processed, see The Role of the Claims Engine. For more information how claim rule sets are processed, see The Role of the Claims Pipeline.

Mapping of LDAP attributes to outgoing claim types

When you use the Send LDAP Attributes as Claims rule template, you can select attributes from an LDAP attribute store, such as Active Directory or Active Directory Domain Services (AD DS) to send their values as claims to the relying party. This essentially maps specific LDAP attributes from an attribute store that you define to a set of outgoing claims that can be used for authorization.

By using this template, you can add multiple attributes, which will be sent as multiple claims, from a single rule. For example, you can use this rule template to create a rule that will look up attribute values for authenticated users from the company and department Active Directory attributes and then send these values as two different outgoing claims.

You can also use this rule to send all the user’s group memberships. If you want to send only individual group memberships, use the Send Group Membership as a Claim rule template. For more information, see When to Use a Send Group Membership as a Claim Rule.

How to create this rule

You can create this rule by using either the claim rule language or by using the Send LDAP Attributes as Claims rule template in the AD FS Management snap-in. This rule template provides the following configuration options:

• Specify a claim rule name

• Select an attribute store from which to extract LDAP attributes

• Mapping of LDAP attributes to outgoing claim types

For more information about how to create this rule, see Create a Rule to Send LDAP Attributes as Claims1.

Using the claim rule language

If the query to Active Directory, AD DS, or Active Directory Lightweight Directory Services (AD LDS) must compare against an LDAP attribute other than samAccountname, you must use a custom rule instead. If there is no Windows Account Name claim in the input set, you must also use a custom rule to specify the claim to use for querying AD DS or AD LDS.

The following examples are provided to help you understand some of the various ways you can construct a custom rule using the claim rule language to query and extract data in an attribute store.

Example: How to query an AD LDS attribute store and return a specified value

Parameters must be separated by a semicolon. The first parameter is the LDAP filter. Subsequent parameters are the attributes to return on any matching objects.

The following example shows how to look up a user by the sAMAccountName attribute and issue an e-mail address claim, using the value of the user’s mail attribute:

c:[Type == "https://schemas.microsoft.com/ws/2008/06/identity/claims/windowsaccountname", Issuer == "AD AUTHORITY"]
=> issue(store = "AD LDS", types = ("https://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress"), query = "sAMAccountName={0};mail", param = regexreplace(c.Value, "(?<domain>[^\\]+)\\(?<user>.+)", "${user}"));

The following example shows how to look up a user by the mail attribute and issue Title and Display Name claims, using the values of the user’s title and displayname attributes:

c:[Type == " https://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress ", Issuer == "AD AUTHORITY"]
=> issue(store = "AD LDS ", types = ("https://schemas.xmlsoap.org/ws/2005/05/identity/claims/title","https://schemas.xmlsoap.org/ws/2005/05/identity/claims/displayname"), query = "mail={0};title;displayname", param = c.Value);

The following example shows how to look up a user by mail and title and then issue a Display Name claim using the user’s displayname attribute:

c1:[Type == " https://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress"] && c2:[Type == "https://schemas.xmlsoap.org/ws/2005/05/identity/claims/title"]
=> issue(store = "AD LDS ", types = ("https://schemas.xmlsoap.org/ws/2005/05/identity/claims/displayname"), query = "(&(mail={0})(title={1}));displayname", param = c1.Value, param = c2.Value);

Example: How to query an Active Directory attribute store and return a specified value

The Active Directory query must include the user’s name (with the domain name) as the final parameter so that the Active Directory attribute store can query the correct domain. Otherwise, the same syntax is supported.

The following example shows how to look up a user by the sAMAccountName attribute in his or her domain and then return the mail attribute:

c:[Type == "https://schemas.microsoft.com/ws/2008/06/identity/claims/windowsaccountname", Issuer == "AD AUTHORITY"]
=> issue(store = "Active Directory", types = ("https://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress"), query = "sAMAccountName={0};mail;{1}", param = regexreplace(c.Value, "(?<domain>[^\\]+)\\(?<user>.+)", "${user}"), param = c.Value);

Example: How to query an Active Directory attribute store based on the value of an incoming claim

c:[Type == "https://test/name"]

   => issue(store = "Enterprise AD Attribute Store",

         types = ("https://test/email"),

         query = ";mail;{0}",

         param = c.Value)

The previous query is made up of the following three parts:

• The LDAP filter—You specify this part of the query to retrieve the objects for which you want to query the attributes. For general information about valid LDAP queries, see RFC 2254. When you are querying an Active Directory attribute store and you do not specify an LDAP filter, the samAccountName={0} query is assumed and the Active Directory attribute store expects a parameter that can feed the value for {0}. Otherwise, the query will result in an error. For an LDAP attribute store other than Active Directory, you cannot omit the LDAP filter part of the query or the query will result in an error.

• Attribute specification—In this second part of the query, you specify the attributes (which are comma-separated if you use multiple attribute values) that you want out of the filtered objects. The number of attributes that you specify must match the number of claim types that you define in the query.

• Active Directory domain—You specify the last part of the query only when the attribute store is Active Directory. (It is not necessary when you query other attribute stores.) This part of the query is used to specify the user account in the form domain\name. The Active Directory attribute store uses the domain part to determine the appropriate domain controller to connect to and run the query and request the attributes.

Example: How to use two custom rules to extract the manager e-mail from an attribute in Active Directory

The following two custom rules, when used together in the order shown below, query Active Directory for the manager attribute of the user account (Rule 1) and then use that attribute to query the user account of the manager for the mail attribute (Rule 2). Finally, the mail attribute is issued as a “ManagerEmail” claim. In summary, Rule 1 queries Active Directory and passes the result of the query to Rule 2, which then extracts the manager e-mail values.

For example, when these rules finish running, a claim is issued that contains the manager’s e-mail address for a user in the corp.fabrikam.com domain.

Rule 1

c:[Type == "https://schemas.microsoft.com/ws/2008/06/identity/claims/windowsaccountname"]
=> add(store = "Active Directory", types = ("https://schemas.xmlsoap.org/claims/ManagerDistinguishedName"), query = "sAMAccountName=
{0};mail,userPrincipalName,extensionAttribute5,manager,department,extensionAttribute2,cn;{1}", param = regexreplace(c.Value, "(?
<domain>[^\\]+)\\(?<user>.+)", "${user}"), param = c.Value);

Rule 2

c:[Type == "https://schemas.microsoft.com/ws/2008/06/identity/claims/windowsaccountname"]
&& c1:[Type == "https://schemas.xmlsoap.org/claims/ManagerDistinguishedName"]
=> issue(store = "Active Directory", types = ("https://schemas.xmlsoap.org/claims/ManagerEmail"), query = "distinguishedName={0};mail;{1}", param = c1.Value, 
param = regexreplace(c1.Value, ".*DC=(?<domain>.+),DC=corp,DC=fabrikam,DC=com", "${domain}\username"));

Additional references

Create a Rule to Send LDAP Attributes as Claims1