Identity & Access Management

Simplify Single Sign-on Using ADFS

Matt Steele

At a Glance:

• ADFS architecture and basic message flow
• Configuring ADFS claims
• Integration with SharePoint technologies
• ADFS best practices

Active Directory Federation Services, also known as ADFS, was introduced in Windows Server 2003 R2 to help organizations set up and participate in a standards-based identity federation.

IT organizations can use identity federations to make decisions based on identity data from other organizations, while also sharing selected information about their own users' identities. You can think of a federation as an agreement between two organizations with some common purpose, often structured so that each partner retains the management of its own internal affairs. In this context, identity is defined by a set of statements or claims about a subject (you can read more about this in Joshua Trupin's article in this issue, or in Kim Cameron's "Laws of Identity" whitepaper). So the common purpose of an identity federation is the sharing of identity information and identity authentication responsibilities. ADFS enables this decentralized identity sharing by implementing the WS-Federation protocol along with standards such as WS-Trust and Security Assertion Markup Language (SAML).

In this article I will discuss the underlying concepts and architecture of identity federation and ADFS. In addition, I'll review how claims are configured and transmitted between account and resource partners using ADFS, provide notes about the ADFS SharePoint® integration, and share some ADFS best practices.

Major Benefits of ADFS

ADFS provides an identity federation solution for organizations looking to share identity information with their partners in a secure manner. Using the trust policy for an ADFS Federation Service, you can manage your trust relationship with partners and map partner claims to claims understood by your organization's Web applications.

By relying on partner claims to initiate Web application sessions, responsibility for partner account management remains with the partner. The partner knows when its new employees are hired, shift roles, and are terminated. And ADFS enables federation partnerships to be managed in a central place, reducing the headache of adding and removing partnerships.

ADFS also helps organizations share identity with partnerships using the same trust policy. When establishing a partnership to use another organization's Web applications, ADFS provides a central place to manage and audit the employee identity information that is shared with that partner.

Identity federation with ADFS offers solutions to a number of potential issues.

Partner Account Provisioning A partner organization has just hired a new employee and would like that employee to access Web applications offered by your organization under the existing partnership agreement. Instead of requiring a new account managed by your organization, ADFS enables your organization to accept digitally signed claims from the partner organization. These claims from the partner organization can confirm that the requestor is indeed an employee of the partner.

Partner Account Credential Management With a new local account for the partner employee, you'd normally need to have some method of managing the credential she uses to authenticate. With ADFS, your organization no longer needs to revoke, change, or reset that credential, since the credential is managed by the partner organization.

Partner Account Management Suppose an employee in a partner organization has a new role that requires access to a different set of your Web apps. With ADFS, your partner always sends claims that reflect the employee's current roles and permissions. Since ADFS allows you to use the partner's claims to control access to your applications, the employee's access is updated immediately.

Partner Account Deactivation What if an employee with access to partner resources is fired? With ADFS, the employer can remove access for this employee across all other partner organizations. Without this functionality, the employer would have to contact each partner organization separately—and the ex-employee would continue to have access until this was accomplished.

Partner Changes Imagine that a partner organization has begun aligning itself with your top competitor. Your organization decides to terminate the partnership to avoid any further information disclosure. With ADFS, the termination of the partnership can be effected with a single trust policy change. Without centralized partner management, individual accounts for each partner employee would need to be deactivated—a much lengthier process.

ADFS Architecture and Message Flow

ADFS provides a standards-based solution that interoperates with other identity federation products supporting the WS-* Web services architecture. ADFS complies with the WS-Federation specification using the Passive Requestor Interoperability Profile. Implementing the WS-Federation specification enables ADFS to interoperate with environments that might not use the Windows® identity model.

Imagine that two companies, A. Datum Corporation and Trey Research Inc., want to set up a federation. Trey Research makes its research reports available to partner companies with a Web application. Trey Research has a new agreement with A. Datum to allow access to these reports for A. Datum employees. Trey Research is referred to as the resource partner in this scenario because it is providing access to the resource Web application. A. Datum is referred to as the account partner in this scenario because the user accounts are managed by A. Datum (see Figure 1).

