Many companies want to share resources with their partners, but how can they do this when each business is a separate security realm with independent directory services, security, and authentication? One answer is federated identity. Federated identity helps overcome some of the problems that arise when two or more separate security realms use a single application. It allows employees to use their local corporate credentials to log on to external networks that have trust relationships with their company. For an overview, see the section "Federating Identity across Realms" in chapter 2, "Claims-Based Architectures."
In this chapter, you'll learn how Adatum lets one of its customers, Litware, use the a-Order application that was introduced in chapter 3, "Claims-Based Single Sign-On for the Web."

The Premise

Now that Adatum has instituted single sign-on (SSO) for its employees, it's ready to take the next step. Customers also want to use the a-Order program to track an order's progress from beginning to end. They expect the program to behave as if it was an application within their own corporate domain. For example, Litware is a longstanding client of Adatum's. Their sales manager, Rick, wants to be able to log on with his Litware credentials and use the a-Order program to determine the status of all his orders with Adatum. In other words, he wants the same SSO capability that Adatum's employees have. However, he doesn't want separate credentials from Adatum just to use a-Order.

Goals and Requirements

The goal of this scenario is to show how federated identity can make the partnership between Adatum and Litware be more efficient. With federated identity, one security domain accepts an identity that comes from another domain. This lets people in one domain access resources located in the other domain without presenting additional credentials. The Adatum issuer will trust Litware to authoritatively issue claims about its employees.
Other than the goals, this scenario has a few other requirements. One is that Adatum must control access to the order status pages and the information that is displayed, based on the partner that is requesting access to the program. In other words, Litware should only be able to browse through its own orders and not another company's. Furthermore, Litware allows employees like Rick, who are in the Sales department, to track orders.
Another requirement is that, because Litware is only one of Adatum's many partners that will access the program, Adatum must be able to find out which issuer has the user's credentials. This is called home realm discovery. For more information, see chapter 2, "Claims-Based Architectures."
One assumption for this chapter is that Litware has already deployed an issuer that uses WS-Federation, just as the Adatum issuer does.
WS-Federation is a specification that defines how companies can share identities across security boundaries that have their own authentication and authorization systems. (For more information about WS-Federation, see chapter 2, "Claims-Based Architectures.") This can only happen when legal agreements between Litware and Adatum that protect both sides are already in place. A second assumption is that Litware should be able to decide which of its employees can access the a-Order application.

Overview of the Solution

Once the solution is in place, when Rick logs on to the Litware network, he will access a-Order just as he would a Litware application. From his perspective, that's all there is to it. He doesn't need a special password or user names. It's business as usual. Figure 1 shows the architecture that makes Rick's experience so painless.

Figure 1
Federated identity between Adatum and LitwareAs you can see, there have been two changes to the infrastructure since Adatum instituted SSO. A trust relationship now exists between the Adatum and Litware security domains, and the Adatum issuer has been configured with an additional capability: it can now act as a federation provider (FP). A federation provider grants access to a resource, such as the a-Order application, rather than verifying an identity. When processing a client request, the a-Order application relies on the Adatum issuer. The Adatum issuer, in turn, relies on the Litware issuer that, in this scenario, acts as an identity provider (IP). Of course, the diagram represents just one implementation choice; separating Adatum's IP and FP would also be possible. Keep in mind that each step also uses HTTP redirection through the client browser but, for simplicity, this is not shown in the diagram
The following steps grant access to a user in another security domain:
  1. Rick is using a computer on Litware's network. He is already authenticated with Active Directory. He opens a browser and navigates to the a-Order application. The application is configured to trust Adatum's issuer (the FP). The application has no knowledge of where the request comes from. It redirects Rick's request to the FP.
  2. The FP presents the user with a page listing different identity providers that it trusts. At this point, the FP doesn't know where Rick comes from.
  3. Rick selects Litware from the list and then Adatum's FP redirects him to the Litware issuer to verify that Rick is who he says he is.
  4. Litware's IP verifies Rick's credentials and returns a security token to Rick's browser. The browser sends the token back to the FP. The claims in this token are configured for the Adatum FP and contain information about Rick that is relevant to Adatum. For example, the claims establish his name and that he belongs to the sales organization. The process of verifying the user's credentials may include additional steps such as presenting a logon page and querying Active Directory or, potentially, other attribute repositories.
  5. The Adatum FP validates and reads the security token issued by Litware and creates a new token that can be used by the a-Order application. Claims issued by Litware are transformed into claims that are understood by Adatum's a-Order application. (The mapping rules that translate Litware claims into Adatum claims were determined when Adatum configured its issuer to accept Litware's issuer as an identity provider.)
  6. As a consequence of the claim mappings, Adatum's issuer removes some claims and adds others that are needed for the a-Order application to accept Rick as a user. The Adatum issuer uses browser redirection to send the new token to the application. WIF validates the security token and extracts the claims. It creates a ClaimsPrincipal and assigns it to HttpContext.User. The a-Order application can then access the claims for authorization decisions. For example, in this scenario, orders are filtered by organization, which is provided as a claim.Adatum's issuer, acting as an FP, mediates between the application and the external issuer. You can think of this as a logical role that the Adatum issuer takes on. The FP has two responsibilities. First, it maintains a trust relationship with Litware's issuer, which means that the FP accepts and understands Litware tokens and their claims.
