Active Directory Federation Services

This article begins with a brief overview of Active Directory Federation Services (AD FS), a list of the benefits to using AD FS, and a list of what's new in AD FS for Windows Server 2008. The article then focuses on the code that a managed developer must incorporate into a Web application to make it federation-aware and provides some specific examples on making claims based authorization decisions.

Overview

AD FS is a standards-based service that allows the secure sharing of identity information between trusted business partners (known as a federation) across an extranet. When a user needs to access a Web application from one of its federation partners, the user's own organization is responsible for authenticating the user and providing identity information in the form of "claims" to the partner that hosts the Web application. The hosting partner uses its trust policy to map the incoming claims to claims that are understood by its Web application, which uses the claims to make authorization decisions.

AD FS is Microsoft's implementation of the WS-Federation Passive Requestor Profile protocol (passive indicates that the client requirements are just a cookie- and JavaScript-enabled Web browser). AD FS implements the standards based WS-Federation protocol and Security Assertion Markup Language (SAML).

The AD FS administration tool (adfs.msc) is supplied as a Microsoft Management Console (MMC) snap-in. The administration tool is used to add account and resource partners, map partner claims, add and configure account stores, and identify and configure federation-aware Web applications.

For in-depth discussions of AD FS, see the following articles:

Simplify Single Sign-on Using ADFS

A Developer's Introduction To Active Directory Federation Services

Major Benefits

The following is a brief list of the major benefits to using AD FS:

• Web single sign on (SSO)

  AD FS provides Web SSO to federated partners outside your organization, which enables their users to have a SSO experience when they access your organization’s Web-based applications.

• Web Services (WS)-* interoperability

  AD FS provides a federated identity management solution that interoperates with other security products that support the WS-* Web Services Architecture. AD FS follows the WS-Federation specification (for passive clients; that is, browsers), which makes it possible for environments that do not use the Windows identity model to federate with Windows environments.

• Partner user account management not required

  The federated partner's Identity Provider (IP) sends claims that reflect its users' identity, groups, and attribute data. Therefore, your organization no longer needs to revoke, change, or reset the credentials for the partner's users, since the credentials are managed by the partner organization. Additionally, if a partnership needs to be terminated, it can be performed with a single trust policy change. Without AD FS, individual accounts for each partner user would need to be deactivated.

• Claim mapping

  Claims are defined in terms that each partner understands and appropriately mapped in the AD FS trust policy for exchange between federation partners.

• Centralized federated partner management

  All federated partner management is performed using the AD FS Microsoft Management Console (MMC) snap-in.

• Extensible architecture

  AD FS provides an extensible architecture for claim augmentation, for example, adding or modifying claims using custom business logic during claims processing. Organizations can use this extensibility to modify AD FS to finely support their business policies.

New and Improved Features

AD FS was first released in Windows Server 2003 R2. It has been updated with the following new and improved features for Windows Server 2008:

• Improved support for Microsoft Office SharePoint® Services 2007 as a claims-aware application

• Support for Active Directory Rights Management Services (AD RMS)

  External users attempting to access an organization's protected content are authenticated through AD FS. Once these external users are authenticated, AD RMS policies are enforced, and AD RMS will automatically provide the external user with appropriate content licenses to work with an organization's protected content. Administrators have granular control over how these external users interact with an organization's content and can also define templates to apply to multiple partner relationships. Federated AD RMS in Windows Server 2008 is fully compatible with existing Office SharePoint Server 2007 deployments and fully supports down-level AD RMS clients.

• Group Policy control of AD FS deployment

  In previous versions of AD FS, there was no way to limit who deployed an AD FS server in the enterprise. Administrators now have the ability to control and stage the rollout of AD FS servers by limiting deployment through Group Policy.

• Improved installation

  AD FS is included as a server role and is installed using Server Manager, which automatically lists and installs all the services required by AD FS during installation. A configuration wizard is available to perform server validation checks during the AD FS installation. This feature not only makes installation easier, but also gives AD FS the same consistent install experience as other Windows components.

• Improved import and export of trust policy during federated trust establishment

  This improvement simplifies the process for bringing federation partners on board.

• Events and Microsoft Operations Manager (MOM) alerts

  Previous versions of AD FS lacked the ability to easily determine when certificates were going to expire. New events and MOM alerts allow IT administrators to be proactive instead of reactive in managing the certificates, dramatically reducing the possibility of user impact issues.

