The Trusted Façade Pattern

Context

You want to authenticate external users that access a client application. Both the users and the application are outside the corporate firewall. The application is in the perimeter network (also known as DMZ, demilitarized zone, and screened subnet). It uses a Web service that is behind the firewall, in the corporate network. The application and the Web service also use different credential stores and authentication mechanisms. The following diagram shows the network topology.

Topology of the network

In the example that follows, the application in the perimeter network is a SharePoint application. The SharePoint application authenticates the external users. It also exposes information and operations that come from the corporate Web service to those authenticated users. The corporate Web service must apply authorization rules based on the identities of the external users.

Objectives

Use the Trusted Façade pattern with a SharePoint application to do the following:

• Authenticate external users of a SharePoint application that is located in a perimeter network. The SharePoint application uses a credential store that is also in the perimeter network.
• Authenticate the SharePoint application in a perimeter network to a Web service in the corporate network with credentials that are recognized in the corporate security domain.
• Ensure the confidentiality and integrity of messages that are exchanged between the SharePoint application and the Web service.
• Have a Web service in a corporate domain apply authorization rules that are based on the identity of the external user.
• Avoid creating additional credential stores to store passwords in the SharePoint application.

Note

This pattern is implemented in the Partner Portal reference implementation to secure access to the pricing service and the incident management service.

Solution

The corporate Web service authenticates the SharePoint application. SharePoint supplies the identities of the authenticated external users to the Web service. The Web service trusts SharePoint to authenticate the external users and to provide the correct identity information. The Web service applies authorization rules based on the identities. In effect, SharePoint provides a security façade that is trusted by the Web service for external users in the perimeter network. The following example demonstrates how the trusted façade is used in the Partner Portal application.

Contoso uses a SharePoint application named the Partner Portal that allows Contoso partners to access information from an incident management business system. One of the partners is a company that is named Fabrikam. The Partner Portal application relies on SharePoint forms-based authentication to authenticate incoming users from Fabrikam. For example, there is a Fabrikam employee who is named Joe. When Joe accesses a Web page in the Partner Portal application to view incident information, SharePoint calls a Web service that is exposed by the incident management business system.

The Web service authenticates the Partner Portal application identity. Typically, this means that the Web service authenticates the service account under which the SharePoint instance runs. An example of this identity might be the PartnerPortalServiceAccount. After the Partner Portal application is authenticated, it provides the Web service with an identity that is based on the external identity, "Joe from Fabrikam." In this example, it is only important to the Web service to know which partner employs Joe, so the identity SharePoint provides to the service is "Fabrikam." Based on this identity, the Web service returns incident information that is only applicable to Fabrikam.

Implementation Details

The Partner Portal implementation of the Trusted Façade pattern has two layers of Web service security that use the Windows Communication Foundation (WCF). The outer layer authenticates the SharePoint application that accesses the WCF service. It also guarantees message integrity and confidentiality. Authentication can occur over HTTP, HTTPS, or TCP and typically uses Windows domain credentials or certificate credentials. HTTPS or TCP are preferable to HTTP because they are better suited to ensure the confidentiality and integrity of the messages. The authentication of the SharePoint application to the Web service typically uses one of the following security mechanisms:

• Active Directory credentials. The credentials for the application pool that is used by the SharePoint application use an Active Directory identity that is known to the corporate network.
• Certificate credentials. The SharePoint application uses a client certificate that is trusted by the Web service, and the Web service uses a certificate trusted by the SharePoint application.

Although other Web service security mechanisms can be used for the outer layer, you should make sure that you maintain message confidentiality and integrity, and that the external user identity can be passed to the Web service.

After the WCF service authenticates the calling SharePoint application as a trusted party, the inner security layer gives the Web service an identity that is related to the external user. The Web service trusts SharePoint to act as a façade that authenticates external users, and it allows SharePoint to vouch for the user's identity.

Note

The trusted façade is conceptually similar to the Kerberos protocol transition with constrained delegation that implemented by the Windows Server 2003 and Windows Server 2008. For more information, see Protocol Transition with Constrained Delegation Technical Supplement on MSDN.

The following diagram represents the outer and inner layers of security that implement the trusted façade. This example uses Windows authentication and the HTTPS transport.

Trusted façade security layers

The next section describes the Partner Portal implementation of the trusted façade.

Partner Portal Implementation

The following section demonstrates the general approach to do the following:

• Secure the communication channel between the SharePoint application and the WCF service.
• Convey end-user identity information from the SharePoint application to the back-end service, over the secure channel.