Second, the FP needs to translate Litware claims into claims that a-Order can understand. The a-Order application only accepts claims from Adatum's FP (this is its trusted issuer). In this scenario, a-Order expects claims of type Role in order to authorize operations on its Web site. The problem is that Litware claims don't come from Adatum and they don't have roles. In the scenario, Litware claims establish the employee's name and organizational group. Rick's organization, for example, is Sales. To solve this problem, the FP uses mapping rules that turn a Litware claim into an Adatum claim.
The following table summarizes what happens to input claims from Litware after the Adatum FP transforms them into Adatum output claims.
Input Conditions
Output claims

Claim issuer: Litware
Claim type: Group, Claim value: Sales
Claim issuer: Adatum
Claim type: Role; Claim value: Order Tracker

Claim issuer: Litware
Claims issuer: Adatum
Claim type: Company; Claim value: Litware

Claim issuer: Litware
Claim types name
Claims issuer: Adatum
Copy claim
ADFS 2.0 includes a claims rule language that lets you define the behavior of the issuer when it creates new tokens. What all of these rules generally mean is that if a set of conditions is true, you can issue some claims.
These are the three rules that the Adatum FP uses:
  • => issue(Type = "", Value = "Litware");
In all the rules, the part before the "=>" is the condition that must be true before the rule applies. The part after the "=>" indicates the action to take. This is usually the creation of an additional claim.
The first rule says that the FP will create a claim of type Organization with the value Litware. That is, for this issuer (Litware) it will create that claim. The second rule specifies that if there's a claim of type Group with value Sales, the FP will create a claim of type Role with the value OrderTracker. The third rule copies a claim of type name.
An important part of the solution is home realm discovery. The a-Order application needs to know which issuer to direct users to for authentication. If Rick opens his browser and types, how does a-Order know that Rick can be authenticated by Litware's issuer? The fact is that it doesn't. The a-Order application relies on the FP to make that decision. The a-Order application always redirects users to the FP.
This approach has two potential issues: it discloses information publicly about Litware's relationship with Adatum and it imposes an extra step on users, who might be confused as to which selection is appropriate.
You can resolve these issues by giving the application a hint about the user's home realm. For example, Litware could send a parameter in a query string that specifies the sender's security domain. The application can use this hint to determine the FP's behavior. For more information, see "Home Realm Discovery" in chapter 2, "Claims-Based Architectures."

Benefits and Limitations

Federated identity is an example of how claims support a flexible infrastructure. Adatum can easily add customers by setting up the trust relationship in the FP and by creating the correct claims mappings. Thanks to WIF, dealing with claims in a-Order is straightforward and because Adatum is using ADFS 2.0, creating the claim mapping rules is also fairly simple. Notice that the a-Order application itself didn't change. Also, creating a federation required incremental additions to an infrastructure that was first put in place to implement SSO.
Another benefit is that the claims that Litware issues are about things that make sense within the context of the organization: Litware's employees and their groups. All the identity differences between Litware and Adatum are corrected on the receiving end by Adatum's FP. Litware doesn't need to issue Adatum-specific claims. Although this is technically possible, it can rapidly become difficult and costly to manage as a company adds new relationships and applications.

Inside the Implementation

The Visual Studio solution named 2-Federation found at is an example of how to use federation. The structure of the application is very similar to what you saw in chapter 3, "Claims-Based Single Sign-On for the Web." Adding federated identity did not require recompilation or changes to the Web.config file. Instead, the issuer was configured to act as a federation provider and a trust relationship was established with an issuer that acts as an identity provider. This process is described in the next section. Also, the mock issuers were extended to handle federation provider role.

Setup and Physical Deployment

The Visual Studio solution named 2-Federation on CodePlex is initially configured to run on a stand-alone development machine. The solution includes projects that implement mock issuers for both Litware and Adatum.

Using Mock Issuers for Development and Testing

Mock issuers are helpful for development, demonstration, and testing because they allow the end-to-end application to run on a single host. The WIF SDK includes a Visual Studio template that makes it easy to create a simple issuer class that derives from the SecurityTokenService base class. You then provide definitions for the GetScope and GetOutputClaims methods, as shown in the downloadable code sample that accompanies this scenario.
When the developers at Adatum want to deploy their application, they will modify the configuration so that it uses servers provided by Adatum and Litware. To do this, you need to establish a trust relationship between the Litware and Adatum issuers and modify the a-Order.OrderTracking application's Web.config file for the Adatum issuer.

Establishing Trust Relationships

In the production environment, Adatum and Litware use production-grade security token issuers such as ADFS 2.0. For the scenario to work, you must establish a trust relationship between Adatum's and Litware's issuers. Generally, there are eight steps in this process:
  1. You export a public key certificate for token signing from the Litware issuer and copy Litware's token signing certificate to the file system of the Adatum's issuer host.
  2. You configure Adatum's issuer to recognize Litware as a trusted identity provider.
  3. You configure Litware's issuer to accept requests from the Adatum issuer.
  4. You configure a-Order Tracking application as a relying party within the Adatum issuer.
  5. You edit claims rules in Litware that are specific to the Adatum issuer.
  6. You edit claims transformation rules in the Adatum issuer that are specific to the Litware issuer.
  7. You edit claims rules in the Adatum issuer that are specific to the a-Order Tracking application.You can refer to documentation provided by your production issuer for instructions on how to perform these steps. Instructions for the samples included in this guide can be found at

More Information

For more information about federation and home realm discovery, see "Developer's Introduction to Active Directory Federation Services" at Also see "One does not simply walk into Mordor, or Home Realm Discovery for the Internet" at
For a tool that will help you generate WS-Federation metadata documents, see Christian Weyer's blog at
For more information about the ADFS 2.0 claim rule language, see "Claim Rule Language" at

Last edited Jul 7, 2010 at 5:28 AM by eugeniop, version 1


No comments yet.