Federated Identity with Multiple Partners and Microsoft Azure Access Control Service

In Chapter 6, "Federated Identity with Multiple Partners," you saw how Fabrikam used claims to enable access to the Fabrikam shipping application for multiple partners. The scenario described how Fabrikam supported users at large partner organizations with their own claims-based identity infrastructure, and users from smaller organizations with no claims-based infrastructure of their own. Fabrikam provided support for the larger partner organizations by establishing trust relationships between the Fabrikam federation provider (FP) and the partner's identity provider (IdP). To support the smaller organizations, it was necessary for Fabrikam to implement its own identity provider and manage the collection of enrolled employees from smaller partners. This scenario also demonstrated how Fabrikam had taken steps to automate the enrollment process for new partners.

Users at smaller partners had to create new accounts at Fabrikam, adding to the list of credentials they have to remember. Many individuals would prefer to reuse an existing identity rather than create a new one just to use the Fabrikam Shipping application. How can Fabrikam enable users to reuse existing identities such as Facebook IDs, Google IDs, or Windows Live® IDs? In addition to establishing trust relationships with the social identity providers, Fabrikam must find solutions to these problems:

• Other identity providers may use different protocols to exchange claims data.
• Other identity providers may use different claim types.
• Fabrikam Shipping must be able to use the claims data it receives to implement authorization rules.
• The federation provider must be able to redirect users to the correct identity provider.
• Fabrikam must be able to enroll new users who want to use the Fabrikam Shipping application.

In Chapter 5, "Federated Identity with Microsoft Azure Access Control Services," you saw how Adatum extended access to the a-Order application to include users who wanted to use their social identity to authenticate with the a-Order application. In this chapter, you'll see how Fabrikam replaced its on-premises federation provider with Azure™ AppFabric Access Control services (ACS), to enable users at smaller organizations without their own identity infrastructure to access Fabrikam Shipping.

You can use ACS to manage multiple trust relationships.

Unlike the scenario described in Chapter 5, "Federated Identity with Microsoft Azure Access Control Services," users from smaller partners who use social identity providers will be able to enroll themselves with the Fabrikam Shipping application. They will access the Fabrikam Shipping application alongside employees of existing enterprise partners. This chapter extends the scenario described in Chapter 6, "Federated Identity with Multiple Partners."

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 the Fabrikam data center.

Fabrikam has already claims-enabled the Fabrikam Shipping web application, allowing employees from Adatum and Litware to access the application without having to present separate usernames and passwords. Users at Contoso, a smaller partner, can also access Fabrikam Shipping, but they must log in using credentials that the Fabrikam identity provider, Active Directory® Federation Services (ADFS) 2.0, authenticates. Users at Contoso have complained about the fact that they must remember a set of credentials specifically for accessing the Fabrikam Shipping application. All of Contoso's employees have either Windows® Live IDs or Google accounts, and they would prefer to use these credentials to gain access to the application. Users at other Fabrikam customers have echoed this request, mentioning Facebook IDs and Yahoo! IDs as additional credential types they would like to be able to use.

Poe Says:
	Managing the accounts for users at organizations such as Contoso adds to the complexity of the Fabrikam ADFS implementation.

Goals and Requirements

The primary goal of this scenario is to show how Fabrikam can use ACS as a federation provider to enable both employees of large partners such as Adatum and Litware, and smaller partners whose employees use identities from with social identity providers, to access the Fabrikam Shipping application.

