Federated Identity for Web Applications

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

Federated identity links independent security realms.

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 were 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 single sign-on capability that Adatum's employees have. However, he doesn't want separate credentials from Adatum just to use a-Order.

Poe Says:
	Adatum does not want to maintain accounts for another company's users of its web application, since maintaining accounts for third-party users can be expensive. Federated identity reduces the cost of account maintenance.

Goals and Requirements

The goal of this scenario is to show how federated identity can make the partnership between Adatum and Litware 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.

In addition to 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.

Bharath Says:
	Security Assertion Markup Language (SAML) is another protocol you might consider for a scenario like this. ADFS 2.0 supports SAMLP.

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.

The application can be modified to accept claims from a partner organization.

Figure 1

Federated identity between Adatum and Litware

As you can see, there have been two changes to the infrastructure since Adatum instituted single sign-on. 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 (IdP). Of course, the diagram represents just one implementation choice; separating Adatum's identity provider and federation provider 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® directory service. He opens a browser and navigates to the a-Order application. The application is configured to trust Adatum's issuer (the federation provider). The application has no knowledge of where the request comes from. It redirects Rick's request to the federation provider.
2. The federation provider presents the user with a page listing different identity providers that it trusts. At this point, the federation provider doesn't know where Rick comes from.

   Bharath says:
   	In the sample code, home realm discovery is explicit, but this approach has caveats. For one, it discloses all of Adatum's partners, and some companies may not want to do this.

   3. Rick selects Litware from the list and then Adatum's federation provider redirects him to the Litware issuer to verify that Rick is who he says he is. 4. Litware's identity provider verifies Rick's credentials and returns a security token to Rick's browser. The browser sends the token back to the federation provider. The claims in this token are configured for the Adatum federation provider 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.

   Bharath says:
   	Notice that Adatum's federation provider is a "relying party" to Litware's identity provider.

   5. The Adatum federation provider 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 created 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. Windows® Identity Foundation (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— the organization name is provided as a claim.

   Jana Says:
   	You can see these steps in more detail in Appendix B. It shows a detailed message sequence diagram for using a browser as the client.

   The Adatum federation provider issuer mediates between the application and the external issuer. You can think of this as a logical role that the Adatum issuer takes on. The federation provider has two responsibilities. First, it maintains a trust relationship with Litware's issuer, which means that the federation provider accepts and understands Litware tokens and their claims.

   Poe Says:
   	Check out the setup and deployment section of the chapter to see how to establish a trust relationship between issuers in separate trust domains.

   Second, the federation provider needs to translate Litware claims into claims that a-Order can understand. The a-Order application only accepts claims from Adatum's federation provider (this is its trusted issuer). In this scenario, a-Order expects claims of type Role in order to authorize operations on its website. 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 federation provider 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 federation provider 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 type: name	Claims issuer: Adatum Claim type: name; Claim Value: Copied from input

   Active Directory Federation Services (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 = "http://schemas.adatum.com/claims/2009/08/organization", Value = "Litware");
   • c:[Type == "https://schemas.xmlsoap.org/claims/Group", Value == "Sales"] => issue(Type = “https://schemas.microsoft.com/ws/2008/06/identity/claims/role", Issuer = c.Issuer, OriginalIssuer = c.OriginalIssuer, Value = "Order Tracker", ValueType = c.ValueType);
   • c:[Type == "https://schemas.xmlsoap.org/ws/2005/05/identity/claims/name"]=> issue(claim = c);

   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 federation provider 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 federation provider 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 http://www.adatum.com/ordertracking, 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 federation provider to make that decision. The a-Order application always redirects users to the federation provider.

   Jana Says:
   	There are no partner-specific details in the a-Order application. Partner details are kept in 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.

   Bharath Says:
   	It also increases the risk of a phishing attack.

   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 federation provider's behavior. For more information, see "Home Realm Discovery" in Chapter 2, "Claims-Based Architectures."

   Markus Says:
   	An issuer can accept the whr parameter as a way to specify someone's home realm.

   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 federation provider and 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 single sign-on.

   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 federation provider. 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.

   Poe Says:
   	Federated identity requires a lot less maintenance and troubleshooting. User accounts don't have to be copied and maintained across security realms.

   Inside the Implementation

   The Microsoft® Visual Studio® development system solution named 2-Federation found at https://claimsid.codeplex.com 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 the federation provider role.

   Adding federated identity to an existing claims-aware application requires only a configuration change.

   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 seven steps in this process:

   Markus Says:
   	Procedures for establishing trust can be automated by using metadata. For example, in ADFS 2.0, you can use the FederationMetadata.xml file if you prefer a more automated approach. The mock issuers provided in the sample code do not provide this metadata.

   1. 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. Configure Adatum's issuer to recognize Litware as a trusted identity provider.
   3. Configure Litware's issuer to accept requests from the Adatum issuer.
   4. Configure the a-Order Tracking application as a relying party within the Adatum issuer.
   5. Edit claims rules in Litware that are specific to the Adatum issuer.
   6. Edit claims transformation rules in the Adatum issuer that are specific to the Litware issuer.
   7. 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 https://claimsid.codeplex.com.

   Questions

   1. Federated identity is best described as:
      1. Two or more applications that share the same set of users.
      2. Two or more organizations that share the same set of users.
      3. Two or more organizations that share an identity provider.
      4. One organization trusting users from one or more other organizations to access its applications.
   2. In a federated security environment, claims mapping is necessary because:
      1. Claims issued by one organization are not necessarily the claims recognized by another organization.
      2. Claims issued by one organization can never be trusted by another organization.
      3. Claims must always be mapped to the roles used in authorization.
      4. Claims must be transferred to a new ClaimsPrincipal object.
   3. The roles of a federation provider can include:
      1. Mapping claims from an identity provider to claims that the relying party understands.
      2. Authenticating users.
      3. Redirecting users to their identity provider.
      4. Verifying that the claims were issued by the expected identity provider.
   4. Must an identity provider issue claims that are specific to a relying party?
      1. Yes
      2. No
      3. It depends.
   5. Which of the following best summarizes the trust relationships between the various parties described in the federated identity scenario in this chapter?
      1. The relying party trusts the identity provider, which in turn trusts the federation provider.
      2. The identity provider trusts the federation provider, which in turn trusts the relying party.
      3. The relying party trusts the federation provider, which in turn trusts the identity provider.
      4. The federation provider trusts both the identity provider and the relying party.

   More Information

   For more information about federation and home realm discovery, see "Developer's Introduction to Active Directory Federation Services" at https://msdn.microsoft.com/en-us/magazine/cc163520.aspx. Also see "One does not simply walk into Mordor, or Home Realm Discovery for the Internet" at https://blogs.msdn.com/vbertocci/archive/2009/04/08/one-does-not-simply-walk-into-mordor-or-home-realm-discovery-for-the-internet.aspx.

   For a tool that will help you generate WS-Federation metadata documents, see Christian Weyer's blog at http://blogs.thinktecture.com/cweyer/archive/2009/05/22/415362.aspx.

   For more information about the ADFS 2.0 claim rule language, see "Claim Rule Language" at https://technet.microsoft.com/en-us/library/dd807118%28WS.10%29.aspx.

   For a simple tool that you can use as a test security token service (STS) that can issue tokens via WS-Federation, see the SelfSTS tool at https://archive.msdn.microsoft.com/SelfSTS.

   Next | Home