Claims Enabling Web Services

The Premise | Goals and Requirements | Overview of the Solution | Inside the Implementation - Implementing the Web Service, Implementing the Active Client, Implementing the Authorization Strategy, Debugging the Application | Setup and Physical Deployment - Configuring ADFS 2.0 for Web Services | Questions

In Chapter 4, "Federated Identity for Web Applications," you saw Adatum make the a-Order application available to its partner Litware. Rick, a salesman from Litware, used his local credentials to log onto the a-Order website, which was hosted on Adatum's domain.

To do this, Rick needed only a browser to access the a-Order website. But what would happen if the request came from an application other than a web browser? What if the information supplied by aOrder was going to be integrated into one of Litware's in-house applications?

Federated identity with an active (or "smart") client application works differently than federated identity with a web browser. In a browser-based scenario, the web application requests security tokens by redirecting the user's browser to an issuer that produces them. (This process is shown in the earlier scenarios.) With redirection, the browser can handle most of the authentication for you. In the active scenario, the client application actively contacts all issuers in a trust chain (these issuers are typically an identity provider (IdP) and a federation provider (FP)) to get and transform the required tokens.

Active clients do not need HTTP redirection.

In this chapter, you'll see an example of a smart client that uses federated identity. Fortunately, support for Microsoft® Windows® Communication Foundation (WCF) is a standard feature of the Windows Identity Foundation (WIF). Using WCF and WIF reduces the amount of code needed to implement both claims-aware web services and claims-aware smart clients.

The Premise

Litware wants to write an application that can read the status of its orders directly from Adatum. To satisfy this request, Adatum agrees to provide a web service called a-Order.OrderTracking.Services that can be called by Litware over the Internet.

Adatum and Litware have already done the work necessary to establish federated identity, and they both have issuers capable of interacting with active clients. The necessary communications infrastructure, including firewalls and proxies, is in place. To review these elements, see Chapter 4, "Federated Identity for Web Applications."

Bharath Says:
	If Active Directory® Federation Services (ADFS) 2.0 is used, support for federated identity with active clients is a standard feature.

Now, Adatum only needs to expose a claims-aware web service on the Internet. Litware will invoke Adatum's web service from within its client application. Because the client application runs in Litware's security realm, it can use Windows authentication to establish the identity of the user and then use this identity to obtain a token it can pass along to Adatum's federation provider.

Goals and Requirements

Both Litware and Adatum see benefits to a collaboration based on claims-aware web services. Litware wants programmatic access to Adatum's a-Order application. Adatum does not want to be responsible for authenticating any people or resources that belong to another security realm. For example, Adatum doesn't want to keep and maintain a database of Litware users.

Active clients use claims to get access to remote services.

Both Adatum and Litware want to reuse the existing infrastructure as much as possible. For example, Adatum wants to enforce permissions for its web service with the same rules it has for the browser-based web application. In other words, the browser-based application and the web service will both use roles for access control.

Overview of the Solution

Figure 1 gives an overview of the proposed system.

Figure 1

Federated identity with a smart client

The diagram shows an overview of the interactions and relationships among the different components. It is similar to the diagrams you saw in the previous chapters, except that no HTTP redirection is involved.

Litware's client application is based on Windows Presentation Foundation (WPF) and is deployed on Litware employees' desktops. Rick, the salesman at Litware, uses this application to track orders with Litware.

Adatum exposes a SOAP web service on the Internet. This web service is implemented with WCF and uses standard WCF bindings that allow it to receive Security Assertion Markup Language (SAML) tokens for authentication and authorization. In order to access this service, the client must present a security token from Adatum.

The sequence shown in the diagram proceeds as follows:

1. Litware's WPF application uses Rick's credentials to request a security token from Litware's issuer. Litware's issuer authenticates Rick and, if the authentication is a success, returns a Group claim with the value Sales because Rick is in the sales organization.
2. The WPF application then forwards the security token to Adatum’s issuer, which has been configured to trust Litware's issuer.
3. Adatum's issuer, acting as a federation provider, transforms the claim Group:Sales into Role:Order Tracker and adds a new claim, Organization:Litware. The transformed claims are the ones required by Adatum's web service, a-Order.OrderTracking.Services. These are the same rules that were defined in the browser-based scenario.
4. Finally, the WPF application sends the web service the request to return orders. This request includes the security token obtained in the previous step.

This sequence is a bit different from a browser-based web application because the smart client application knows the requirements of the web service in advance and also knows how to acquire the claims that satisfy the web service's requirements. The client application goes to the identity provider first, the federation provider second, and then to the web service. The smart client application actively drives the authentication process.

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

You can implement a claims-based smart client application using the built-in facilities of WCF, or you can code at a lower level using the WIF API. The a-Order.OrderTracking web service uses WCF standard bindings.

The a-Order.OrderTracking web service uses WCF standard bindings.

Implementing the Web Service

The web service's Web.config file contains the following WCF service configuration.

<services>
   <service 
      name="AOrder.OrderTracking.Services.OrderTrackingService" 
      behaviorConfiguration="serviceBehavior">
     <endpoint 
        address="" 
        binding="ws2007FederationHttpBinding" 
             
        bindingConfiguration=
              "WS2007FederationHttpBinding_IOrderTrackingService"  
        contract=
           "AOrder.OrderTracking.Contracts.IOrderTrackingService"
        />
     <endpoint address="mex" binding="mexHttpBinding" 
               contract="IMetadataExchange" />
   </service>
</services> 

Note

If your service endpoints support metadata exchange, as a-Order tracking does, it's easy for clients to locate services and bind to them using tools such as Svcutil.exe. However, some manual editing of the configuration that is auto-generated by the tools will be necessary in the current example because it involves two issuers: the identity provider and the federation provider. With only one issuer, the tool will generate a configuration file that does not need editing.

The Web.config file contains binding information that matches the binding information for the client. If they don't match, an exception will be thrown.

The Web.config file also contains some customizations. The following XML code shows the first customization.

<extensions>
   <behaviorExtensions>
      <add name="federatedServiceHostConfiguration" 
           type=
"Microsoft.IdentityModel.
   Configuration.ConfigureServiceHostBehaviorExtensionElement, 
 Microsoft.IdentityModel, ..." />
   </behaviorExtensions>
</extensions>

Adding this behavior extension attaches WIF to the WCF pipeline. This allows WIF to verify the security token's integrity against the public key. (If you forget to attach WIF, you will see a run-time exception with a message that says that a service certificate is missing.)

The service's Web.config file uses the <Microsoft.identityModel> element to specify the configuration required for the WIF component. This is shown in the following code example.

<microsoft.identityModel>
  <service>
     <issuerNameRegistry 
        type=
          "Microsoft.IdentityModel.Tokens.
                ConfigurationBasedIssuerNameRegistry, 
                Microsoft.IdentityModel, Version=3.5.0.0,
             Culture=neutral,   
             PublicKeyToken=31bf3856ad364e35">
       <trustedIssuers>
         <add 
           thumbprint="f260042d59e14817984c6183fbc6bfc71baf5462"  
           name="adatum" />
       </trustedIssuers>
     </issuerNameRegistry>
     <audienceUris>
        <add value=
          "http://{adatum host}/a-Order.OrderTracking.Services/
                                        OrderTrackingService.svc"
        />
     </audienceUris>
...

Because the Adatum issuer will encrypt its security tokens with the web service's X.509 certificate, the <service> element of the service's Web.config file also contains information about the web service's private key. This is shown in the following XML code.

<serviceCertificate>
   <certificateReference 
      findValue="CN=adatum" 
      storeLocation="LocalMachine" 
      storeName="My" 
      x509FindType="FindBySubjectDistinguishedName"/>
</serviceCertificate>

Implementing the Active Client

