Federated Identity with Multiple Partners

In this chapter, you'll learn about the special considerations that apply to applications that establish many trust relationships. Here you will also see how use the ASP.NET Model View Controller (MVC) framework to build a claims-aware application.

Although the basic building blocks of federated identity—issuers, trust, security tokens and claims—are the same as what you saw in the previous chapter, there are some identity and authorization requirements that are particular to the case of multiple trust relationships.

Special considerations apply when there are many trust relationships.

In some web applications, such as the one shown in this chapter, users and customers represent distinct concepts. A customer of an application can be an organization, and each customer can have many individual users, such as employees. If the application is meant to scale to large numbers of customers, the enrollment process for new customers must be as streamlined as possible. It may even be automated. As with the other chapters, it is easiest to explain these concepts in the context of a scenario.

The Premise

Fabrikam is a company that provides shipping services. As part of its offering, it has a web application named Fabrikam Shipping that allows its customers to perform such tasks as creating shipping orders and tracking them. Fabrikam Shipping is an ASP.NET MVC application that runs in Fabrikam's data center. Fabrikam's customers want their employees to use a browser to access the shipping application.

Fabrikam has made its new shipping application claims-based. Like many design choices, this one was customer-driven. In this case, Fabrikam signed a deal with a major customer, Adatum. Adatum's corporate IT strategy (as discussed in chapter 3, "Claims-Based Single Sign-On for the Web") calls for the eventual elimination of identity silos. Adatum wants its users to access Fabrikam Shipping without presenting separate user names and passwords. Fabrikam also signed agreements with Litware that had similar requirements. However, Fabrikam also wants to support smaller customers, such as Contoso, that do not have the infrastructure in place to support federated identity.

Goals and Requirements

Larger customers such as Adatum and Litware have some particular concerns. These include the following:

• Usability. They would prefer if their employees didn't need to learn new passwords and user names for Fabrikam Shipping. These employees shouldn't need any credentials other than the ones they already have, and they shouldn't have to enter credentials a second time when they access Fabrikam Shipping from within their security domain.
• Support. It is easier for Adatum and Litware to manage issues such as forgotten passwords than to have employees interact with Fabrikam.
• Liability. There are reasons why Adatum and Litware have the authentication and authorization policies that they do. They want to control who has access to resources, no matter where those resources are deployed, and Fabrikam Shipping is no exception. If an employee leaves the company, he or she should no longer have access to the application.

Fabrikam has its own goals, which are the following:

• To delegate the responsibility for maintaining user identities to its customers, when possible. This avoids a number of problems, such as having to synchronize data between Fabrikam and its customers. The contact information for a package's sender is an example of this kind of information. Its accuracy should be the customer's responsibility because it could quickly become costly for Fabrikam to keep this information up to date.
• To bill customers by cost center if one is supplied. Cost centers should be provided by the customers. This is also another example of information that is the customer's responsibility.
• To sell its services to a large number of customers. This means that the process of enrolling a new company must be streamlined. Fabrikam would also prefer that its customers self-manage the application whenever possible.
• To provide the infrastructure for federation if a customer cannot. Fabrikam wants to minimize the impact on the application code that might arise from having more than one authentication mechanism for customers.

Overview of the Solution

With the goals and requirements in place, it's time to look at the solution. As you saw in Chapter 4, "Federated Identity for Web Applications," the solution includes the establishment of a claims-based architecture with an issuer that acts as an identity provider (IdP) on the customers' side. In addition, the solution includes an issuer that acts as the federation provider (FP) on Fabrikam's side. Recall that a federation provider acts as a gateway between a resource and all of the issuers that provide claims about the resource's users.

Figure 1 shows Fabrikam's solution for customers that have their own identity provider.

Figure 1

Fabrikam Shipping for customers with an identity provider

Here's an example of how the system works. The steps correspond to the numbers in the preceding illustration.

Step 1: Present Credentials to the Identity Provider