Figure 1 Partner Relationships

So let's examine how the message exchange in this example will work. All exchanges and redirects require the use of TLS/SSL to secure the claims that are transferred. When an A. Datum user accesses the Trey Research ADFS-enabled Web application, the user will be redirected to the Trey Research ADFS Federation Service. If it's the first time the user has been redirected, the Federation Service may present the user with an interface for selecting an account partner membership. This process is referred to as Home Realm Discovery, and it is necessary when Trey Research has more than one partnership. This may be augmented with customized code in order to automate the discovery process. The corresponding ASP.NET page may also be customized by the Trey Research IT organization to provide a consistent interface and experience that would be familiar to the A. Datum user.

After selecting the A. Datum account partner, the user is then redirected to the A. Datum Federation Service, which authenticates the user using the appropriate technology (integrated, forms, certificate, or the like). Referring to its trust policy, the A. Datum Federation Service gives the client a signed security token with a set of claims appropriate for Trey Research to be redirected back to the Trey Research Federation Service.

The Trey Research Federation Service verifies A. Datum's digital signature on the security token and examines the attached claims. For each claim in the security token, the Trey Research Federation Service will refer to its trust policy and map the claim (if configured) to another claim local to the organization. For organizations that are already using Active Directory®, these mapped claims can be further associated with groups in Active Directory. Once all claims have been mapped to their local equivalents, a new security token is created containing the claims local to Trey Research. This token is then sent back to the client to be redirected to the original Trey Research ADFS-enabled Web application.

The Web application receives the security token and verifies the digital signature of the Trey Research Federation Service. Once the signature has been verified, the claims in the token can be used to identify the user and make any necessary authorization decisions.

Claims Flow in ADFS

The heart of identity federation with ADFS is the ability to capture existing identity date in an account partner organization and transmit it as a set of claims to a resource partner organization in a standardized way. The claims from an account partner pass through several components before arriving at the resource application. The transformations that take place at each of these components must be configured correctly for the claims to pass through in the expected manner. Understanding the overall picture of these components and transformations in ADFS helps to understand the purpose of each step of the process.

Figure 2 shows the general flow of claims through all of the ADFS components. The organization claim is the starting point and is typically created first as a representation of the possible claims in the organization. Using the earlier example configuration (which you can read more about in the Step-by-Step Guide for Active Directory Federation Services, the account partner, A. Datum Corporation, is transmitting group claims to its federation resource partner Trey Research.

Figure 2 ADFS Claims Flow

It is easy to imagine that A. Datum may want to identify certain individuals who are entitled to purchase new research reports in the Trey Research Web application. This designation could be specified by membership in a particular group in A. Datum's Active Directory. ADFS enables this identity data to be communicated to Trey Research as a claim (I'll call it the "Purchaser" claim), so that Trey Research may ensure that only authorized purchasers are allowed to execute a purchase order.

The Purchaser claim is an A. Datum organization claim that will be passed to Trey Research with the intent to grant access to A. Datum users for the Trey Research Web application. Figure 3 shows the ADFS UI for creating the organization claim in the A. Datum trust policy.

Figure 3 Organization Claim

Once A. Datum's organization claim is defined, the company's ADFS administrator must define which A. Datum users will be assigned this claim. The mapping can be done by associating one or more Active Directory groups with the claim using the New Group Claim Extraction option for the Active Directory account store. Figure 4 shows a group claim extraction being defined to ensure that all users that are members of the Purchasers group will be assigned the Purchaser organization claim.

Figure 4 Group Claim Extraction

Now the first two legs of Figure 1 have been configured for A. Datum. The last part of the A. Datum configuration is to enable the claim to be sent to Trey Research using a name for the claim that has been agreed upon by both organizations. To do this I'll define a new Outgoing Group Claim Mapping for the Trey Research resource partner. Here, the string "ResearchPurchaser" is the actual text that will be used to represent this claim in the token sent to Trey Research. Without an outgoing claim mapping for a resource partner, an organization claim will not be sent to that resource partner. This can be useful when you have claims you don't want to share with some partners. Figure 5 shows the claim mapping creation UI with the text and the associated organization claim in the dropdown box.

