When to Use a Send Group Membership as a Claim Rule

 

Applies To: Windows Server 2012

You can use this rule in Active Directory Federation Services (AD FS) when you want to issue a new outgoing claim value for only those users who are members of a specified Activ  Directory security group. When you use this rule, you issue a single claim for only the group that you specify and that matches the rule logic, as described in the following table.

Rule option

Rule logic

Outgoing claim value

If a user’s group membership is equal to the specified group and outgoing claim type equals specified claim type, then replace the existing group name value with the specified outgoing claim value and issue the claim.

The following sections provide a basic introduction to claim rules. They also provide details about when to use the Send Group Membership as a Claim 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.

Outgoing claim value

Using the Send Group Membership as a Claim rule template, you can issue a claim that is contingent on whether a user is a member of a group that you specify.

In other words, this rule template issues a claim only when the user has the group security ID (SID) that matches the Active Directory group that the administrator specifies. All users who authenticate against Active Directory Domain Services (AD DS) will have incoming group SID claims for each group that they belong to. By default, the acceptance transform rules in the Active Directory Claims Provider Trust pass through these group SID claims. Using these group SIDs as a basis for issuing claims is much faster than looking up the user’s groups in AD DS.

When you use this rule, only a single claim is sent, based on the Active Directory group that you select. For example, you can use this rule template to create a rule that will send a group claim with a value of "Admin" if the user is a member of the Domain Admins security group.

Configuring this rule on a claims provider trust

Administrators should use this rule type in the acceptance transform rules of a claims provider trust only when group SIDs are being received from the claims provider, which is very uncommon for any claims providers except Active Directory or AD DS.

How to create this rule

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

  • Specify a claim rule name

  • Select a user’s group using object picker

  • Select an outgoing claim type

  • Select an outgoing name ID format (which is available only when Name ID is chosen from the outgoing claim type field)

  • Specify an outgoing claim value

For more information about how to create this rule, see Create a Rule to Send Group Membership as a Claim1.

Using the claim rule language

If you want to issue claims based on an incoming SID other than a group SID, use the Transform an Incoming Claim rule template. If the administrator wants to retrieve the names for all the groups that the user is a member of, use the Send LDAP Attributes as Claims rule template instead with the tokenGroups attribute.

Example: How to issue group claims based on the user’s group membership

The following rule issues group claims for a user based on an incoming group SID:

c:[Type == "https://schemas.microsoft.com/ws/2008/06/identity/claims/groupsid", Value == "S-1-5-21-397933417-626991126-188441444-512", Issuer == "AD AUTHORITY"]
=> issue(Type = "https://schemas.xmlsoap.org/claims/Group", Value = "administrators", Issuer = c.Issuer, OriginalIssuer = c.OriginalIssuer, ValueType = c.ValueType);

Additional references

Create a Rule to Send LDAP Attributes as Claims1