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.

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.

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.

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.

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

<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

<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

<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

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

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

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.

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

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

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

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

Role Checks

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

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

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

Access Checks

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