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 on to the a-Order Web site, which was hosted on Adatum's domain.
To do this, Rick only needed a browser to access the a-Order Web site. 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 IP and an FP) to get and transform the required tokens.
In this chapter, you'll see an example of a smart client that uses federated identity. Fortunately, support for 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 a claims-aware Web service and a claims-aware smart client.

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 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, such as firewalls and proxies, is in place. To review these elements, see chapter 4, "Federated Identity for Web Applications."
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 FP.

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.
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 clientThe 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. 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. It goes to the IP first, the FP second, and then to the Web service. The smart client application actively drives the authentication process.

Inside the Implementation

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.

Implementing the Web Service

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


     <endpoint address="mex" binding="mexHttpBinding" 
               contract="IMetadataExchange" />

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 IP and the FP. 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.

      <add name="federatedServiceHostConfiguration" 
 Microsoft.IdentityModel, ..." />

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, Version=,
           name="adatum" />
        <add value=
          "http://{adatum host}/a-Order.OrderTracking.Services/

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.


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.

       "http://{adatum host}/a-Order.OrderTracking.Services/
        <dns value="adatum" />

The address attribute gives the Uniform Resource Indicator (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.

    <security mode="Message">
          address="https://{adatum host}/{issuer endpoint}"

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.SimulatedIssuer/Scenario4/Issue.svcFor ADFS 2.0, the address will be: https://{adatum host}/Trust/13/IssuedTokenMixedSymmetricBasic256This 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 gives the active endpoint of the Adatum issuer.
The nested binding configuration is labeled AdatumIssuerIssuedToken. It is the second binding, as shown here.

  <binding name="AdatumIssuerIssuedToken">
               "https://{litware host}/Trust/13/UsernameMixed"
    <httpsTransport />

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/Scenario4/Issue.svcFor ADFS 2.0 the address will be: https://{litware host}/Trust/13/UsernameMixedThe AdatumIssuerIssuedToken binding configures the connection to the Adatum issuer that will act as the FP in this scenario.
The <security> element specifies that the binding uses WS-Trust. Thisbinding 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 IP. The following XML code shows this.

  <binding name="LitwareIssuerUsernameMixed">
     <security mode="TransportWithMessageCredential">

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

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 =  

  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.

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's WSTrustChannel class.

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.

             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 : 
  public SimpleClaimsAuthorizationManager() { }

  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 IP, issues a Group claim that identifies the salesman Rick as being in the Litware sales organization (value=Sales). The Adatum issuer, acting as an FP, 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.

    <filter type="" />
    type="System.Diagnostics.XmlWriterTraceListener, System,
               Version=, Culture=neutral, 
    <filter type="" />

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 FP, and the IP.
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.
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.
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 and message security (based on an X.509 certificate). 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, both Litware and Adatum must establish a trust relationship. Litware must configure Adatum ADFS as a relying party 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 (RP). You must enable token encryption and create rules that pass role and name claims through.

Last edited Jul 7, 2010 at 5:30 AM by eugeniop, version 1


No comments yet.