1. When John from Adatum attempts to use Fabrikam Shipping for the first time (that is, when he first navigates to https://{fabrikam host}/f-shipping/adatum), there's no session established yet. In other words, from Fabrikam's point of view, John is unauthenticated. The URL provides the Fabrikam Shipping application with a hint about the customer that is requesting access (the hint is "adatum" at the end of the URL).
2. The application redirects John's browser to Fabrikam's issuer (the federation provider). That is because Fabrikam's federation provider is the application's trusted issuer. As part of the redirection URL, the application includes the whr parameter that provides a hint to the federation provider about the customer's home realm. The value of the whr parameter is http://adatum/trust.
3. Fabrikam's federation provider uses the whr parameter to look up the customer's identity provider and redirect John's browser back to the Adatum issuer.

   Markus Says:
   In this scenario, discovering the home realm is automated. There's no need for the user to provide it, as was shown in Chapter 4, "Federated Identity for Web Applications."

   4. Assuming that John uses a computer that is already a part of the domain and in the corporate network, he will already have valid network credentials that can be presented to Adatum's identity provider. 5. Adatum's identity provider uses John's credentials to authenticate him and then issue a security token with a set of Adatum's claims. These claims are the **employee name**, the **employee address**, the **cost center**, and the **department**.  

   Step 2: Transmit the Identity Provider's Security Token to the Federation Provider

   1. The identity provider uses HTTP redirection to redirect the security token it has issued to Fabrikam's federation provider.
   2. Fabrikam's federation provider receives this token and validates it.

   Step 3: Map the Claims

   1. Fabrikam's federation provider applies token mapping rules to the identity provider's security token. The claims are transformed into something that Fabrikam Shipping understands.
   2. The federation provider uses HTTP redirection to submit the claims to John's browser.

   Step 4: Transmit the Mapped Claims and Perform the Requested Action

   1. The browser sends the federation provider's security token, which contains the transformed claims, to the Fabrikam Shipping application.
   2. The application validates the security token.
   3. The application reads the claims and creates a session for John.

   Because this is a web application, all interactions happen through the browser. (See Appendix B for a detailed description of the protocol for a browser-based client.)

   The principles behind these interactions are exactly the same as those described in Chapter 4, "Federated Identity for Web Applications." One notable exception is Fabrikam's automation of the home realm discovery process. In this case, there's no user intervention necessary. The home realm is entirely derived from information passed first in the URL and then in the whr parameter.

   Automated home realm discovery is important when there are many trust relationships.

   Litware follows the same steps as Adatum. The only differences are the URLs used (http://{fabrikam host}/f-shipping/litware and the Litware identity provider's address) and the claims mapping rules, because the claims issued by Litware are different from those issued by Adatum. Notice that Fabrikam Shipping trusts the Fabrikam federation provider, not the individual issuers of Litware or Adatum. This level of indirection isolates Fabrikam Shipping from individual differences between Litware and Adatum.

   Fabrikam also provides identity services on behalf of customers such as Contoso that do not have issuers of their own. Figure 2 shows how Fabrikam implemented this.

   

   Figure 2

   Fabrikam Shipping for customers without an identity provider

   Contoso is a small business with no identity infrastructure of its own. It doesn't have an issuer that Fabrikam can trust to authenticate Contoso's users. It also doesn't care if its employees need a separate set of credentials to access the application.

   Smaller organizations may not have their own issuers.

   Fabrikam has deployed its own identity provider to support smaller customers such as Contoso. Notice, however, that even though Fabrikam owns this issuer, it's treated as if it were an external identity provider, just as those that belong to Adatum and Litware. In a sense, Fabrikam "federates with itself."

   Because the identity provider is treated as an external issuer, the process is the same as that used by Adatum and Litware. The only differences are the URLs and the claim mappings.

   Note

   By deploying an identity provider for customers such as Contoso, Fabrikam accepts the costs associated with maintaining accounts for remote users (for example, handling password resets). The benefit is that Fabrikam only has to do this for customers that don't have their own federation infrastructure. Over time, Fabrikam expects to have fewer customers that need this support.
   It would also be possible for Fabrikam to support third-party identity providers such as LiveID or OpenID as a way to reduce the cost of maintaining passwords for external users.

   Using Claims in Fabrikam Shipping

   Fabrikam Shipping uses claims for two purposes. It uses role claims to control access and it also uses claims to retrieve user profile information.

   Fabrikam uses claims for access control and for user profiles.

   Access control to Fabrikam Shipping is based on one of three roles:

   • Shipment Creator. Anyone in this role can create new orders.
   • Shipment Manager. Anyone in this role can create and modify existing shipment orders.
   • Administrator. Anyone in this role can configure the system. For example, they can set shipping preferences or change the application's appearance and behavior ("look and feel").

   The sender's address and the sender's cost center for billing are the pieces of profile information that Fabrikam Shipping expects as claims. The cost center allows Fabrikam to provide more detailed invoices. For example, two employees from Adatum who belong to two different departments would get two different bills.

   Fabrikam configures claims mappings for every new customer that uses Fabrikam Shipping. This is necessary because the application logic within Fabrikam Shipping only understands one set of role claims, which includes Shipment Creator, Shipment Manager, and Administrator. By providing these mappings, Fabrikam decouples the application from the many different claim types that customers provide.

   The following table shows the claims mappings for each customer. Claims that represent cost centers, user names, and sender addresses are simply copied. They are omitted from the table for brevity.

   Partner	Input conditions	Output claims
   Adatum	Claim issuer: Adatum Claim type: Group, Claim value: CustomerService	Claim issuer: Fabrikam Claim type: Role, Claim value: Shipment Creator
   	Claim issuer: Adatum Claim type: Group, Claim value: OrderFulfillments	Claim issuer: Fabrikam Claim type: Role, Claim value: Shipment Creator
   		Claim issuer: Fabrikam Claim type: Role, Claim value: Shipment Manager
   	Claim issuer: Adatum Claim type: Group, Claim value: Admins	Claim issuer: Fabrikam Claim type: Role, Claim value: Administrator
   	Claim issuer: Adatum	Claim issuer: Fabrikam Claim type: Organization, Claim value: Adatum
   Litware	Claim issuer: Litware Claim type: Group, Claim value: Sales	Claim issuer: Fabrikam Claim type: Role, Claim value: Shipment Creator
   	Claim issuer: Litware	Claim issuer: Fabrikam Claim type: Organization, Claim value: Litware
   Contoso	Claim issuer: Fabrikam identity provider Claim type: e-mail, Claim value: bill@contoso.com	Claim issuer: Fabrikam Claim type: Role, Claim value: Shipment Creator
   		Claim issuer: Fabrikam Claim type: Role, Claim value: Shipment Manager
   		Claim issuer: Fabrikam Claim type: Role, Claim value: Administrator
   		Claim issuer: Fabrikam Claim type: Organization, Claim value: Contoso

   Note

   As in Chapter 4, "Federated Identity for Web Applications," Adatum could issue Fabrikam-specific claims, but it would not be a best practice to clutter Adatum's issuer with Fabrikam-specific concepts such as Fabrikam roles. Fabrikam allows Adatum to issue any claims it wants, and then it configures its federation provider to map these Adatum claims to Fabrikam claims.

   Inside the Implementation

   Now is a good time to walk through some of the details of the solution. As you go through this section, you may want to download the Microsoft® Visual Studio® development system solution 3FederationWithMultiplePartners from https://claimsid.codeplex.com. If you are not interested in the mechanics, you should skip to the next section.

   The Fabrikam Shipping application uses the ASP.NET MVC framework in conjunction with the Windows® Identify Foundation (WIF). The application's Web.config file contains the configuration information, as shown in the following XML code. The <system.webServer> section of the Web.config file references WIF-provided modules and the ASP.NET MVC HTTP handler class. The WIF information is the same as it was in the previous scenarios. The MVC HTTP handler is in the <handlers> section.

   Fabrikam Shipping is an ASP.NET MVC application that uses claims.

   <system.webServer>
     ...
     <modules runAllManagedModulesForAllRequests="true">
       ...
       <add name="WSFederationAuthenticationModule" 
            preCondition=" integratedMode"   
            type="Microsoft.IdentityModel.Web.
                         WSFederationAuthenticationModule, ..." />
    
      <add name="SessionAuthenticationModule" 
            preCondition=" integratedMode"    
            type="Microsoft.IdentityModel.Web.
                              SessionAuthenticationModule, ..." />
     </modules>
     <handlers>
       ...
       <add name="MvcHttpHandler" 
            preCondition="integratedMode" 
            verb="*" 
            path="*.mvc" 
            type="System.Web.Mvc.MvcHttpHandler, ..."/>
       ...
     </handlers>
   </system.webServer>
   

   Jana Says:
   	Fabrikam chose ASP.NET MVC because it wanted improved testability and a modular architecture. They considered these qualities important for an application with many customers and complex federation relationships.

   Note

   Fabrikam Shipping is an example of the finer-grained control that's available with the WIF API. Although Fabrikam Shipping demonstrates how to use MVC with WIF, it's not the only possible approach. Also, WIF-supplied tools, such as FedUtil.exe, are not currently fully integrated with MVC applications. For now, you can edit sections of the configuration files after applying the FedUtil program to an MVC application. This is what the developers at Fabrikam did with Fabrikam Shipping.

   Fabrikam Shipping needs to customize the redirection of HTTP requests to issuers in order to take advantage of the ASP.NET MVC architecture. It does this by turning off automatic redirection from within WIF's federated authentication module. This is shown in the following XML code:

   <federatedAuthentication>
      <wsFederation passiveRedirectEnabled="false" 
        issuer="https://{fabrikam host}/{issuer endpoint}/" 
        realm="https://{fabrikam host}/f-Shipping/FederationResult" 
        requireHttps="true" 
      />
      <cookieHandler requireSsl="true" path="/f-Shipping/" />
   </federatedAuthentication>
   

   Bharath Says:
   	If you set passiveRedirectEnabled to false, WIF will no longer be responsible for the redirections to your issuers. You will have complete control of these interactions.

   By setting the passiveRedirectEnabled attribute to false, you instruct WIF's federated authentication module not to perform its built-in redirection of unauthenticated sessions to the issuer. For example, Fabrikam Shipping uses the WIF API to perform this redirection under programmatic control.

   ASP.NET MVC applications include the concept of route mappings and controllers that implement handlers. A route mapping enables you to define URL mapping rules that automatically dispatch incoming URLs to application-provided action methods that process them. (Outgoing URLs are also processed.)

   The following code shows how Fabrikam Shipping establishes a routing table for incoming requests such as "http://{fabrikam host}/f-shipping/adatum". The last part of the URL is the name of the organization (that is, the customer). This code is located in Fabrikam Shipping's Global.asax file.

   public class MvcApplication : System.Web.HttpApplication
   {
     // ...
     public static void RegisterRoutes(RouteCollection routes)
     {     
       // ...       
       routes.MapRoute(
            "OrganizationDefault",
            "{organization}/",
            new { controller = "Shipment", action = "Index" });
     }
       // ...
   }
   

   Markus Says:
   	There's a lot of good information about APS.NET MVC concepts at https://www.asp.net.

   The RegisterRoutes method allows the application to tell the ASP.NET MVC framework how URIs should be mapped and handled in code. This is known as a routing rule.

   When an incoming request such as "http://{fabrikam host}/f-Shipping/adatum" is received, the MVC framework evaluates the routing rules to determine the appropriate controller object that should handle the request. The incoming URL is tested against each route rule. The first matching rule is then used to process the request. In the case of the "f-Shipping/adatum" URL, an instance of the application's ShipmentController class will be used as the controller, and its Index method will be the action method.

   [AuthenticateAndAuthorize(Roles = "Shipment Creator")]
   public class ShipmentController : BaseController
   {
      public ActionResult Index()
      {
         // ...
      }
   }
   

   The ShipmentController class has been decorated with a custom attribute named AuthenticateAndAuthorize. This attribute is implemented by the Fabrikam Shipping application. Here is the declaration of the attribute class.

   [AttributeUsage(AttributeTargets.Class | AttributeTargets.Method)]
   public sealed class AuthenticateAndAuthorizeAttribute : 
                          FilterAttribute, IAuthorizationFilter
   {
     // ...
   
     public void OnAuthorization(AuthorizationContext filterContext)
     {
       if (!filterContext.HttpContext.Request.IsSecureConnection) 
       { 
          throw /* ... */ 
       }
   
       if (!filterContext.HttpContext.User.Identity.IsAuthenticated)
       {
         AuthenticateUser(filterContext);
       }
       else
       {
         this.AuthorizeUser(filterContext);
       }
   
     // ...
   } 
   

   The AuthenticateAndAuthorizeAttribute class derives from the FilterAttribute class and implements the IAuthorizationFilter interface. Both these types are provided by ASP.NET MVC. The MVC framework recognizes these attribute types when they are applied to controller classes and it calls the OnAuthorization method before each controller method is invoked. The OnAuthorization method detects whether or not authentication has been performed already, and if it hasn't, it invokes the AuthenticateUser helper method to contact the application's federation provider by HTTP redirection. The following code shows how this happens.

   private static void AuthenticateUser(AuthorizationContext context)
   {
     var organizationName = 
                   (string)context.RouteData.Values["organization"];
   
     if (!string.IsNullOrEmpty(organizationName))
     {
       if (!IsValidTenant(organizationName)) { throw /* ... */ }
                 
       var returnUrl = GetReturnUrl(context.RequestContext);
   
       var fam = 
           FederatedAuthentication.WSFederationAuthenticationModule;
   
       var signIn = 
           new SignInRequestMessage(new Uri(fam.Issuer), fam.Realm)
           {
             Context = returnUrl.ToString(),
             HomeRealm =RetrieveHomeRealmForTenant(organizationName)
           };
   
       context.Result = 
                     new RedirectResult(signIn.WriteQueryString());
     }
   }
   

   Bharath Says:
   	To keep your app secure and avoid attacks such as SQL injection, you should verify all values from an incoming URL.

   The AuthenticateUser method takes the customer's name from the route table. (The code refers to a customer as an organization.) In this example, "adatum" is the customer. Next, the method checks to see if the customer has been enrolled in the Fabrikam Shipping application. If not, it raises an exception.

   Then, the AuthenticateUser method looks up the information it needs to create a federated sign-in request. This includes the URI of the issuer (that is, Fabrikam's federation provider), the application's realm (the address where the issuer will eventually return the security token), the URL that the user is trying to access, and the home realm designation of the customer. The method uses this information to create an instance of WIF's SignInRequestMessage class. An instance of this class represents a new request to an issuer to authenticate the current user.

   In the underlying WS-Federation protocol, these pieces of information correspond to the parameters of the request message that will be directed to Fabrikam's federation provider. The following table shows this correspondence.

   Parameter	Name	Contents
   wrealm	Realm	This identifies the Fabrikam Shipping application to the federation provider. This parameter comes from the Web.config file and is the address to which a token should be sent.
   wctx	Context	This parameter is set to the address of the original URL requested by the user. This parameter is not used by the issuer, but all issuers in the chain preserve it for the Fabrikam Shipping application, allowing it to send the user to his or her original destination.
   whr	Home realm	This parameter tells Fabrikam's federation provider that it should use Adatum's issuer as the identity provider for this request.

   The GetReturnUrl method is a locally defined helper method that gives the URL that the user is trying to access. An example is http://{fabrikam host}/f-shipping/adatum/shipment/new.

   After using the WIF API to construct the sign-on request message, the method configures the result for redirection.

   At this point, ASP.NET will redirect the user's browser to the federation provider. In response, the federation provider will use the steps described in the Chapter 3, "Claims-Based Single Sign-On for the Web," and Chapter 4, "Federated Identity for Web Applications," to authenticate the user. This will include additional HTTP redirection to the identity provider specified as the home realm. Unlike the previous examples in this guide, the federation provider in this example uses the whr parameter sent by the application to infer the address of the customer's identity provider. After the federation provider receives a security token from the identity provider and transforms it into a token with the claim types expected by Fabrikam Shipping, it will POST it to the wrealm address that was originally specified. This is a special URL configured with the SignInRequestMessage class in the AuthenticateAndAuthorizeAttribute filter. In the example, the URL will be f-shipping/FederationResult.

   The MVC routing table is configured to dispatch the POST message to the FederationResult action handler defined in the HomeController class of the Fabrikam Shipping application. This method is shown in the following code.

   [ValidateInput(false)]
   [AcceptVerbs(HttpVerbs.Post)]
   
   public ActionResult FederationResult(string wresult)
   {
     var fam = 
           FederatedAuthentication.WSFederationAuthenticationModule;
     if (fam.CanReadSignInResponse(
                      System.Web.HttpContext.Current.Request, true))
     {
       string returnUrl = this.GetReturnUrlFromCtx();
   
       return new RedirectResult(returnUrl);
     }
   
     // ...
   }
   

   Notice that this controller does not have the AuthenticateAndAuthorize attribute applied. However, the token POSTed to this address is still processed by the WIF Federation Authentication Module because of the explicit redirection of the return URL.

   The FederationResult action handler uses the helper method GetReturnUrlFromCtx to read the wctx parameter that contains the original URL requested by the user. This is simply a property lookup operation: this.HttpContext.Request.Form["wctx"]. Finally, it issues a redirect request to this URL.

   The ValidateInput custom attribute is required for this scenario because the body of the POST contains a security token serialized as XML. If this custom attribute were not present, ASP.NET MVC would consider the content of the body unsafe and therefore raise an exception.

   The application then processes the request a second time, but in this pass, there is an authenticated user. The OnAuthorization method described earlier will again be invoked, except this time it will pass control to the AuthorizeUser helper method instead of the AuthenticateUser method as it did in the first pass. The definition of the AuthorizeUser method is shown in the following code.

   private void AuthorizeUser(AuthorizationContext context)
   {
     var organizationRequested = 
        (string)context.RouteData.Values["organization"];
     var userOrganiation = 
        ClaimHelper.GetCurrentUserClaim(
             Fabrikam.ClaimTypes.Organization).Value;
               
     if (!organizationRequested.Equals(userOrganiation,  
                        StringComparison.OrdinalIgnoreCase))
     {
       context.Result = new HttpUnauthorizedResult();
       return;
     }
   
     var authorizedRoles = this.Roles.Split(new[] { "," }, 
                             StringSplitOptions.RemoveEmptyEntries);
     bool hasValidRole = false;
     foreach (var role in authorizedRoles)
     {
       if (context.HttpContext.User.IsInRole(role.Trim()))
       {
         hasValidRole = true;
         break;
       }
     }
   
     if (!hasValidRole)
     {
       context.Result = new HttpUnauthorizedResult();
       return;
     }
   }
   

   The AuthorizeUser method checks the claims that are present for the current user. It makes sure that the customer identification in the security token matches the requested customer as given by the URL. It then checks that the current user has one of the roles required to run this application.

   Note

   Because this is a claims-aware application, you know that the user object will be of type IClaimsPrincipal even though its static type is IPrincipal. However, no run-time type conversion is needed in this case. The reason is that the code only checks for role claims, and these operations are available to instances that implement the IPrincipal interface.
   If you want to extract any other claims from the principal, you will need to cast the User property to IClaimsPrincipal first. This is shown in the following code.
   var claimsprincipal =
   context.HttpContext.User as IClaimsPrincipal;

   If the user has a claim that corresponds to one of the permitted roles (defined in the AuthenticateAndAuthorizeAttribute class), the AuthorizeUser method will return without setting a result in the context. This allows the original action request method to run.

   In the scenario, the original action method is the Index method of the ShipmentController class. The method's definition is given by the following code example.

   [AuthenticateAndAuthorize(Roles = "Shipment Creator")]
   public class ShipmentController : BaseController
   {
      public ActionResult Index()
      {
        var repository = new ShipmentRepository();
   
        IEnumerable<Shipment> shipments;
        var organization = 
            ClaimHelper.GetCurrentUserClaim(                              
                            Fabrikam.ClaimTypes.Organization).Value;
   
        if (this.User.IsInRole(Fabrikam.Roles.ShipmentManager))
        {
          shipments = 
                repository.GetShipmentsByOrganization(organization);
        }
        else
        {
          var userName = this.User.Identity.Name;
          shipments = 
             repository.GetShipmentsByOrganizationAndUserName(
                                            organization, userName);    
        }
   
        var model = 
             new ShipmentListViewModel { Shipments = shipments };
   
        return View(model);
      }
    // ...
   }
   

   The Index action handler retrieves the data that is needed to satisfy the request from the application's data store. Its behavior depends on the user's role, which it extracts from the current claims context. It passes control to the controller's View method for rendering the information from the repository into HTML.

   Setup and Physical Deployment

   Applications such as Fabrikam Shipping that use federated identity with multiple partners sometimes rely on automated provisioning and may allow for customer-configurable claims mapping. The Fabrikam Shipping example does not implement automated provisioning, but it includes a prototype of a web interface as a demonstration of the concepts.

   Automated provisioning may be needed when there are many partners.

   Establishing the Trust Relationship

   If you were to implement automated provisioning, you could provide a web form that allows an administrator from a customer's site to specify a URI of an XML document that contains federation metadata for ADFS 2.0. Alternatively, the administrator could provide the necessary data elements individually.

   If your application's federation provider is an ADFS 2.0 server, you can use Windows PowerShell® scripts to automate the configuration steps. For example, the ADFSRelyingParty command allows you to programmatically configure ADFS to issue security tokens to particular applications and federation providers. Look on MSDN® for the ADFS 2.0 commands that you can use in your PowerShell scripts.

   Note

   Processing a federation request might initiate a workflow process that includes manual steps such as verifying that a contract has been signed. Both manual and automated steps are possible, and of course, you would first need to authenticate the request for provisioning.

   If you automate provisioning with a federation metadata XML file, this file would be provided by a customer's issuer. In the following example, you'll see the federation metadata file that is provided by Adatum. The file contains all the information that Fabrikam Shipping would need to configure and deploy its federation provider to communicate with Adatum's issuer. Here are the important sections of the file.

   Organization Section

   The organization section contains the organization name.

   <Organization>
     <OrganizationDisplayName xml:lang="">
        Adatum
     </OrganizationDisplayName>
     <OrganizationName xml:lang="">Adatum</OrganizationName>
     <OrganizationURL xml:lang="">
        http://{adatum host}/Adatum.Portal/
     </OrganizationURL>
   </Organization> 
   

   Issuer Section

   The issuer section contains the issuer's URI.

   <fed:SecurityTokenServiceEndpoint>
       <EndpointReference 
           xmlns="http://www.w3.org/2005/08/addressing">
           <Address>
               https://{adatum host}/{issuer endpoint}/
           </Address>
   …
       </EndpointReference>
   </fed:SecurityTokenServiceEndpoint> 
   

   Certificate Section

   The certificate section contains the certificate (encoded in base64) that is used by the issuer to sign the tokens.

   <RoleDescriptor ...>
       <KeyDescriptor use="signing">
           <KeyInfo xmlns="http://www.w3.org/2000/09/xmldsig#">
               <X509Data>
                  <X509Certificate>
                       MIIB5TCCAV ... Ukyey2pjD/R4LO2B3AO
                   </X509Certificate>
               </X509Data>
           </KeyInfo>
       </KeyDescriptor>
   </RoleDescriptor> 
   

   After Adatum registers as a customer of Fabrikam Shipping, the customer's systems administrators must also configure their issuer to respond to requests from Fabrikam's federation provider. For ADFS 2.0, this process is identical to what you saw in Chapter 4, "Federated Identity for Web Applications," when the Litware issuer began to provide claims for the a-Order application.

   User-Configurable Claims Transformation Rules

   It's possible for applications to let customers configure the claims mapping rules that will be used by the application's federation provider. You would do this to make it as easy as possible for an application's customers to use their existing issuers without asking them to produce new claim types. If a customer already has roles or groups, perhaps from Microsoft Active Directory, that are ready to use, it is convenient to reuse them. However, these roles would need to be mapped to roles that are understood by the application.

   An application with many partners may require user-configurable claims transformation rules.

   If the federation provider is an ADFS 2.0 server, you can use Windows PowerShell scripts to set up the role mapping rules. The claims mapping rules would be different for each customer.

   Questions

   1. In the scenario described in this chapter, who should take what action when an employee leaves one of the partner organizations such as Litware?
      1. Fabrikam Shipping must remove the user from its user database.
      2. Litware must remove the user from its user database.
      3. Fabrikam must amend the claims-mapping rules in its federation provider.
      4. Litware must ensure that its identity provider no longer issues any of the claims that get mapped to Fabrikam Shipping claims.
   2. In the scenario described in this chapter, how does Fabrikam Shipping perform home realm discovery?
      1. Fabrikam Shipping presents unauthenticated users with a list of federation partners to choose from.
      2. Fabrikam Shipping prompts unauthenticated users for their email addresses. It parses this address to determine which organization the user belongs to.
      3. Fabrikam Shipping does not need to perform home realm discovery because users will have already authenticated with their organizations' identity providers.
      4. Each partner organization has its own landing page in Fabrikam Shipping. Visiting that page will automatically redirect unauthenticated users to that organization's identity provider.
   3. Fabrikam Shipping provides an identity provider for its smaller customers who do not have their own identity provider. What are the disadvantages of this?
      1. Fabrikam must bear the costs of providing this service.
      2. Users at smaller customers will need to remember another username and password.
      3. Smaller customers must rely on Fabrikam to manage their user's access to Fabrikam Shipping.
      4. Fabrikam Shipping must set up a trust relationship with all of its smaller customers.
   4. How does Fabrikam Shipping ensure that only users at a particular partner can view that partner's shipping data?
      1. The Fabrikam Shipping application examines the email address of the user to determine the organization they belong to.
      2. Fabrikam Shipping uses separate databases for each partner. Each database uses different credentials to control access.
      3. Fabrikam shipping uses the role claim from the partner's identity provider to determine whether the user should be able to access the data.
      4. Fabrikam shipping uses the organization claim from its federation provider to determine whether the user should be able to access the data.
   5. The developers at Fabrikam set the wsFederationpassiveRedirectEnabled attribute to false. Why?
      1. This scenario uses active redirection, not passive redirection.
      2. They wanted more control over the redirection process.
      3. Fabrikam Shipping is an MVC application.
      4. They needed to be able to redirect to external identity providers.

   Next | Home