• AD FS snap-in control of certificate revocation list (CRL) checking

  In previous versions of AD FS, administrators occasionally had to disable CRL checking because partners issued their own certificates that were chained to an Internet authority, but did not publish their CRLs to the internet. CRL checking had to be disabled by manually modifying the trust policy of an XML file. This procedure was not intuitive, difficult to troubleshoot, and the solution was a medium-high risk operation on the AD FS servers. The AD FS snap-in now allows CRL checking behavior (within the scope of AD FS) to be adjusted or disabled.

Developing Federation-Aware Applications

Behind-the-Scenes Workflow

While a deep understanding of the process behind the delivery of an AD FS authenticated user to the Web application is not necessary, an overview of the process can be helpful. The following scenario is a simplified example of what occurs behind the scenes when a user from a federated partner accesses a federation-aware application.

Consider a user from one partner (known as the "account" partner) who attempts to access an AD FS enabled Web application hosted by another partner (known as the "resource" partner). The AD FS Web Agent on the resource partner's Web server intercepts the request and checks whether the user has an appropriate AD FS cookie. If so, the user is given access to the Web application. If not, the user is redirected to the resource partner's AD FS server.

The resource partner's AD FS checks the request for a security (SAML) token from the account partner and, if the token is not found, orchestrates "home realm" discovery. Home realm discovery is the process of determining the federation server associated with the user either implicitly or by presenting the user with a Web page to make an explicit choice. Once determined, a self-identifier is added to the request so that the account partner's federation server knows who is requesting a security token and the user is redirected to the account partner's federation server.

There, the user is asked to authenticate, either implicitly if the account partner is using AD FS with integrated Windows authentication, or through some other explicit manner depending on the federation service's implementation. It is important to recognize that the user is authenticated by the user's own organization. Once authenticated, the account partner's federation service issues a security token containing identity information (in the form of "claims") and redirects the user back to the resource partner's AD FS server.

The resource partner's AD FS now finds the security token and verifies it is from one of its trusted account partners. AD FS uses its trust policy to map the account partner claims to claims that are understood by its Web application. Then AD FS issues a second SAML token that contains the resource partner claims, writes the contents to a cookie on the user's computer, and redirects the user back to the Web application.

The AD FS Web Agent discovers the cookie, parses the SAML token, and allows access to the Web application. The Web application instantiates a SingleSignOnIdentity object, which contains the claims parsed from the SAML token, and uses these claims to make authorization decisions. For information on AF DS cookies, see Cookies used by ADFS.

Claims

From an application developer's perspective, the primary area of interest in AD FS is the claim. What is a claim, how is it obtained, and how is it used to make authorization decisions? The last two questions will be answered in the step-by-step example that follows this section.

A claim is a statement about a user, and typically, a security token contains multiple claims. There are three claim types supported in WS-Federation:

• Identity, which identifies the user. A security token must contain at least one Identity claim but can contain three, one for each of the following, listed in order of priority:

  • User Principal Name (UPN), for example, user@realm

  • Email, for example, user@domain

  • Common Name, which is an arbitrary string

• Group, which indicates membership in a group or role, for example, Purchaser or Owner.

• Custom, which provides any additional information about the user, for example, EmployeeID. This is a name/value pair. A Custom claim can be any attribute value associated with the User object in Active Directory.

Each partner in the federation defines its own claims in terms that it understands. The AD FS snap-in is used to create an organization's claims and map these claims to partner claims. For more information, see Understanding Claims. Claims originate from an account store, either Active Directory (AD) or Active Directory Lightweight Directory Services.

Step-by-Step Example

The following example demonstrates the steps necessary for a Web application to make claims-based authorization decisions using AD FS. Windows Authorization Manager (AzMan) is used to provide role-based access control (RBAC). For more information about AzMan and a discussion of the portions of the example code that use AzMan, see the companion topic Windows Authorization Manager.

The development tasks are:

1. Make the application federation-aware

   • Register the AD FS Web Agent

   • Specify a custom configuration section and handler

   • Add the custom section

   • Reference the SingleSignOn assemblies

2. Obtain the SingleSignOnIdentity object

3. Verify authentication

4. Create a client context using AzMan

5. Retrieve claims

6. Make authorization decisions

   • Use raw claims

   • Use role checks

   • Use access checks