Communication with the back-end service uses the HTTPS protocol. The protocol uses the Secure Sockets Layer (SSL) to encrypt messages at the transport level. A certificate is installed on the WCF service server to authenticate the SSL messages from the WCF service client. SharePoint uses Windows authentication to authenticate to the server. This establishes a trust relationship between the Web service and the SharePoint application. The SharePoint application authenticates the external user identity. It then transmits it in a UsernameToken token. It uses the secured outer layer to do this. The UsernameToken does not contain a password because SharePoint has already authenticated the external user.

Participants

The following are the participants in the authentication and authorization process.

• External user. The external user uses the SharePoint application that provides the credentials for authentication. SharePoint maintains a security context for the external user during the user session.
• SharePoint application. This authenticates the external user based on the credentials the user provides. The SharePoint application authenticates to the Web service and gives it the external user identity. The SharePoint application then exposes the functionality and data that it receives from the Web service to the external user.
• External user identity store. This stores the external user credentials for a particular identity in the perimeter network. Common examples are a SQL Server database, Active Directory Application Mode (ADAM), or Lightweight Directory Services (LDS).
• Service. This is the Web service that first authenticates SharePoint before granting it access. It makes authorization decisions that are based on the external user identity that SharePoint provides.
• Internal user identity store. This stores the user credentials for a particular identity in the corporate security domain. A common example is Active Directory.

Note

The internal client identity store can also be based on a certificate authority that establishes a cryptographically strong identity with a digital certificate. In this case, the identity does not need to be validated with a central identity store at run time, but the certificate authority that issued the certificate must be trusted. The certificate authority is conceptually equivalent to the internal client identity store.

Interaction Sequence

This section describes the authentication process. The following diagram outlines the sequence of steps.

Steps for authenticating a user and accessing business information

Step1: The User Authenticates to SharePoint

In the first step, the user authenticates to the SharePoint application, typically by providing a user name and password. SharePoint validates the information against credentials that are in the external user identity store, which is located in the perimeter network. SharePoint returns a security context to the client. This is an encrypted cookie. The result of this step is that SharePoint has established the identity of the external user and established a security context that is used in subsequent requests.

Step 2: The User Browses to a Page that Contains Business Data

The user submits a request to SharePoint for a page that includes data from the line-of-business (LOB) system. SharePoint derives the client's identity from the security context that was established in step 1. SharePoint retrieves the data from the LOB system (see step 3) and creates a page that contains the data that the external user is authorized to view. SharePoint provides the content in response to the browser request.

Step 3: SharePoint Retrieves Data from the Service

In this step, SharePoint uses a Web service to retrieve the business information from the LOB system. The following three events occur during this step:

1. The Web service authenticates the identity of the SharePoint application.
2. The Web service accepts the identity of the external user that it receives from SharePoint.
3. The Web service processes the operation that is contained in the message.

There are several ways to implement this sequence. The Partner Portal application has the following characteristics:

• SSL ensures message confidentiality and integrity.
• The Web service authenticates the SharePoint identity with NTLM.
• The Web service receives the external user identity as a UserName token.
• The implementation uses the WCF infrastructure.

The following explanation of the code shows how the steps are implemented.

Assume that the service has an SSL certificate and therefore accepts requests over HTTPS. The following XML is from the SharePoint application's Web.config file. It is mirrored on the Web service.

<customBinding>
   <binding name="TrustedFacadeBinding">
      <security authenticationMode="UserNameOverTransport"/>
      <httpsTransport authenticationScheme="Ntlm" />
   </binding>
</customBinding>

The XML creates a custom binding. A custom binding is necessary because there are two types of authentication information. One type uses the outer security layer, and the other type uses the inner security layer. The httpsTransport setting configures the outer security layer. It instructs WCF to use the HTTPS protocol and to use NTLM to authenticate to the Web service. HTTPS secures the transport layer, and NTLM conveys the Windows credentials for the SharePoint application pool to the Web service.

The following code, which is in the SharePoint application, shows how to set a partner identity that is derived from the user identity on the client proxy.

PricingClient client = new Contoso.LOB.Services.Client.PricingProxy.PricingClient();
client.ClientCredentials.UserName.UserName = this.PartnerId;
return new DisposableProxy<IPricing>(client);

WCF sends a UserName token to the Web service to establish the inner security layer. The identity used in this token is established by setting the UserName property on the WCF proxy.