To recap from Chapter 6, "Federated Identity with Multiple Partners," 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. The solution described in Chapter 6, "Federated Identity with Multiple Partners," addresses this concern and introducing ACS as a federation provider must not change the user experience for the employees of these customers.
• Support. It is easier for Adatum and Litware to manage issues such as forgotten passwords than to have their employees interact with Fabrikam. The solution described in Chapter 6, "Federated Identity with Multiple Partners," addresses this concern and introducing ACS as a federation provider must not change the user experience for the security administrators of these customers.
• Liability. There are reasons why Adatum and Litware have the authentication and authorization policies that they have. They want to control who has access to their 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. Again, the solution described in Chapter 6, "Federated Identity with Multiple Partners," addresses this concern.
• Confidentiality. Partners of Fabrikam, such as Adatum, do not want other partners, such as Litware, to know that they are using the Fabrikam Shipping service. When a user accesses the Fabrikam Shipping site, they should not have to choose from a list of available authentication partners; rather, the site should automatically redirect them to the correct identity provider without revealing a list of partners.

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 data. Its accuracy should be the customer's responsibility because it could quickly become costly for Fabrikam to keep this information up to date. The solution described in Chapter 6, "Federated Identity with Multiple Partners," addresses this concern.
• To bill customers by cost center if one is supplied. Customers should provide the cost center information. This is another example of information that is the customer's responsibility. The solution described in Chapter 6, "Federated Identity with Multiple Partners," addresses this concern.
• 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. The automated enrollment process must be able to support both large organizations with their own identity infrastructure, and smaller organizations whose employees use a social identity provider. Furthermore, Fabrikam would like to support the widest possible range of social identity providers.
• 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. However, Fabrikam would prefer not to have to maintain an on-premises identity provider for smaller customers. Instead, it would like users at smaller customers to use existing social identities.

Smaller customers and individual users have some particular concerns. These include the following:

• Usability. Individual users would prefer to use existing identities such as Windows Live IDs or Google account credentials to access the Fabrikam Shipping website instead of having to create a new user ID and password just to access this site.
• Support. If individual users forget their passwords, they would like to be able to use the password recovery tools provided by their social identity provider rather than interacting with Fabrikam.
• Privacy. Individual users do not want their social identity provider to reveal to Fabrikam private information maintained by the social identity provider that is not relevant to the Fabrikam shipping application.

Bharath Says:
	Fabrikam must be careful to explain to individual users the implications of allowing their social identity provider to release details to ACS and be clear about exactly what information Fabrikam Shipping and ACS will be able to access.

Overview of the Solution

With the goals and requirements in place, it's time to look at the solution. As you saw in Chapter 6, "Federated Identity with Multiple Partners," the solution includes the establishment of a claims-based architecture with issuers that act as an identity providers on the customers' side. In addition, the solution includes an issuer that acts as the federation provider on the Fabrikam 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. In this chapter, Fabrikam replaces the on-premises federation provider with ACS in order to support authenticating users with social identities. This change also means that Fabrikam no longer has to host and manage a federation provider in its own datacenter.

Figure 1 shows the Fabrikam Shipping solution using ACS.

Figure 1

Fabrikam Shipping using ACS

Here's an example of how the system works for a user at an organization such as Adatum with its own identity provider. This process is similar, but not identical to the process described in Chapter 6, "Federated Identity with Multiple Partners." The steps correspond to the shaded numbers in the preceding illustration.

Jana Says:
	In the solution described in Chapter 6, "Federated Identity with Multiple Partners," Fabrikam used an on-premises federation provider (FP). Now Fabrikam is using ACS in the cloud instead.

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 the Fabrikam ACS instance in the cloud (the federation provider). That's because the Fabrikam ACS instance is the application's trusted issuer. As part of the redirection URL, the application includes the whr parameter that provides a hint to ACS about the customer's home realm. The value of the whr parameter is https://localhost/Adatum.SimulatedIssuer.7/.

   Note

   It's important to use the entityID value from the identity provider's FederationMetadata.xml file as the whr value if you want ACS to automatically redirect the user to the partner's identity provider. entityID is an attribute in the issuer's federation metadata: ACS uses this attribute value to uniquely identify identity providers that it trusts.