Step 1: Make the Application Federation-Aware

Making an application federation-aware requires the following changes to its Web.config file. Once these changes are made, the application can obtain claims from AD FS for the federation partners. (Note: The Web application must also be identified and configured within the AD FS snap-in, which enables both the federation service and the Web application to securely identify each other.)

Register the AD FS Web Agent

AD FS provides a Web agent that runs in the IIS request pipeline as an extension HTTP module of type System.Web.Security.SingleSignOn.WebSsoAuthenticationModule. The AD FS Web Agent registers a handler for the HttpApplication.BeginRequest event, which performs all the processing for cookies, query strings, and HTTP POST messages. The agent obtains the identity (security token) of the user and decides whether to permit access to the application. The application must add the AD FS Web Agent to the webServer\modules section of its Web.config file as shown in the following XML example.

<webServer>
  <modules>
    <add name="AD FS Web Agent"
       type="System.Web.Security.SingleSignOn.WebSsoAuthenticationModule,
             System.Web.Security.SingleSignOn,
             Version=1.0.0.0, Culture=neutral,
             PublicKeyToken=31BF3856AD364E35, Custom=null" />
  </modules>
</webServer>

Specify a Custom Configuration Section and Handler

The AD FS Web Agent needs to access settings stored in the Web.config file and uses a configuration section handler of type System.Web.Security.SingleSignOn.WebSsoConfigurationHandler to do so. The settings are stored in a custom section named websso. The configuration file handler must be made aware of the custom section by specifying the section in the system.web section group as shown in the following XML example.

<configSections>
  <sectionGroup name="system.web">
    <section name="websso"
             type="System.Web.Security.SingleSignOn.WebSsoConfigurationHandler,
                   System.Web.Security.SingleSignOn,
                   Version=1.0.0.0, Culture=neutral,
                   PublicKeyToken=31BF3856AD364E35, Custom=null" />
  </sectionGroup>
</configSections>

Add the Custom Section

The settings required by the AD FS Web Agent are specified in the custom websso section and described in the following table.

<websso>
  <fs>https://someresourcefederationserver/adfs/fs/federationserverservice.asmx</fs>
  <urls>
    <returnurl>https://localhost/TreyOrdering/Default.aspx</returnurl>
  </urls>
  <cookies writecookies="true">
    <path>/TreyOrdering</path>
  </cookies>
  <authenticationrequired />
</websso>

Reference the SingleSignOn Assemblies

Add references for the System.Web.Security.SingleSignOn and System.Web.Security.SingleSignOn.ClaimTransforms assemblies to enable the Web application to access types in the System.Web.Security.SingleSignOn and System.Web.Security.SingleSignOn.Authorization namespaces, respectively.

Also, set the authentication mode to None since authentication is performed by AD FS, not Internet Information Services (IIS).

<system.web>
  <authentication mode="None" />
  <compilation defaultLanguage="c#" debug="true">
    <assemblies>
      <add assembly="System.Web.Security.SingleSignOn,
                     Version=1.0.0.0, Culture=neutral,
                     PublicKeyToken=31BF3856AD364E35"/>
      <add assembly="System.Web.Security.SingleSignOn.ClaimTransforms,
                     Version=1.0.0.0, Culture=neutral,
                     PublicKeyToken=31BF3856AD364E35"/>
    </assemblies>
  </compilation>
</system.web>

Step 2: Obtain the SingleSignOnIdentity Object

In the code for the Web application, include the System.Web.Security.SingleSignOn namespace, which contains the SingleSignOnIdentity class, and the System.Web.Security.SingleSignOn.Authentication namespace, which contains the SecurityProperty and SecurityPropertyCollection classes. These namespaces enable the application to use the AD FS infrastructure for authentication and access the claims it provides via the SAML token.

using System.Web.Security.SingleSignOn;
using System.Web.Security.SingleSignOn.Authorization;

The SingleSignOnIdentity object is set on the HttpContext.User property by the AD FS Web Agent (WebSsoAuthenticationModule). The application obtains the SingleSignOnIdentity object during the Page_Load event.

private void Page_Load(object sender, System.EventArgs e)
{
    SingleSignOnIdentity SsoId = User.Identity as SingleSignOnIdentity;
}

Step 3: Verify Authentication