After the security context is established, the Web service validates the identity, based on the context. The Partner Portal application uses a stub service to simulate a pricing engine. Validation occurs in two steps. The first step adds a PrincipalPermission attribute to the pricing operation to ensure that the calling service is authorized to access the Web service. This is shown in the following code.

[PrincipalPermission(SecurityAction.Demand, Role=SecurityHelper.AdministratorsRole)]
[PrincipalPermission(SecurityAction.Demand, Role=SecurityHelper.AuthorizedRole)]        
public Price GetPriceBySku(string sku)
{
…

The code checks that the accessing identity belongs to a permitted role; in this case, the code checks that the identity is one of two defined roles, AdministratorRole or AuthorizedRole. The SharePoint application pool belongs to the AuthorizedRole. After NTLM establishes the identity, SharePoint can access the Web service. At this point, the outer security layer is established and the Web service trusts the end-user identity that SharePoint provides. The following code shows how to retrieve the partner ID from the claim set that the WCF security context provides.

public class SecurityHelper : ISecurityHelper
{
   …
   public string GetPartnerId()
   {
      string clientUserName = string.Empty;

      foreach (ClaimSet claimSet in ServiceSecurityContext.Current.AuthorizationContext.ClaimSets)
      {
         foreach (Claim claim in claimSet)
         {
            if (claim.ClaimType == ClaimTypes.Name && claim.Right == Rights.Identity)
            {
               clientUserName = (string)claim.Resource;
                break;
             }
          }
      }
      return clientUserName;
   }
}

After it retrieves the security context, the business logic applies authorization rules that are based on the identity. In the following code, the partner identity determines the pricing discounts.

[PrincipalPermission(SecurityAction.Demand, Role = SecurityHelper.AdministratorsRole)]
[PrincipalPermission(SecurityAction.Demand, Role = SecurityHelper.AuthorizedRole)]    
public IList<Discount> GetDiscountsBySku(string sku)
{
   List<Discount> discounts = new List<Discount>();
   string query = string.Format(CultureInfo.CurrentCulture, "ProductSku = '{0}' AND PartnerId = '{1}'", sku, this.securityHelper.GetPartnerId());
   PricingDataSet.DiscountRow[] match = this.pricingDataSet.Discount.Select(query) as PricingDataSet.DiscountRow[];
…

Implementation Variations

The implementation variations of the Trusted Façade pattern primarily focus on how the security context is established between the SharePoint application and the Web service. There are many ways to do this, but the following are two recommended alternatives:

• Use TCP transport and Windows stream security. The WCF documentation provides an example of how to use the TCP transport in conjunction with the windowsStreamSecurity element to implement the Trusted Façade pattern. This approach requires a stream-oriented protocol such as TCP or named pipes. Typically, you must host the service as a Windows service. However, if you are using Windows Server 2008, you can take advantage of its process activation features. For more information, see Windows Process Activation Service Support for Application Server and How to: Host a WCF Service in WAS on MSDN. For the WCF example, seeTrusted Facade Service on MSDN.
• Use certificate-based authentication. You can use certificate-based authentication if you configure a client certificate to authenticate the SharePoint application to the Web service. Use certificate-based authentication instead of Windows Challenge/Response (NTLM).

Considerations

The benefits of using the Trusted Façade pattern with WCF include the following:

• The pattern shows a way to communicate between two different authentication domains. It allows you to apply fine-grained authorization rules that are based on the identity of the external user. This is in contrast to a trusted subsystem, where the Web service has no information about the external user. Therefore, it applies the same coarse-grained authorization rules to all users.
• The pattern eliminates the need to store user passwords in SharePoint in order to authenticate with the LOB Web service. This is preferable to a custom single sign-on (SSO) implementation, such as SharePoint SSO.
• The pattern can be implemented with several transport security options, including TCP and HTTPS.

The following are some issues to consider if you use the Trusted Façade pattern:

• If the security of the SharePoint application is compromised and a client identity is impersonated, the Web service may return information to an unauthorized user. Web service operations are still limited to the operations that are permitted for the SharePoint application. This issue is the same as for the Trusted Subsystem pattern.
• You must configure identities and authorization rights based on identities that are derived from external users. In some cases, the system might not have this flexibility and additional logic that is required in the Web service.

Related Patterns

The Partner Portal implementation of the Trusted Façade pattern is a variation of the Trusted Facade Service that is discussed on MSDN. It also builds on the Trusted Subsystem, which is also discussed on MSDN.

Home page on MSDN | Community site