When to Use an Authorization Claim Rule
You can use this rule in Active Directory Federation Services (AD FS) 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:
| Rule option | Rule logic |
|---|---|
| Permit all users | If incoming claim type equals any claim type and value equals any value, then issue claim with value equals Permit |
| Permit access to users with this incoming claim | If incoming claim type equals specified claim type and value equals specified claim value, then issue claim with value equals Permit |
| Deny access to users with this incoming claim | If incoming claim type equals specified claim type and value equals specified claim value, then issue claim with value equals Deny |
The following sections provide a basic introduction to claim rules and provide further details about when to use this 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.
Permit All Users
When you use the Permit All Users rule template, all users will have access to the relying party. However, you can use additional authorization rules to further restrict access. If one rule permits a user to access the relying party, and another rule denies the user access to the relying party, the deny result overrides the permit result and the user is denied access.
Users who are permitted access to the relying party from the Federation Service may still be denied service by the relying party.
Permit access to users with this incoming claim
When you use the Permit or Deny Users Based on an Incoming Claim rule template to create a rule and set the condition to permit, you can permit specific user's access to the relying party based on the type and value of an incoming claim. For example, you can use this rule template to create a rule that will permit only those users that have a group claim with a value of Domain Admins. If one rule permits a user to access the relying party, and another rule denies the user access to the relying party, the deny result overrides the permit result and the user is denied access.
Users who are permitted to access the relying party from the Federation Service may still be denied service by the relying party. If you want to permit all users to access the relying party, use the Permit All Users rule template.
Deny access to users with this incoming claim
When you use the Permit or Deny Users Based on an Incoming Claim rule template to create a rule and set the condition to deny, you can deny user's access to the relying party based on the type and value of an incoming claim. For example, you can use this rule template to create a rule that will deny all users that have a group claim with a value of Domain Users.
If you want to use the deny condition yet also enable access to the relying party for specific users, you must later explicitly add authorization rules with the permit condition to enable those users access to the relying party.
If a user is denied access when the claims issuance engine processes the rule set, further rules processing shuts down, and AD FS returns an "Access denied" error to the user's request.
Authorizing users
In AD FS, authorization rules are used to issue a permit or deny claim that will determine whether a user or a group of users (depending on the claim type used) will be allowed to access Web-based resources in a given relying party or not. Authorization rules can only be set on relying party trusts.
Authorization rule sets
Different authorization rule sets exist depending on the type of permit or deny operations you need to configure. These rule sets include:
Issuance Authorization Rules: These rules determine whether a user can receive claims for a relying party and, therefore, access to the relying party.
Delegation Authorization Rules: These rules determine whether a user can act as another user to the relying party. When a user is acting as another user, claims about the requesting user are still placed in the token.
Impersonation Authorization Rules: These rules determine whether a user can fully impersonate another user to the relying party. Impersonating another user is a very powerful capability, because the relying party will not know that the user is being impersonated.
For more details about how the authorization rule process fits into the claims issuance pipeline, see The Role of the Claims Issuance Engine.
Supported claim types
AD FS defines two claim types that are used to determine whether a user is permitted or denied. These claim type Uniform Resource Identifiers (URIs) are as follows:
Permit: http://schemas.microsoft.com/authorization/claims/permit
Deny: http://schemas.microsoft.com/authorization/claims/deny
How to create this rule
You can create both authorization rules using either the claim rule language or using the Permit All Users rule template or the Permit or Deny Users Based on an Incoming Claim rule template in the AD FS Management snap-in. The Permit All Users rule template does not provide any configuration options. However, the Permit or Deny Users Based on an Incoming Claim rule template provides the following configuration options:
Specify a claim rule name
Specify an incoming claim type
Type an incoming claim value
Permit access to users with this incoming claim
Deny access to users with this incoming claim
For more instructions on how to create this template, see Create a Rule to Permit All Users or Create a Rule to Permit or Deny Users Based on an Incoming Claim in the AD FS Deployment Guide.
Using the claim rule language
If a claim should be sent only when the claim value matches a custom pattern, you must use a custom rule. For more information, see When to Use a Custom Claim Rule.
Example of how to create an authorization rule based on multiple claims
When using the claim rule language syntax to authorize claims, a claim can also be issued based on the presence of multiple claims in the user's original claims. The following rule issues an authorization claim only if the user is a member of the group Editors and has authenticated using Windows authentication:
[type == "https://schemas.microsoft.com/ws/2008/06/identity/claims/authenticationmethod",
value == "urn:federation:authentication:windows" ]
&& [type == "http://schemas.xmlsoap.org/claims/Group ", value == "editors"]
=> issue(type = "http://schemas.xmlsoap.org/claims/authZ", value = "Granted");
Example of how to create authorization rules that will delegate who can create or remove federation server proxy trusts
Before a Federation Service can use a federation server proxy to redirect client requests, a trust must first be established between the Federation Service and the federation server proxy computer. By default, a proxy trust is established when either of the following credentials is provided successfully in the AD FS Federation Server Proxy Configuration Wizard:
The service account, used by the Federation Service, that the proxy will protect
An Active Directory domain account that is a member of the local Administrators group on all federation servers in a federation server farm
When you want to specify which user or users can create a proxy trust for a given Federation Service, you can use any of the following delegation methods. This list of methods is in priority order, based on the AD FS product team's recommendations of the most secure and least problematic methods of delegation. It is necessary to use only one of these methods, depending on the needs of your organization:
Create a domain security group in Active Directory (for example, FSProxyTrustCreators), add this group to the local Administrators group on each of the federation servers in the farm, and then add only the user accounts to which you want to delegate this right to the new group. This is the preferred method.
Add the user's domain account to the administrator group on each of the federation servers in the farm.
If for some reason you cannot use either of these methods, you can also create an authorization rule for this purpose. Although it is not recommended—because of possible complications that may occur if this rule is not written correctly—you can use a custom authorization rule to delegate which Active Directory domain user accounts can also create or even remove the trusts between all the federation server proxies that are associated with a given Federation Service.
If you choose method 3, you can use the following rule syntax to issue an authorization claim that will allow a specified user (in this case, contoso\frankm) to create trusts for one or more federation server proxies to the Federation Service. You must apply this rule using the Windows PowerShell command Set-ADFSProperties AddProxyAuthorizationRules.
c:[Type == "https://schemas.microsoft.com/ws/2008/06/identity/claims/windowsaccountname", issuer=~"^AD AUTHORITY$" value == "contoso\frankm" ] => issue(Type = "https://schemas.microsoft.com/authorization/claims/permit", Value = "true") exists([Type == "https://schemas.microsoft.com/ws/2008/06/identity/claims/groupsid", Value == "S-1-5-32-544", Issuer =~ "^AD AUTHORITY$"]) => issue(Type = "https://schemas.microsoft.com/authorization/claims/permit", Value = "true"); c:[Type == "https://schemas.microsoft.com/ws/2008/06/identity/claims/primarysid", Issuer =~ "^AD AUTHORITY$" ] => issue(store="_ProxyCredentialStore",types=("https://schemas.microsoft.com/authorization/claims/permit"),query="isProxyTrustManagerSid({0})", param= c.Value ); c:[Type == "https://schemas.microsoft.com/ws/2008/06/identity/claims/proxytrustid", Issuer =~ "^SELF AUTHORITY$" ] => issue(store="_ProxyCredentialStore",types=("https://schemas.microsoft.com/authorization/claims/permit"),query="isProxyTrustProvisioned({0})", param=c.Value );Later, if you want to remove the user so that the user can no longer create proxy trusts, you can revert to the default proxy trust authorization rule to remove the right for the user to create proxy trusts for the Federation Service. You must also apply this rule using the Windows PowerShell command Set-ADFSProperties AddProxyAuthorizationRules.
exists([Type == "https://schemas.microsoft.com/ws/2008/06/identity/claims/groupsid", Value == "S-1-5-32-544", Issuer =~ "^AD AUTHORITY$"]) => issue(Type = "https://schemas.microsoft.com/authorization/claims/permit", Value = "true"); c:[Type == "https://schemas.microsoft.com/ws/2008/06/identity/claims/primarysid", Issuer =~ "^AD AUTHORITY$" ] => issue(store="_ProxyCredentialStore",types=("https://schemas.microsoft.com/authorization/claims/permit"),query="isProxyTrustManagerSid({0})", param= c.Value ); c:[Type == "https://schemas.microsoft.com/ws/2008/06/identity/claims/proxytrustid", Issuer =~ "^SELF AUTHORITY$" ] => issue(store="_ProxyCredentialStore",types=("https://schemas.microsoft.com/authorization/claims/permit"),query="isProxyTrustProvisioned({0})", param=c.Value );
For more information about how to use the claim rule language, see The Role of the Claim Rule Language.