The client application, which acts as the WCF proxy, is responsible for orchestrating the interactions. You can see this by examining the client's App.config file. The following XML code is in the <system.serviceModel> section.

<client>
  <endpoint 
     address=
       "http://{adatum host}/a-Order.OrderTracking.Services/
                                        OrderTrackingService.svc"
     binding="ws2007FederationHttpBinding" 
     bindingConfiguration=
              "WS2007FederationHttpBinding_IOrderTrackingService"
     contract="OrderTrackingService.IOrderTrackingService" 
     name="WS2007FederationHttpBinding_IOrderTrackingService">
     <identity>
        <dns value="adatum" />
     </identity>
   </endpoint>
</client>    

The address attribute gives the Uniform Resource Identifier (URI) of the order tracking service.

The binding attribute, ws2007FederationHttpBinding, indicates that WCF should use the WS-Trust protocol when it creates the security context of invocations of the a-Order order tracking service.

The Domain Name System (DNS) value given in the <identity> section is verified at run time against the service certificate's subject name.

The App.config file specifies three nested bindings in the <bindings> subsection. The following XML code shows the first of these bindings.

<ws2007FederationHttpBinding>
  <binding  
     name="WS2007FederationHttpBinding_IOrderTrackingService">
    <security mode="Message">
      <message>
        <issuer 
          address="https://{adatum host}/{issuer endpoint}"
          binding="customBinding"   
          bindingConfiguration="AdatumIssuerIssuedToken">
        </issuer>
      </message>
    </security>
  </binding>
</ws2007FederationHttpBinding>

Note

The issuer address changes depending on how you deploy the sample. For an issuer running on the local machine, the address attribute of the <issuer> element will be:
https://localhost/Adatum.FederationProvider.4/Issuer.svc
For ADFS 2.0, the address will be:
https://{adatum host}/Trust/13/IssuedTokenMixedSymmetricBasic256

This binding connects the smart client application to the a-Order.OrderTracking service. Unlike WCF bindings that do not involve claims, this special claims-aware binding includes a message security element that specifies the address and binding configuration of the Adatum issuer. The address attribute represents the active endpoint of the Adatum issuer.

The message security element identifies the issuer.

The nested binding configuration is labeled AdatumIssuerIssuedToken. It is the second binding, as shown here.

<customBinding>
  <binding name="AdatumIssuerIssuedToken">
    <security 
       authenticationMode="IssuedTokenOverTransport"
       messageSecurityVersion=
          "WSSecurity11WSTrust13WSSecureConversation13
                        WSSecurityPolicy12BasicSecurityProfile10"
    >
      <issuedTokenParameters>
        <issuer 
           address=
               "https://{litware host}/{issuer endpoint}"
           binding="ws2007HttpBinding" 
           bindingConfiguration="LitwareIssuerUsernameMixed">
        </issuer>
      </issuedTokenParameters>
    </security>
    <httpsTransport />
  </binding>
</customBinding>

Markus Says:
	The federation binding in the Microsoft .NET Framework 3.5 provides no way to turn off a secure conversation. (This feature is available in version 4.0.) Because ADFS 2.0 endpoints have secure conversation disabled, this example needs a custom binding.

Note

The issuer address changes depending on how you deploy the sample. For an issuer running on the local machine, the address attribute of the <issuer> element will be:
https://localhost/Litware.SimulatedIssuer.4/Issuer.svc
For ADFS 2.0 the address will be:
https://{litware host}/Trust/13/UsernameMixed

The AdatumIssuerIssuedToken binding configures the connection to the Adatum issuer that will act as the federation provider in this scenario.

The <security> element specifies that the binding uses WS-Trust. This binding also nests the URI of the Litware issuer, and for this reason, it is sometimes known as a federation binding. The binding specifies that the binding configuration labeled LitwareIssuerUsernameMixed is used for the Litware issuer that acts as the identity provider. The following XML code shows this.

