Federation Scenario

[Starting with the .NET Framework 4.5, Windows Identity Foundation (WIF) has been fully integrated into the .NET Framework. The version of WIF addressed by this topic, WIF 3.5, is deprecated and should only be used when developing against the .NET Framework 3.5 SP1 or the .NET Framework 4. For more information about WIF in the .NET Framework 4.5, also known as WIF 4.5, see the Windows Identity Foundation documentation in the .NET Framework 4.5 Development Guide.]

This scenario describes a single sign-on experience for a partner employee when she tries to access resources from another partner’s domain. There are three major players in a federation scenario, an identity provider, a claims provider, and a relying party. Windows® Identity Foundation (WIF) offers APIs to build all three players.

The following diagram illustrates a typical federation scenario where a Fabrikam employee wants to access Contoso.com resources without a need to re-login; that is, to use single sign-on.

89a58a75-d05f-4424-ab28-c7ca1fd20ede

The fictional users participating in this scenario are:

  • Frank: A Fabrikam employee who wants to access Contoso resources.

  • Daniel: A Contoso application developer who implements the necessary changes in the application.

  • Adam: The Contoso IT administrator.

The components involved in this scenario are:

  • web1: A parts ordering Web application that is built with ASP.NET and controls access to the relevant parts.

  • sts1: An STS that is in the role of claims provider in Contoso.com and emits claims that are expected by the application (web1). It has established trust with Fabrikam.com and is configured to allow access to Fabrikam employees.

  • sts2: An STS that is in the role of identity provider in Fabrikam.com and provides an end point to which the Fabrikam employee is authenticated. It has established trust with Contoso.com so that Fabrikam employees are allowed to access to the Contoso.com resources.

As shown in the previous diagram, the flow in this scenario is:

  1. Contoso administrator Adam configures the trust between the application (RP) and sts1.

  2. Contoso administrator Adam configures the trust with sts2 as an identity provider.

  3. Fabrikam administrator Frank configures the trust with sts1 as a claims provider and then accesses the application.

Basic Steps Involved in this Scenario

Note that this sample scenario is for illustrative purpose only. The actual steps involved to achieve this scenario in a production environment might differ.

Set Up the Claims Provider

There are three options available for Adam, the Contoso.com administrator:

  1. Install an STS product such as Active Directory® Federation Services (AD FS) 2.0.

  2. Subscribe to a cloud STS product such as LiveID STS.

  3. Build a custom STS using WIF.

Which option he selects depends on several factors, such as the business need, timeline, availability of technical resources, allotted budget, and so on. For this sample scenario, we assume that Adam selects option 1 and installs AD FS 2.0 as the RP-STS, using the AD FS 2.0 product documentation.

Make the Application Claims-Aware

To make web1 a claims-aware application, Daniel installs WIF and then adds the following code to enumerate the claims. For more information, see FedUtil - Federation Utility for Establishing Trust from an RP to an STS, Visual Studio Templates, and Building Relying Party Applications.

// Get the access to IClaimsIdentity
IClaimsIdentity claimsIdentity = ((IClaimsPrincipal)Thread.CurrentPrincipal).Identities[0];

foreach ( Claim claim in claimsIdentity.Claims )
{
// Before using the claims validate that this is an expected claim.
// If it is not in the expected claims list then ignore the claim.
    if ( ExpectedClaims.Contains( claim.ClaimType ) )
    {
// Write out the claim or use the claim as needed by application logic
        WriteClaim( claim, table );
    }
}

Establish Trust from a Relying Party Application to the STS

Using the FedUtil - Federation Utility for Establishing Trust from an RP to an STS tool, Daniel establishes trust from a RP application to the STS. The tool also generates metadata for the RP application and places the xml file (metadata.xml) in the RP application’s folder. The RP application’s web.config file is automatically updated with information about the STS (sts1).

Configure a Relying Party Application at the Claims Provider

By referring to the AD FS 2.0 Product Documentation, Adam establishes trust with the RP application.

Configure an Identity Provider (IP) at Fabrikam

There are three options available for the Fabrikam.com administrator, Frank:

  1. Purchase and install an STS product such as AD FS 2.0.

  2. Subscribe to a cloud STS product such as LiveID STS.

  3. Build a custom STS using WIF.

For this sample scenario, we assume that Frank selects option1 and installs AD FS 2.0 as the IP-STS. By referring to the AD FS 2.0 product documentation, Frank also establishes trust with Contoso.com as a claims provider.

Access the Web Application

Frank logs in to the Fabrikam system as a Fabrikam domain user. He then opens up a browser and accesses the Contoso.com RP application page. With the federation trusts established between Fabrikam and Contoso, Frank can now access the resources at Contoso without a need to re-authenticate.

Sample Resources

For complete end to end scenario samples, see the following samples:

  • End-to-end\Federation for web services (active case).

  • End-to-end\Federation for web app (passive case).

Note that these samples are intended to work on a single system with custom STSes and an RP.