Figure 5 Outgoing Group Claim Mapping

This completes the configuration of claims flow for the A. Datum account partner. Using the Federation Service UI, I've defined the Purchaser organization claim, configured which users are assigned this claim (based on Active Directory groups), and defined the text representation of the claim to Trey Research. Using the partner relationships in Figure 1 as a reference, I've defined the first three transformations and the A. Datum Federation Service now correctly packages claims in the user's token to be transmitted to Trey Research.

To begin configuring the Trey Research Federation Service to handle this claim, I now need to define an organization claim for Trey Research. This claim is constructed using the same interface shown in Figure 3 and is called the Adatum Purchaser Claim. Once the claim is defined, I'll associate it with the incoming text in A. Datum users' security tokens by creating a new Incoming Group Claim Mapping in the A. Datum account partner configuration of the Trey Research Federation Service. Because the mapping represents the actual incoming text, it must match exactly what is configured in the A. Datum trust policy. Figure 6 shows the connection between the text and the Adatum Purchaser Claim.

Figure 6 Incoming Group Claim Mapping

At this point, all of the necessary components have been configured except for enabling the claim for the particular Trey Research application. Optionally, the claim may be mapped to an Active Directory group to allow an NT Token-based application to rely on Win32® authorization mechanisms such as access control lists (ACLs) set using Active Directory security identifiers (SIDs). This configuration change is made on the organization claim itself under the properties dialog and is optional because claims-aware applications do not leverage the Windows NT® token model.

The final step for completing the flow to the application involves configuring the organization claim to be sent to the intended application, as detailed in the ADFS Step-by-Step Guide. Completing this final step connects all the components together so that, for the account partner, claims may be created from Active Directory groups and sent to appropriate partners. For the resource partner, claims may now be received from partners, possibly correlated with Active Directory groups, repackaged in the user's security token, and sent to the appropriate applications.

Claims-aware applications are part of a newer model designed for applications written in ASP.NET 2.0 and built to handle the claims within the application code. These applications consume ADFS claims natively and may make authorization decisions based directly on the content of those claims, without necessarily incorporating Windows security principals or groups. Using claims in this way allows inclusion of dynamic, custom claims, such as purchasing limits, that may be configured at the Federation Service and distributed to applications that understand the claims. Using the example Purchaser claim defined in this section, the Trey Research Web application may now allow A. Datum users with the Purchaser claim to order new research reports for A. Datum. This functionality is enabled without the need for Trey Research to maintain any A. Datum user accounts.

ADFS Best Practices

Imagine for a moment that, as the local ADFS guru, you are asked to spearhead configuring your company's 30 business partners as account federation partners. Setting up a single partner following the ADFS Step-by-Step Guide wasn't too difficult, but what about configuration on a larger scale? There are important concerns for organizations looking to scale the number of partners further out in ADFS. Best practices for addressing these concerns include understanding the technical requirements of your partnering process, using a consistent structure for organization claims, and using the ADFS Object Model (OM) Application Programming Interface (API).

Standardization Your organization may have a large set of business and legal requirements for setting up federation partners, but the ADFS technical requirements are fairly simple. Whether your organization will be functioning in the account or resource partner role, you'll need to agree with each partner on the actual names for the claims that will be exchanged across organizations. If you are a resource partner with numerous account partners, it may be fairly easy to develop a standard set of mappings and ask your account partners to conform as part of the partnership. As a resource partner, you must also make sure you obtain each account partner's token-signing certificate, which must be configured when creating the partner in the ADFS trust policy.

