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);