<ws2007HttpBinding>
  <binding name="LitwareIssuerUsernameMixed">
     <security mode="TransportWithMessageCredential">
       <message 
         clientCredentialType="UserName" 
         establishSecurityContext="false" 
       />
     </security>
  </binding>
</ws2007HttpBinding>    

This binding connects the Litware issuer that acts as an identity provider. This is a standard WCF HTTP binding because it transmits user credentials to the Litware issuer.

Note

In a production scenario, the configuration should be changed to clientCredentialType="Windows" to use Windows authentication. For simplicity, this sample uses UserName credentials. You may want to consider using other options in a production environment.

When the active client starts, it must provide credentials. If the configured credential type is UserName, a UserName property must be set. This is shown in the following code.

private void ShowOrders()
{
  var client = 
          new OrderTrackingService.OrderTrackingServiceClient();
  
  client.ClientCredentials.UserName.UserName = "LITWARE\\rick";
  client.ClientCredentials.UserName.Password =  
                                      "thisPasswordIsNotChecked";

  var orders = client.GetOrdersFromMyOrganization();

  this.DisplayView(new OrderTrackingView()
                   {
                     DataContext = 
                         new OrderTrackingViewModel(orders)
                   });
}

This step would not be necessary if the application were deployed in a production environment because it would probably use Windows authentication.

Note

WCF federation bindings can handle the negotiations between the active client and the issuers without additional code. You can achieve the same results with calls to the WIF WSTrustChannel class.

Markus Says:
	Using the WIF WSTrustChannel gives you more control, but it requires a deeper understanding of WS-Trust.

Implementing the Authorization Strategy

The Adatum web service implements its authorization strategy in the SimpleClaimsAuthorizationManager class. The service's Web.config file contains a reference to this class in the <claimsAuthorizationManager> element.

A claims authorization manager determines which methods can be called by the current user.

<claimsAuthorizationManager 
   type="AOrder.OrderTracking.Services.
                               SimpleClaimsAuthorizationManager,  
             AOrder.OrderTracking.Services" />

Adding this service extension causes WCF to invoke the CheckAccess method of the specified class for authorization. This occurs before the service operation is called.

The implementation of the SimpleClaimsAuthorizationManager class is shown in the following code.

public class SimpleClaimsAuthorizationManager : 
                                       ClaimsAuthorizationManager
{
  public override bool CheckAccess(AuthorizationContext context)
  {
    return context.Principal.IsInRole(Adatum.Roles.OrderTracker);
  }
}

WIF provides the base class, ClaimsAuthorizationManager. Applications derive from this class in order to specify their own ways of checking whether an authenticated user should be allowed to call the web service methods.

The CheckAccess method in the a-Order order tracking service ensures that the caller of any of the service's methods must have a role claim with the value Adatum.Roles.OrderTracker, which is defined in the Samples.Web.ClaimsUtilities project elsewhere as the string, "Order Tracker."

In this scenario, the Litware issuer, acting as an identity provider, issues a Group claim that identifies the salesman Rick as being in the Litware sales organization (value=Sales). The Adatum issuer, acting as a federation provider, transforms the security token it receives from Litware. One of its transformation rules adds the role, Order Tracker, to any Litware employee with a group claim value of Sales. The order tracking service receives the transformed token and grants access to the service.

Debugging the Application

The configuration files for the client and the web service in this sample include settings to enable tracing and debugging messages. By default, they are commented out so that they are not active.

If you uncomment them, make sure you update the <sharedListeners> section so that log files are generated where you can find them and in a location where the application has write permissions. Here is the XML code.

<sharedListeners>
  <add 
    initializeData="c:\temp\WCF-service.svclog"     
    type="System.Diagnostics.XmlWriterTraceListener"
    name="xml">
    <filter type="" />
  </add>
  <add 
    initializeData="c:\temp\wcf-service-msvg.svclog"      
    type="System.Diagnostics.XmlWriterTraceListener, System,
               Version=2.0.0.0, Culture=neutral, 
               PublicKeyToken=b77a5c561934e089"
    name="ServiceModelMessageLoggingListener" 
    traceOutputOptions="Timestamp">
    <filter type="" />
  </add>