3. ACS uses the whr parameter to look up the customer's identity provider and redirect John's browser to the Adatum issuer.

   Markus Says:
   	This scenario automates home realm discovery. There's no need for the user to provide his home realm details, as was the case in Chapter 4, "Federated Identity for Web Applications."

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

   > [!NOTE]
   > Although the identity provider may also issue an organization claim, Fabrikam will always generate the organization claim value in ACS. This prevents a malicious administrator at a partner organization from impersonating a user from another partner.  
   

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

   1. The Adatum identity provider uses HTTP redirection to redirect the browser to the Fabrikam ACS instance, delivering the security token issued by the Adatum identity provider to the Fabrikam ACS instance.
   2. The Fabrikam ACS instance receives this token and validates it.

   Step 3: Map the Claims

   1. The Fabrikam ACS instance applies claim-mapping rules to the claims in the identity provider's security token. ACS transforms the claims into claims that Fabrikam Shipping expects and understands.

   2. ACS returns a new token with the claims to John's browser and uses HTTP redirection to return John's browser the Fabrikam Shipping application.

      Note

      The redirection should be to a secure HTTP address (HTTPS) to prevent the possibility of session hijacking.

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

   1. The browser sends the security token from ACS, 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.)

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

   In the scenario described in Chapter 6, "Federated Identity with Multiple Partners," Fabrikam managed and hosted an identity provider for smaller customers such as Contoso to enable users from these customers to authenticate before accessing the Fabrikam Shipping application. Users at organizations such as Contoso would now prefer to reuse an existing social identity rather than maintaining a separate set of credentials just for use with Fabrikam Shipping.

   Here's an example of how the system works for a user at an organization such as Contoso where the users authenticate with an online social identity provider. The steps correspond to the un-shaded numbers in the preceding illustration. ACS treats the online social identity providers in almost the same way it treats the Adatum and Litware identity providers. However, it will use a different set of claims-mapping rules for the social identity providers and, if necessary, perform protocol transition as well. Fabrikam didn't need to change the Fabrikam Shipping application in order to support users with social identities; the application continues to trust ACS and ACS continues to deliver the same types of claims to Fabrikam Shipping.

   Step 1: Present Credentials to the Identity Provider

   1. When Mary from Contoso attempts to use Fabrikam Shipping for the first time (that is, when she first navigates to https://{fabrikam host}/f-shipping/Contoso), there's no session established yet. In other words, from Fabrikam's point of view, Mary is unauthenticated. The URL provides the Fabrikam Shipping application with a hint about the customer that is requesting access (the hint is "Contoso" at the end of the URL).

   2. The application redirects Mary's browser to the Fabrikam ACS instance in the cloud (the federation provider). That's because the Fabrikam ACS instance 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 uri:WindowsLiveID.

      Note

      In the current implementation, this means that all the employees at a small partner must use the same social identity provider. In this example, all Contoso employees must have a Windows Live ID to be able to access Fabrikam Shipping. You could extend the sample to enable users at partners such as Contoso to each use different social identity providers.

   3. ACS uses the whr parameter to look up the customer's preferred social identity provider and redirect Mary's browser to the social identity issuer; in this example, Windows Live.

   4. The social identity provider, Windows Live in this example, uses Mary's credentials to authenticate her and then returns a security token with a basic set of claims to Mary's browser. In the case of Windows Live ID, the only claim returned is nameidentifier.  

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

   1. The social identity provider uses HTTP redirection to redirect Mary's browser with the security token it has issued to the Fabrikam ACS instance.
   2. The Fabrikam ACS instance receives this token and validates it.

   Step 3: Map the Claims

   1. The Fabrikam ACS instance applies token mapping rules to the social identity provider's security token. It transforms the claims into claims that Fabrikam Shipping understands. In this example, it adds new claims: name, organization, role, and costcenter.

      Jana says:
      	The types of claims that ACS sends to Fabrikam Shipping from a user with a social identity are the same claims types as it sends for users at Adatum and Litware.

      2. If necessary, ACS transitions the protocol that the social identity provider uses to the WS-Federation protocol. 3. ACS returns a new token with the claims to Mary's browser.

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

      1. ACS uses HTTP redirection to redirect Mary's browser with the security token from ACS, which contains the claims, to the Fabrikam Shipping application.
      2. The application validates the security token.
      3. The application reads the claims and creates a session for Mary.

      Enrolling a New Partner Organization

      One of Fabrikam's goals was to enable partner organizations to enroll themselves with the Fabrikam Shipping application, and enable them to manage their own users. Both larger partners with their own identity providers and smaller partners whose employees use identities from social identity providers should be able to perform these operations.

      Partners, both with and without their own identity providers, can enroll themselves with Fabrikam Shipping.

      The enrollment process must perform three key configuration steps:

      • Update the Fabrikam Shipping list of registered partners. The registration data for each partner should include its name, the URL of a logo image, and an identifier for the partner's home realm.
      • For partners using their own identity provider, create a trust relationship so that the Fabrikam ACS instance trusts the partner's identity provider.
      • Create suitable claims-mapping rules in the Fabrikam ACS instance that transform the claims from the partner's identity provider to the claims that Fabrikam Shipping expects to see.

      Fabrikam uses the partner name and logo that it stores in its list of registered partners to customize the UI of Fabrikam Shipping when an employee from the partner visits the site. The partner's home realm is important because when Fabrikam Shipping redirects a user to ACS for authentication, it includes the home realm as a value for the whr parameter in the request's querystring. To enable ACS to automatically redirect the user to the correct identity provider, the partner's home realm value should be the value of the entityID in the partner identity provider's FederationMetadata.xml.

      Partners without their own identity provider use one of the pre-configured social identity providers in ACS; enrolling a new partner in this scenario does not require Fabrikam to configure a new identity provider in ACS. For partners with their own identity provider, the enrollment process must configure a new identity provider in ACS.

      Note

      Partners with their own identity provider must configure their identity provider; a configuration example might be defining a relying party realm. The details of this will be specific to the type of identity provider that the partner uses.

      Different identity providers return different claims. For example, Windows Live only returns a nameidentifier claim, while a custom provider might include name, organization, costcenter, and role claims. Regardless of the claims that the identity provider issues, the rules that the enrollment process creates in ACS must be sufficient to return costcenter, name, organization, and role claims, all of which the Fabrikam Shipping application requires. ACS can issue these claims to Fabrikam Shipping either by transforming a claim from the identity provider, by passing a claim from the identity provider through unchanged, or by creating a new claim.

      Bharath Says:
      	We can use ACS to handle the differences in the tokens and protocols that the various social identity providers use.

      Managing Multiple Partners with a Single Identity

      A user, such as Paul, may work for two or more partners of Fabrikam Shipping. If those partners have their own identity providers, then Paul will have two separate identities, such as paul@contoso.com and paul@adventureworks.com, for example. However, if the partner organizations do not have their own identity providers, then it's likely that Paul will want to use the same social identity (paul@gmail.com) with both partners. This raises a problem if Paul has different roles in the two partner organizations; in Contoso, he may be in the Shipment Manager role, and in AdventureWorks he may be in the Administrator role. If ACS assigns roles based on Paul's identity, he will end up with both roles assigned to him, which means he will be in the Administrator role in Contoso.

      To handle this scenario, Fabrikam first considered using a different service namespace for each partner in ACS. To access Contoso data at Fabrikam Shipping, Paul would need a token from the Contoso namespace, to access AdventureWorks data he would need a token from the AdventureWorks namespace. To automate the enrollment process for new partners, Fabrikam would need to be able to create new service namespaces in ACS programmatically. Unfortunately, the ACS Management API does not currently support this operation.

      The solution adopted by Fabrikam was to create a different relying party (RP) in ACS for each partner. In ACS, each relying party can have its own set of claims-mapping rules, so the rule group in the Contoso relying party in ACS can assign the Shipment Manager role to Paul, while the rule group in the AdventureWorks relying party in ACS can assign him the Administrator role. If Paul signs in to Fabrikam Shipping using a token from the Contoso relying party and he then tries to access AdventureWorks data he will need to re-authenticate in order to obtain a token from the AdventureWorks relying party in ACS.

      Note

      A single service namespace in ACS can have multiple relying parties. The wtrealm parameter passed to ACS identifies the relying party to use, and each relying party has its own set of claims-mapping rules that include a rule to add an organization claim. Fabrikam Shipping uses the organization claim to authorize access to data.

      Managing Users at a Partner Organization

      For a partner organization with its own identity provider, the partner can manage which employees have access to its data at Fabrikam Shipping using the partner's identity provider. By controlling which claims its identity provider issues for individual employees, the partner can determine what level of access the employee has in the Fabrikam Shipping application. This approach depends on the claims-mapping rules that the enrollment process created in ACS. For example, mapping the Order Tracker role in Adatum to the ShipmentManager role in Fabrikam Shipping would give anyone at Adatum with the Order Tracker role the ability to manage Adatum shipments at Fabrikam.

      Poe Says:
      	Enabling partners to manage their own users reduces the amount of work Fabrikam has to do to manage the Fabrikam Shipping application.

      In the case of a partner without its own identity provider, such as Contoso where employees authenticate with a social identity provider, the claims-mapping rules in ACS must include the mapping of individuals to roles within Fabrikam. To manage these mappings for these organizations, one user should be a designated administrator who can edit their organization's claims-mapping rules. The administrator would use an administration page hosted on the Fabrikam Shipping enrollment web site to manage the list of users with access to Contoso data in Fabrikam Shipping and edit the rules that control access levels. This page will use the ACS Management API to make the necessary configuration changes in ACS.

      Note

      The sample does not implement this feature: each partner without its own identity provider has only a single user. The enrollment process configures this user. The sample implementation also assumes that if a partner did have more than one user, then all the users must use the same social identity provider.

      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® solution, 7FederationWithMultiplePartnersAndAcs from https://claimsid.codeplex.com. If you are not interested in the mechanics, you should skip to the next section.

      The scenario described in this chapter is very similar to the scenario described in Chapter 6, "Federated Identity with Multiple Partners." The key difference is that ACS, rather than an issuer at Fabrikam, now provides the federation services. The changes to the Fabrikam Shipping application all relate to the way Fabrikam Shipping interacts with ACS; in particular, how the application enrolls new partners and handles the log on process. The logic of the application and the authorization rules it applies using the claims from the identity providers is unchanged.

      Modifying Fabrikam Shipping to use ACS instead of the Fabrikam federation provider was mostly a configuration task.

      Getting a List of Identity Providers from ACS

      When a partner wants to enroll with the Fabrikam Shipping application, part of the sign-up process requires the partner to select the identity provider they want to use. The choice they have is either to use their own identity provider (at this stage in the enrollment process Fabrikam Shipping and ACS know nothing about the partner or its identity provider), or to use one of the pre-configured social identity providers: Google, Yahoo!, or Windows Live. It's possible that the list of available social identity providers might change, so it makes sense for Fabrikam to build the list programmatically by querying the Fabrikam ACS instance. However, there's no way to ask ACS for only the list of social identity providers and exclude any custom identity providers from other partners. The following code sample shows how Fabrikam implemented an extension method, IsSocial, to check whether an identity provider is a social identity provider.

      public static class SocialIdentityProviders
      {
        public static readonly SocialIdentityProvider Google = new SocialIdentityProvider { 
          DisplayName = "Google", HomeRealm = "Google", Id = "10008641" };
        public static readonly SocialIdentityProvider WindowsLiveId = new 
          SocialIdentityProvider { DisplayName = "Windows Live ID", 
          HomeRealm = "uri:WindowsLiveID", Id = "10007989" };
        public static readonly SocialIdentityProvider Yahoo = new SocialIdentityProvider { 
          DisplayName = "Yahoo!", HomeRealm = "Yahoo!", Id = "10008653" };
              
        public static IEnumerable<SocialIdentityProvider> GetAll()
        {
          return new SocialIdentityProvider[3] { Google, Yahoo, WindowsLiveId };
        }
      
        public static string GetHomeRealm(string socialIpId)
        {
          var providers = new[] { Google, Yahoo, WindowsLiveId };
          return providers.Single(p => p.Id == socialIpId).HomeRealm;
        }
      
        public static bool IsSocial(this IdentityProvider ip)
        {
          if (ip.Issuer.Name.Contains(Google.HomeRealm) ||
              ip.Issuer.Name.Contains(Yahoo.HomeRealm) ||
              ip.Issuer.Name.Contains(WindowsLiveId.HomeRealm))
          {
             return true;
          }
          return false;
        }
      }
      

      Jana Says:
      	A separate web application called f-Shipping.Enrollment.7 handles the enrollment tasks.

      The solution includes an ACS.ServiceManagementWrapper project that wraps the REST calls that perform management operations in ACS. The enrollment process builds a list of available social identity providers by calling the RetrieveIdentityProviders method in this wrapper class.

      Note

      The ACS.ServiceManagementWrapper project uses password authentication over HTTPS with the calls that it makes to the ACS management API. As an alternative, you could sign the request with a symmetric key or an X.509 certificate.

      Adding a New Identity Provider to ACS

      When a partner with its own identity provider enrolls with Fabrikam Shipping, part of the enrollment process requires Fabrikam to add details of the partner's issuer to the list of identity providers in ACS. The enrollment process automates this by using the ACS Management API. The wrapper class in the ACS.ServiceManagementWrapper project includes two methods, AddIdentityProvider and AddIdentityProviderManually for configuring a new identity provider in ACS. During the enrollment process, if the user provides a FederationMetadata.xml file that contains all of the necessary information to configure the trust, the EnrollmentController class uses the AddIdentityProvider method. If the user provides details of the identity provider manually, it uses the AddIdentityProviderManually method. The enrollment process then adds a relying party and mapping rules to the identity provider, again using methods in the ServiceManagementWrapper wrapper class.

      Managing Claims-Mapping Rules in ACS

      The automated enrollment process for both larger organizations that have their own identity provider, and smaller partners who rely on a social identity provider requires Fabrikam to add claims-mapping rules to ACS programmatically. The wrapper class in the ACS.ServiceManagementWrapper project includes an AddSimpleRuleToRuleGroup method that the enrollment process uses when it adds a new claims-mapping rule. The application also uses the AddPassthroughRuleToRuleGroup when it needs to add a rule that passes a claim through from the identity provider to the relying party without changing it, and the AddSimpleRuleToRuleGroupWithoutSpecifyInputClaim method when it needs to create a new claim that's not derived from any of the claims issued by the identity provider.

      Note

      It's important that the mapping rules don't simply pass through the organization claim, but instead create a new organization claim derived from the identity of the identity provider. This is to prevent the risk of a malicious administrator at the partner spoofing the identity of another organization. When registering a new organization, the code should verify that the organization name is not already is use, so that a new registration cannot override an existing organization name or add itself to an existing organization. The Fabrikam Shipping application uses the organization claim in its authorization and data access management logic (for example, when creating and listing shipments).

      For partners without their own identity provider, the enrollment process must also create a new relying party in ACS. The wrapper class in the ACS.ServiceManagementWrapper project includes an AddRelyingParty method to perform this operation.

      Jana Says:
      	Each partner without an identity provider still needs a relying party so that Fabrikam Shipping can recognize when the same user is associated with two or more different partner organizations.

      The EnrollmentController class in the f-Shipping.Enrollment.7 project demonstrates how the Fabrikam Shipping application handles the automated enrollment process.

      Because Fabrikam uses multiple relying parties in ACS to handle the case where a user with a social identity is associated with multiple partners, the sample solution disables checking audience URIs in the Web.config file:

      <microsoft.identityModel>
        <service>
          <audienceUris mode="Never">
          </audienceUris>
          …
        </service>
      </microsoft.identityModel>
      

      Normally, you should not set the audienceUris mode to "Never" because this introduces a security vulnerability: the correct approach is to add the audience URIs at run time as Fabrikam Shipping enrolls new partners. You would also need to share the list of Uris between the f-Shipping.Enrollment.7 web application and the f-Shipping.7 web application. Furthermore, to avoid the possibility of one tenant impersonating another, you would use a separate symmetric key for each tenant. However, as described previously, in this solution ACS adds an organization claim to the token that it issues that the REST service can check.

      Displaying a List of Partner Organizations

      For the purposes of this sample, the home page at Fabrikam Shipping displays a list of registered partner organizations. In a real application, you may not want to make this information public because some partners may not want other partners to know about their business relationship with Fabrikam Shipping, so each partner would have their own landing page.

      Note

      In ACS 2.0 (the current version at the time of this writing), it's not possible to keep this information private because ACS publishes a public feed of all the identity providers associated with each relying party.

      Poe Says:
      	You can find the address of the feed that contains a list of all the identity providers in the ACS portal in the "Application integration" section under "Login Page Integration."

      For this example, the Fabrikam Shipping application generates the list of partners from a local store instead of querying ACS. Because Fabrikam Shipping maintains this data locally, there is no need to query ACS or use the login page that ACS can generate for you.

      Authenticating a User of Fabrikam Shipping

      The Fabrikam Shipping application uses the AuthenticateAndAuthorizeAttribute attribute class to intercept requests and then ask the WSFederationAndAuthenticationModule class to handle the authentication and to retrieve the user's claims from ACS. The AuthenticateUser method builds the redirect URL that passes the WS-Federation parameters to the ACS instance that Fabrikam Shipping uses. The following table describes the parameters that the application passes to ACS.

      Parameter	Example value	Notes
      wa	wsignin1.0	The WS-Federation command.
      wtrealm	https://localhost/f-Shipping.7/FederationResult	The realm value that ACS uses to identify the relying party.
      wctx	https://localhost/f-Shipping.7/Contoso	The return URL to which ACS should post the token with claims.

      Note

      The Fabrikam Shipping application does not send a whr parameter identifying the home realm because Fabrikam configures each tenant in ACS as a relying party with only a single identity provider enabled.

      The following code example shows the AuthenticateUser method in the AuthenticateAndAuthorizeAttribute class.

      private static void AuthenticateUser(AuthorizationContext context)
      {
        var organizationName = (string)context.RouteData.Values["organization"];
      
        if (!string.IsNullOrEmpty(organizationName))
        {
          …
      
          var returnUrl = GetReturnUrl(context.RequestContext);
      
          // User is not authenticated and is entering for the first time.
          var fam = FederatedAuthentication.WSFederationAuthenticationModule;
          var signIn = new SignInRequestMessage(new Uri(fam.Issuer), fam.Realm)
            {
              Context = returnUrl.ToString(),
              Realm = string.Format("https://localhost/f-shipping.7/{0}",organizationName)
            };
      
          context.Result = new RedirectResult(signIn.WriteQueryString());
        }
        else
        {
          throw new ArgumentException("Tenant name missing.");
        }
      }
      

      Authorizing Access to Fabrikam Shipping Data

      The Fabrikam Shipping application uses the same AuthenticateAndAuthorize attribute to handle authorization. For example, Fabrikam Shipping only allows members of the Shipment Manager role to cancel orders. The following code example from the ShipmentController class shows how this is declared:

      [AuthenticateAndAuthorize(Roles = "Shipment Manager")]
      [AcceptVerbs(HttpVerbs.Post)]
      public ActionResult Cancel(string id)
      {
        …
      }
      

      The AuthorizeUser method in the AuthenticateAndAuthorizeAttribute class determines whether a user has the appropriate Organization and Role claims:

      private void AuthorizeUser(AuthorizationContext context)
      {
          var organizationRequested = (string)context.RouteData.Values["organization"];
                  
          …
      
          var userOrganization = ClaimHelper
            .GetCurrentUserClaim(Fabrikam.ClaimTypes.Organization).Value;
          if (!organizationRequested.Equals(
              userOrganization, 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;
          }
      }
      

      In a multi-tenant application such as Fabrikam Shipping, the authorization rule that checks the Organization claim ensures that a tenant only has access to its own data.

      For a discussion of some alternative approaches to authorization that Fabrikam Shipping could have taken, see Appendix G, "Authorization Strategies."

      Setup and Physical Deployment

      The following sections describe the setup and physical deployment for the Fabrikam Shipping websites, the simulated claims issuers, and the initialization of the ACS instance.

      Fabrikam Shipping Websites

      Fabrikam has two separate websites: one for Fabrikam Shipping and one to manage the enrollment process for new partners. This enables Fabrikam to configure the two sites for the different expected usage patterns: Fabrikam expects the usage of the shipping site to be significantly higher than the usage of the enrollment site.

      Markus Says:

      Using two separate sites also circumvents a problem that can occur during the enrollment process for a partner that uses a social identity provider. During the enrollment process, a user must sign into their social identity provider so that Fabrikam can capture the claim values that prove that user's identity. The enrollment process then creates the new claims-mapping rules in ACS for the partner. Unless the user running the enrollment process signs out and then signs in again (not a great user experience), they will not get the full set of claims that they require to access the Fabrikam Shipping application.

      In the sample application, Fabrikam Shipping maintains a list of registered partner organizations using the Organization and OrganizationRepository classes. The following code sample shows the Organization class:

      public class Organization
      {
          public string LogoPath { get; set; }
          public string Name { get; set; }
          public string DisplayName { get; set; }
          public string HomeRealm { get; set; }
      }
      

      Both the f-Shipping.Enrollment.7 and the f-Shipping.7 web applications need access to this repository, which the sample implements by using a simple file called organizations.txt stored in a folder called SharedData.

      Note

      The implementation of the enrollment functionality in this sample shows only a basic outline of how you would implement this functionality in a real application.

      Sample Claims Issuers

      The sample comes with two, pre-configured, claims issuers that act as identity providers for Adatum and Litware. These simulated issuers illustrate the role that a real issuer, such as ADFS 2.0, would play in this scenario. If you want to experiment and extend the sample by enrolling additional partners with their own identity providers, you will need additional issuers. You can either create your own new STS using the WIF "WCF Security Token Service" template in Visual Studio and using either the Adatum.SimulatedIssuer.7 or Litware.SimulatedIssuer.7 projects as a model to work from, or you could use one of the simple issuers for Northwind or AdventureWorks in the Assets folder for this sample.

      These simple issuers use the SelfSTS sample application that you can read about here: https://archive.msdn.microsoft.com/SelfSTS.

      Initializing ACS

      The sample application includes a set of pre-configured partners for Fabrikam Shipping, both with and without their own identity providers. These partners require identity providers, relying parties, and claims-mapping rules in ACS in order to function. The ACS.Setup project in the solution is a simple console application that you can run to add the necessary configuration data for the pre-configured partners to your ACS instance. It uses the ACS Management API and the wrapper classes in the ACS.ServiceManagementWrapper project.

      Note

      You will still need to perform some manual configuration steps; the ACS Management API does not enable you to create a new service namespace. You must perform this operation in the ACS management portal.

      Questions

      1. Why does Fabrikam want to use ACS in the scenario described in this chapter?
         1. Because it will simplify Fabrikam's own internal infrastructure requirements.
         2. Because it’s the only way Fabrikam can support users who want to use a social identity provider for authentication.
         3. Because it enables users with social identities to access the Fabrikam Shipping application more easily.
         4. Because ACS can authenticate users with social identities.
      2. In the scenario described in this chapter, why is it necessary for Fabrikam to configure ACS to trust issuers at partners such Adatum and Litware?
         1. Because Fabrikam does not have its own on-premises federation provider.
         2. Because Fabrikam uses ACS for all the claims-mapping rules that convert claims to a format that Fabrikam Shipping understands.
         3. Because partners such as Adatum have some users who use social identities as their primary method of authentication.
         4. Because a relying party such as Fabrikam Shipping can only use a single federation provider.
      3. How does Fabrikam Shipping manage home realm discovery in the scenario described in this chapter?
         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 each address to determine which organization the user belongs to.
         3. ACS manages home realm discovery; Fabrikam Shipping does not.
         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.
      4. Enrolling a new partner without its own identity provider requires which of the following steps?
         1. Updating the list of registered partners stored by Fabrikam Shipping. This list includes the home realm of the partner.
         2. Adding a new identity provider to ACS.
         3. Adding a new relying party to ACS.
         4. Adding a new set of claims-mapping rules to ACS.
      5. Why does Fabrikam use a separate web application to handle the enrollment process?
         1. Because the expected usage patterns of the enrollment functionality are very different from the expected usage patterns of the main Fabrikam Shipping web site.
         2. Because using the enrollment functionality does not require a user to authenticate.
         3. Because the site that handles enrolling new partners must also act as a federation provider.
         4. Because the site that updates ACS with new relying parties and claims-mapping rules must have a different identity from sites that only read data from ACS.

      More Information

      Appendix E of this guide provides a detailed description of ACS and its features.

      Next | Home