Edit

WS 2007 Federation HTTP Binding

  • Article

The WS2007FederationHttp sample demonstrates the use of WS2007FederationHttpBinding, a standard binding that you can use to build federated scenarios that support version 1.3 of the WS-Trust specification.

Note

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

The sample consists of a console-based client program (Client.exe), a console-based security token service program (Securitytokenservice.exe), and a console-based service 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 obtains a security token from the Security Token Service (STS) and makes synchronous requests to the service for a given math operation. The service then replies with the result. Client activity is visible in the console window.

The sample makes the ICalculator contract available using the ws2007FederationHttpBinding element. The configuration of this binding on the client is shown in the following code:

<bindings>
  <ws2007FederationHttpBinding>
    <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" >
          <!-- Endpoint address and binding for Security Token Service -->
          <issuer address ="http://localhost:8000/sts/windows"
                  binding ="ws2007HttpBinding" />
        </message>
      </security>
    </binding>
  </ws2007FederationHttpBinding>
</bindings>

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

The configuration of this binding on the service is shown in the following code:

<bindings>
  <ws2007FederationHttpBinding>
    <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" >
          <!-- Metadata address for Security Token Service -->
          <issuerMetadata address ="http://localhost:8000/sts/mex" >
            <identity>
              <certificateReference storeLocation ="CurrentUser"
                                    storeName="TrustedPeople"
                                    x509FindType ="FindBySubjectDistinguishedName"
                                    findValue ="CN=STS" />
            </identity>
          </issuerMetadata>
        </message>
      </security>
    </binding>
  </ws2007FederationHttpBinding>
</bindings>

On the <security>, the security value specifies which security mode should be used. In this sample, message security is used, which is why the <message> is specified inside the <security>. The <issuerMetadata> element of ws2007FederationHttpBinding inside the <message> 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:

<behaviors>
  <serviceBehaviors>
    <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>
  </serviceBehaviors>
</behaviors>

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

STS makes a single endpoint available using the standard WS2007HttpBinding. The service responds to requests from clients for tokens. If the client is authenticated using a Windows account, the service issues a token that contains the client's user name as a claim. As part of creating the token, 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, STS also returns the symmetric key. The client presents the issued token to the ICalculator service and proves that it knows the symmetric key by signing the message with that key.

When you run the sample, the request for the security token is shown in the STS console window. The operation's 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.

The Setup.bat file included with this sample allows you to configure the server and STS with the relevant certificates to run a self-hosted application. The batch file creates two certificates in the LocalMachine/TrustedPeople certificate store. The first certificate has a subject name of CN=STS and is used by 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 STS to encrypt a key in a way that the service can decrypt.

To set up, build, and run the sample

  1. Ensure that you have performed the One-Time Setup Procedure for the Windows Communication Foundation Samples.

  2. Open a Developer Command Prompt for Visual Studio with administrator privileges and run the Setup.bat file to create the required certificates.

This batch file uses Certmgr.exe and Makecert.exe, which are distributed with the Windows SDK. However, you must run Setup.bat from within a Visual Studio command prompt to enable the script to find these tools.

  1. To build the C# or Visual Basic .NET edition of the solution, follow the instructions in Building the Windows Communication Foundation Samples.

  2. To run the sample in a single- or cross-computer configuration, follow the instructions in Running the Windows Communication Foundation Samples. If you are using Windows Vista, you must run Service.exe, Client.exe, and SecurityTokenService.exe with elevated privileges (right-click the files and then click Run as administrator).