</sharedListeners>

Setup and Physical Deployment

By default, the web service uses the local host for all components. In a production environment, you would want to use separate computers for the client, the web service, the federation provider, and the identity provider.

To deploy this application, you must substitute the mock issuer with a production-grade component such as ADFS 2.0 that supports active clients. You must also adjust the Web.config and App.config settings to account for the new server names by changing the issuer addresses.

Remove the mock issuer during deployment.

Note that neither the client nor the web service needs to be recompiled to be deployed to a production environment. All of the necessary changes are in the respective .config files.

Configuring ADFS 2.0 for Web Services

In the case of ADFS 2.0, you enable the endpoints using the Microsoft Management Console (MMC).

To obtain a token from Litware, the UsernameMixed or WindowsMixed endpoint could be used. UsernameMixed requires a user name and password to be sent across the wire, while WindowsMixed works with the Windows credentials. Both endpoints will return a SAML token.

Note

The "Mixed" suffix indicates that the endpoint uses transport security (based on HTTPS) for integrity and confidentiality; client credentials are included in the header of the SOAP message.

To obtain a token from Adatum, the endpoint used is IssuedTokenMixedSymmetricBasic256. This endpoint accepts a SAML token as an input and returns a SAML token as an output. It also uses transport and message security.

In addition, Litware and Adatum must establish a trust relationship. Litware must configure Adatum ADFS as a relying party (RP) and create rules to generate a token based on Lightweight Directory Access Protocol (LDAP) Active Directory attributes. Adatum must configure Litware ADFS as an identity provider and create rules to transform the group claims into role claims.

Finally, Adatum must configure the a-Order web service as a relying party. Adatum must enable token encryption and create rules that pass role and name claims through.

Questions

1. Which statements describe the difference between the way federated identity works for an active client as compared to a passive client:
   1. An active client uses HTTP redirects to ask each token issuer in turn to process a set of claims.
   2. A passive client receives HTTP redirects from a web application that redirect it to each issuer in turn to obtain a set of claims.
   3. An active client generates tokens to send to claims issuers.
   4. A passive client generates tokens to send to claims issuers.
2. A difference in behavior between an active client and a passive client is:
   1. An active client visits the relying party first; a passive client visits the identity provider first.
   2. An active client does not need to visit a federation provider because it can perform any necessary claims transformations by itself.
   3. A passive client visits the relying party first; an active client visits the identity provider first.
   4. An active client must visit a federation provider first to determine the identity provider it should use. Passive clients rely on home realm discovery to determine the identity provider to use.
3. The active scenario described in this chapter uses which protocol to handle the exchange of tokens between the various parties?
   1. WS-Trust
   2. WS-Transactions
   3. WS-Federation
   4. ADFS
4. In the scenario described in this chapter, it's necessary to edit the client application's configuration file manually, because the Svcutil.exe tool only adds a binding for a single issuer. Why do you need to configure multiple issuers?
   1. The metadata from the relying party only includes details of the Adatum identity provider.
   2. The metadata from the relying party only includes details of the client application's identity provider.
   3. The metadata from the relying party only includes details of the client application's federation provider.
   4. The metadata from the relying party only includes details of the Adatum federation provider.
5. The WCF service at Adatum performs authorization checks on the requests that it receives from client applications. How does it implement the checks?
   1. The WCF service uses the IsInRole method to verify that the caller is a member of the OrderTracker role.
   2. The Adatum federation provider transforms claims from other identity providers into Role type claims with a value of OrderTracker.
   3. The WCF service queries the Adatum federation provider to determine whether a user is in the OrderTracker role.
   4. It does not need to implement any authorization checks. The application automatically grants access to anyone who has successfully authenticated.

Next | Home