The Web.config file for this example includes the authenticationrequired element, which by default is true. This tells the AD FS Web Agent that a user must be authenticated before access to the Web application is granted. When the authenticationrequired element is not present or set to false, the user can access the application anonymously. If anonymous access is allowed, use the SingleSignOnIdentity.IsAuthenticated property to check for authentication.

if (SsoId.IsAuthenticated)
{
    // ... 
}
else
{
    // This redirects the user to the resource AD FS Logon service.
    SsoId.SignIn(Context); 
}

At times, who provided the authentication might be a consideration before trust is granted to the user. Use the SingleSignOnIdentity.AuthenticatingAuthority property for this.

Step 4: Create a Client Context Using AzMan

The following code example shows how to connect to the AzMan trust policy store, obtain an object that represents this application's trust policy in the AzMan store, and create an empty client context. Subsequently, the client context will be populated with Group claims and used to make authorization decisions.

string connectionString = @"msxml://c:\AuthPolicy\AzStore.xml";

// Connect to the AzMan authorization policy store.
AzAuthorizationStoreClass azStore = new AzAuthorizationStoreClass();
azStore.Initialize(0, connectionString, null);

// Obtain the object associated with this application.
IazApplication2 azApplication = 
    azStore.OpenApplication("Trey Ordering", null);

// Create an empty client context.
IAzClientContext3 clientContext = 
    azApplication.InitializeClientContext2("Trey Ordering", null);

Step 5: Retrieve Claims

The System.Web.Security.SingleSignOn.Authentication namespace contains the SecurityProperty and SecurityPropertyCollection classes. The SingleSignOnIdentity.SecurityPropertyCollection property returns a SecurityPropertyCollection instance, which contains a SecurityProperty object for each claim about the user. Group claims are added as roles to the AzMan client context. Identity and custom claims are added to a NameValueCollection object for convenient retrieval.

SecurityPropertyCollection claims = SsoId.SecurityPropertyCollection;

// Add all Group claims (as roles) to the AzMan client context.
clientContext.AddRoles(claims.GetRoles(), null);

// Store identity and custom claims in a NameValueCollection.
foreach (SecurityProperty claim in claims.GetIdentities())
{
    nonGroupClaims.Add(claim.Name, claim.Value);
}
foreach (SecurityProperty claim in claims.GetProperties(
    SecurityProperty.CustomClaimUri))
{
    nonGroupClaims.Add(claim.Name, claim.Value);
}

Step 6: Make Authorization Decisions

There are numerous ways to make authorization decisions. Three of the more common are discussed here:

• Use raw claims

• Use role checks

• Use access checks

Access checks are the recommended use and make the application less coupled with policy.

Raw Claims

Raw claims from AD FS are available through the SecurityPropertyCollection object. The following code example shows a decision based on the custom claim named EmployeeID, which in the previous section was retrieved and added to the nonGroupClaims NameValueCollection. Raw claims can be used in conjunction with role and access checks.

if (Convert.ToInt32(nonGroupClaims["EmployeeID"]) == 321)
{
    // Allow access.
}

Role Checks

The easiest means to make authorization decisions is to base them on roles using the IPrincipal.IsInRole method, which is available through HttpContext.User or the SecurityPropertyCollection.IsInRole method. IsInRole returns true if there is a Group claim equal to the role. Role checks do not provide the granularity that access checks allow.

if (User.IsInRole("Purchaser"))
{
    // Allow access.
}

-or-

if (claims.IsInRole("Purchaser"))
{
    // Allow access.
}

The client context obtained through AzMan can also be used for role checks as the following code snippet demonstrates.

if (clientContext.IsInRoleAssignment("", "Purchaser") )
{
    // Allow access.
}

Access Checks

AzMan is used for access checks, which allow authorizations to be made based on specific operations defined in the AzMan authorization policy store. In the following code example, access is granted to any user in an AzMan role (Group claim) that is allowed to perform operation #57.

// 57 corresponds to an OperationID defined in the AzMan store.
if (clientContext.AccessCheck2("Order #123", "", 57) == 0)
{
    // Allow access for operation #57.
}

See Also

Concepts

Develop Federation-Aware Applications

Windows Authorization Manager

Other Resources

Active Directory Federation Services (MSDN)

Active Directory Federation Services (TechNet)

AD FS Documentation Blog

AD FS Product Support Blog

AD FS Class Library

The .NET Developer's Guide to Identity