Share via

Introduction to Token Issuance Authorization in AD FS 2.0 RC

  • Article

In this post we cover a new feature introduced in the Active Directory Federation Services (AD FS ) 2.0 RC - support for token issuance authorization. One of the main functions of the product in this and previous releases has been to provide a centralized point for authentication. Let’s try to briefly explain the distinction between the two: while authentication is the act of verifying the identity of a person, authorization is the act of determining whether the person can perform an action on a resource. In the scope of the AD FS 2.0 RC, the action is obtaining a token, while the resource is the relying party that the token is destined to.

Motivation

Support for token issuance authorization in AD FS offers similar benefits to performing centralized authentication. The authentication and authorization logic can be decoupled from the applications making them easier to write and maintain. The server performs both steps using the same claims based rule language. Let’s try to illustrate the benefits with an example. The Contoso Company outsources employee benefits to an external vendor, Fabrikam. The Fabrikam online store offers software and other merchandise to Contoso employees at discounted rates. A Contoso STS running AD FS is responsible for authenticating employees, thus freeing the vendor from that burden. Typically there are certain restrictions, e.g. only full time employees or employees of certain Contoso subsidiaries should be authorized to shop at the Fabrikam online store. Prior to supporting the authorization feature on the STS all authenticated users would be issued a token and the only place to enforce an authorization policy would be at the relying party. Why should Fabrikam be responsible for enforcing a policy defined by Contoso? Adding code to implement the policy and having to change the code to reflect future changes to the policy would be a hassle for the vendor. With the new token issuance authorization feature, the administrator of the Contoso STS can create a policy that authorizes token issuance to Fabrikam based on membership in an Active Directory security group. This implements a form of role based access control (RBAC) at the STS. The administrators of the Fabrikam online store need not be aware of the details of the access control policy and no action is required from the vendor if the policy changes.

Let us now take a look at the design of the feature in the product, i.e. where the authorization step is performed in the token issuance pipeline and how authorization rules are evaluated.

Authorization in the claims issuance policy pipeline

The following diagram illustrates the flow of claims during token issuance.

A user’s identity is represented by a number of claims (e.g. name claim, e-mail claim, group claims etc). These claims could either be sourced from an account store (e.g. when the AD FS STS is serving as an identity provider the claims are sourced from AD) or from an incoming SAML token from a federation partner. The claims are processed by a policy configured for the source of the claims (AD or another identity provider).

The normalized claims are then made available to the authorization module and processed with the authorization policy configured for the relying party that the token was requested for (each relying party configured on the STS has its own authorization policy). In many cases the normalized identity claims will be sufficient to make an authorization decision. In some cases additional information about the user may be needed and can be retrieved in the form of claims extraction from an attribute store (e.g. a SQL server database). A future post will provide more details on using attribute stores with AD FS 2.0. If the authorization check fails, processing of the request is aborted and no token is issued. If the authorization check succeeds, the normalized identity claims are processed by the specific issuance policy for the relying party and the output claims are included in the token.

In addition to authorizing token issuance the authorization module and language are also applied for identity delegation and impersonation scenarios.

Overview of the claims authorization language

Authorization rules are written using the same claims based language also used for authoring claims issuance rules. The result of the access check is determined by two claims where the claim type has special meaning:

  • A rule issuing a claim of type https://schemas.microsoft.com/authorization/claims/permit indicates that the access check should succeed

A rule issuing a claim of type https://schemas.microsoft.com/authorization/claims/deny indicates that the access check should fail

The claim values of the permit and deny claims have no effect on the authorization decision. Rules in the authorization policy are evaluated using the following principles:

  • Deny by default – if none of the rules issue a "permit" claim, the access check fails
  • Deny overrides – if there are conflicts between rules, i.e. there are rules that issue a "permit" claim and there are rules that issue a "deny" claim, the access check fails

Thus, the language supports both allow-list and deny-list semantics. An example of allow-list semantics would be a policy similar to the authorization policy used in our motivating example of restricting access to the Fabrikam online store. Such a policy would consist of two rules:

  1. Extract the group membership of the user from Contoso’s AD, each group is represented as a claim
  2. If a group claim with value "Authorized Fabrikam Shoppers" exists, issue a "permit" claim

An example of deny-list semantics could be a policy that controls access to classified documents and denies access if the user is a part time employee. Such policy could be represented with the following rules:

  1. Always issue a "permit" claim
  2. Query a SQL attribute store and issue a part time employee claim if the user is not a full time employee
  3. If a part time employee claim is present, issue a "deny" claim

If the user is a part time employee there will be a conflict between the output of rules 1) and 3), and since deny overrides the access check will fail.

Summary

In this post we provided an overview of the authorization feature introduced in AD FS 2.0 RC. Leveraging the feature allows the IT pro to support a number of scenarios:

  • Control access to relying party applications, e.g. Contoso’s use of RBAC to limit access to Fabrikam
  • Control what users can participate in federations, i.e. if the relying party is another STS, the administrator can selectively include/exclude groups of users from the federation

Stefan Miltchev

Software Design Engineer

AD FS Team

Comments

  • Anonymous
    January 14, 2010
    Please support Windows CardSpace 2.0 on Windows XP? Can someone from the team clarify why or why not?
  • Anonymous
    October 29, 2010
    Great article ! Is there any way to implment the token issuance auth in ADFS 1 (STS). I was thinking a group claim serves that purpose but it seems like not.TIA