Flexibility When organizing claims in trust policy, there are some constraints to be aware of. For organizations looking to leverage NT Token-based applications, at least one group claim must map to each security group that the organization plans to use for authorization decisions on account partner users. The claims and mapping system in ADFS allows for some flexibility and abstraction in claim assignment on the resource. For example, in situations where multiple different claims from a partner result in the same claim on the resource side, ADFS allows multiple claim mappings to refer to the same claim. Because the claims intended for claims-aware applications often do not map to Active Directory groups, there is even more flexibility for those applications. Flexibility in the ADFS claims model allows for many solutions.

Automation For organizations with complex workflows and business processes and high partner churn, the ADFS OM API offers an alternative to the manual configuration process. The OM API allows programmatic access to trust policy construction and editing. Organizations with existing custom tools for handling business processes can integrate ADFS trust policy editing into the partnering process tools directly. As partner volume and churn increase, this can also be preferable to allow for some automation as well as extended partner-analysis functionality.

Read more about the ADFS OM API at go.microsoft.com/fwlink/?LinkId=66063.

Integration with SharePoint

Understanding the flow of claims makes configuring the trust policy fairly intuitive. The Web application and ADFS Web Agent are the final elements of a full ADFS configuration. There are many applications that can be federation-enabled with ADFS Web Agents. Windows SharePoint Services (WSS) and SharePoint Portal Server (SPS) 2003 are popular options because of their rich, user-focused functionality. The ADFS Step-by-Step Guide details configuring WSS as an NT Token-based application and using claims mapped to Active Directory groups for partner-user authorization. The first appendix of the guide describes the necessary configuration steps for ADFS with SPS 2003. The ADFS Step-by-Step Guide is a great source of finely detailed information on this integration, so I'll just summarize the important points about deploying ADFS with the SharePoint technologies.

WSS qualifies as an NT Token-based application and integrates with the corresponding ADFS Web Agent. Configuring the ADFS Web Agent is the same for SharePoint as it is for most other NT Token applications. As stated in the guide, you configure the Federation Service URL within IIS and then enable the ADFS Web Agents on the default Web site. Figure 7 shows the IIS console interface for configuring the ADFS Web Agent.

Figure 7 Configuring the ADFS Web Agent

Once the Web Agent is configured for the SharePoint application, Active Directory groups can be assigned SharePoint roles such as Reader, Member, or Administrator. This process of assigning roles is part of SharePoint. SPS 2003 adds several significant features beyond WSS, including the ability to search across multiple sites. Because the SPS indexing process requires Windows Integrated Authentication, using SPS 2003 with ADFS requires a large farm-type configuration. The large farm configuration allows an internal indexing site to remain configured for Windows Integrated Authentication while the external sites are ADFS-enabled. This is important because configuring the SPS 2003 option described in the ADFS guide requires up to nine machines for a full identity federation simulation.

When using WSS or SPS with ADFS as a federated application, administrators must also consider the integration points with Microsoft® Office 2003 clients. The WS-Federation Passive Requestor Interoperability Profile, which ADFS implements, was designed for use by browsers that fully implement HTTP along with client-side scripting. The HTTP clients in Office 2003 are designed with constrained browser functionality in order to keep security high and attack surface low. With the constrained browser functionality, Office clients are not always able to participate fully in the protocol. WSS and SPS have several unique integration points with Office clients that must be disabled to avoid confusing user errors in Office applications. The Knowledge Base article details the necessary configuration changes and supported scenarios. Much of the user experience remains the same, and downloaded documents will still be displayed to users in a manner similar to standard Internet browser downloads.

Conclusion

ADFS-enabled identity federation allows organizations to share identities in an interoperable, standardized way while reducing the headaches involved in business-to-business partnering. In addition, the claims-based identity model supported by ADFS and the WS-* specifications represents an integral part of the Microsoft identity platform. The online documentation makes it easy for you to experiment with the technology and see how it can help to alleviate your identity management challenges.

Matt Steeleis a Program Manager on the Active Directory Federation Services team at Microsoft. Matt is currently working on ADFS product integrations and supporting the design of future identity and access technologies.

© 2008 Microsoft Corporation and CMP Media, LLC. All rights reserved; reproduction in part or in whole without permission is prohibited.