Share via

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 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.

NoteNote:

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 configuration of this binding on the client is as follows:

<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 Security Token Service that issues a security token to the client so that the client can authenticate to the Calculator service.

The configuration of this binding on the service is as follows:

<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 Security Token Service.

The behavior for the service is as follows:

<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 Security Token Service exposes a single endpoint using the standard wsHttpBinding. The Security Token Service 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 Security Token Service 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 Security Token Service 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 Security Token Service 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.bat batch file included with this sample allows you to configure the server and Security Token Service 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 Security Token Service 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 Security Token Service to encrypt a secret such that the service can decrypt it.

To set up, build, and run the sample

  1. Run the setup.bat 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.

Footer image

Send comments about this topic to Microsoft.
© Microsoft Corporation. All rights reserved.