WS Federation HTTP Binding

  • Article

Download sample

This sample demonstrates how to implement a typical federated service, security token service and a corresponding client using Windows Communication Foundation (WCF). This sample consists of a client console program (client.exe), a security token service console program (Securitytokenservice.exe) and a service console program (Service.exe). The service implements a contract that defines a request-reply communication pattern. The contract is defined by the ICalculator interface, which exposes math operations (add, subtract, multiply, and divide). The client gets a security token from the security token service (STS) and makes synchronous requests to the service for a given math operation and the service replies with the result. Client activity is visible in the console window.

For more information about this binding, see How to: Create a WSFederationHttpBinding, and How to: Configure Credentials on a Federation Service.

Note

The setup procedure and build instructions for this sample are located at the end of this topic.

This sample exposes the ICalculator contract using the wsFederationHttpBinding Element. The following configuration of this binding is on the client.

<bindings>
  <wsFederationHttpBinding>
    <binding name="ServiceFed" >
      <security mode ="Message">
        <message issuedKeyType ="SymmetricKey" 
                 issuedTokenType ="http://docs.oasis-open.org/wss/oasis-wss-saml-token-profile-1.1#SAMLV1.1" >
          <issuer address ="https://localhost:8000/sts/windows" 
                  binding ="wsHttpBinding" />
        </message>
      </security>
    </binding>
  </wsFederationHttpBinding>
</bindings>

On the security element of wsFederationHttpBinding, the security mode value configures which security mode should be used. In this sample, messages security is being used, which is why the message element of wsFederationHttpBinding is specified inside the security element of wsFederationHttpBinding. The <issuer> element of wsFederationHttpBinding inside the message element of wsFederationHttpBinding specifies the address and binding for the STS that issues a security token to the client so that the client can authenticate to the Calculator service.

The following configuration of this binding is on the service.

<bindings>
  <wsFederationHttpBinding>
    <binding name="ServiceFed" >
      <security mode ="Message">
        <message issuedKeyType ="SymmetricKey" 
                 issuedTokenType =
"http://docs.oasis-open.org/wss/oasis-wss-saml-token-profile-1.1#SAMLV1.1" >
          <issuerMetadata address ="https://localhost:8000/sts/mex" >
            <identity>
              <certificateReference storeLocation ="CurrentUser"
                     storeName="TrustedPeople"
                     x509FindType ="FindBySubjectNameDistinguisedName" 
                     findValue ="CN=STS"/>
            </identity>
          </issuerMetadata>
        </message>
      </security>
    </binding>
  </wsFederationHttpBinding>
</bindings>

On the security element of wsFederationHttpBinding, the security mode value configures which security mode should be used. In this sample, messages security is being used, which is why the <message> element of wsFederationHttpBinding is specified inside the security element of wsFederationHttpBinding. The <issuerMetadata> element of wsFederationHttpBinding inside the <message> element of wsFederationHttpBinding specifies the address and identity for an endpoint that can be used to retrieve metadata for the STS.

The behavior for the service is shown in the following code.

<behavior name ="ServiceBehaviour" >
  <serviceDebug includeExceptionDetailInFaults ="true"/>
  <serviceMetadata httpGetEnabled ="true"/>
  <serviceCredentials>
    <issuedTokenAuthentication>
      <knownCertificates>
        <add storeLocation ="LocalMachine"
             storeName="TrustedPeople"
             x509FindType="FindBySubjectDistinguishedName"
             findValue="CN=STS" />
      </knownCertificates>
    </issuedTokenAuthentication>
    <serviceCertificate storeLocation ="LocalMachine"
                        storeName ="My"
                        x509FindType ="FindBySubjectDistinguishedName"
                        findValue ="CN=localhost"/>
  </serviceCredentials>
</behavior>

The <issuedTokenAuthentication> of <serviceCredentials> allows the service to specify constraints on the tokens it allows clients to present during authentication. This configuration specifies that tokens signed by a certificate whose Subject Name is CN=STS are accepted by the service.

The STS exposes a single endpoint using the standard wsHttpBinding. The STS responds to request from clients for tokens and provided the client authenticates using a Windows account, issues a token that contains the client's user name as a claim in the issued token. As part of creating the token, the STS signs the token using the private key associated with the CN=STS certificate. In addition it creates a symmetric key and encrypts it using the public key associated with the CN=localhost certificate. In returning the token to the client, the STS also returns the symmetric key. The client presents the issued token to the Calculator service, and proves that it knows the symmetric key by signing the message with that key.

Running the sample

See the following instructions to run the sample. When you run the sample, the request for the security token is shown in the STS console window. The operation requests and responses are displayed in the client and service console windows. Press ENTER in any of the console windows to shut down the application.

Add(100,15.99) = 115.99
Subtract(145,76.54) = 68.46
Multiply(9,81.25) = 731.25
Divide(22,7) = 3.14285714285714

Press <ENTER> to terminate client.

Setup Batch File

The Setup.cmd batch file included with this sample allows you to configure the server and Security Token Service (STS) with relevant certificates to run a self-hosted application. The batch file creates two certificates both in the LocalMachine/TrustedPeople certificate store. The first certificate has a subject name of CN=STS and is used by the STS to sign the security tokens that it issues to the client. The second certificate has a subject name of CN=localhost and is used by the STS to encrypt a secret such that the service can decrypt it.

To set up, build, and run the sample

  1. Run the Setup.cmd file to create the required certificates.

  2. To build the C# or Visual Basic .NET edition of the solution, follow the instructions in Building the Windows Communication Foundation Samples. Ensure that all the projects in the solution are built (Client, RSTRSTR, SecurityTokenService, Service, Shared).

  3. Ensure that Service.exe and SecurityTokenService.exe are both running.

  4. Run Client.exe.

See Also

Other Resources

WS 2007 Federation HTTP Binding

© 2007 Microsoft Corporation. All rights reserved.