How to: Secure a Client Using a Policy File

Article
09/13/2006

To secure a client using a turnkey security assertion, do two things:

Define and name a policy.
Call the SetPolicy method of the proxy class with the policy name.

This topic describes how to define the policy using the WSE Settings 3.0 Tool and then shows how to call the SetPolicy method. If you do not want to use the tool, see How to: Secure an Application Using a Custom Policy Assertion.

To security a client using a policy file

Open the client project in Visual Studio 2005.
Run the WSE Settings 3.0 Tool.
1. In Solution Explorer, right-click the project name, and then click WSE Settings 3.0….
2. Select the Policy tab.
3. Click Add….
4. Provide a name for the client's policy, such as ClientPolicy. This name is used in the policy file and the client's code.
5. Click OK to dismiss the dialog.
The WSE Security Settings Wizard appears.
Click Next.
Click Secure a client application.

Choose the client authentication method, and then click Next.

The following table describes the options for authenticating clients.

Option	Description
Anonymous	No client credentials are required.
Username	Clients are required to send a UsernameToken security token that contains their username and password.
Certificate	Clients are required to send an X509SecurityToken security token that represents an X.509 certificate.
Windows	Clients are required to send a KerberosToken security token that contains a Windows identity.

Specify details about the security credentials used for authentication, and then click Next.

Specify how SOAP messages sent to and from this client are protected.

Select Enable WS-Security 1.1 Extensions to use WS-Security 1.1.
To use WS-Security 1.1 features, both the client and Web service must support the WS-Security 1.1 specification. WS-Security 1.1 extensions include the EncryptedKeyToken security token, digital signature confirmation, and a new method for calculating the subject key identifier for X509SecurityToken security tokens.

Specify the protection (integrity and confidentiality) requirements for SOAP messages sent to and from the client.
The following table describes the options for protecting SOAP messages sent to and from this client.

Option	Description
None	SOAP message protection should be provided at the transport layer (SSL). WSE does not enforce this transport layer protection.
Sign-Only	SOAP messages must be digitally signed.
Sign and Encrypt	SOAP messages must be digitally signed and the SOAP body encrypted.
Sign, Encrypt, Encrypt Signature	SOAP messages must be digitally signed, and the SOAP body and digital signature encrypted.

Select Establish Secure Session when multiple SOAP messages are exchanged between the client and Web service.
The Establish Secure Session option specifies that the Web service issues a SecurityContextToken security token to the client, which is then used to protect SOAP messages sent to and from the Web service. When multiple SOAP messages are exchanged between a client and a Web service, the use of a SecurityContextToken security token typically increases performance. Performance is increased by two measures: smaller SOAP message payload and less work to encrypt SOAP messages and generate digital signatures. The SOAP message payload is only decreased when a stateless SecurityContextToken security token is used. For details about using a stateless SecurityContextToken security token, see <statefulSecurityContextToken> Element. Cryptographic operations based on asymmetric keys require more work than those done using symmetric keys. SecurityContextToken security tokens use a symmetric key.

Specify the security credentials that are used to encrypt SOAP requests and/or digitally sign SOAP responses from the Web service, and then click Next.
Click Finish.

This dialog displays the turnkey security assertion and its settings that are used to create the policy. This policy is added to the policy file for the project. If a policy file does not already exist, one is created.

Click OK.

The WSE Settings 3.0 Tool is dismissed.

The following code example shows a policy named ClientPolicy that was generated using the WSE Settings 3.0 Tool.

<policies>
  <extensions>
    <extension name="kerberosSecurity"
               type="Microsoft.Web.Services3.Design.KerberosAssertion, Microsoft.Web.Services3, Version=3.0.0.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35" />
    <extension name="kerberos"
               type="Microsoft.Web.Services3.Design.KerberosTokenProvider, Microsoft.Web.Services3, Version=3.0.0.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35" />
    <extension name="requireActionHeader"
               type="Microsoft.Web.Services3.Design.RequireActionHeaderAssertion, Microsoft.Web.Services3, Version=3.0.0.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35" />
  </extensions>
  <policy name="ClientPolicy">
    <kerberosSecurity establishSecurityContext="false" signatureConfirmation="false" protectionOrder="SignBeforeEncrypting" deriveKeys="false" >
      <token>
        <kerberos targetPrincipal="host/contoso4" impersonationLevel="Identification" />
      </token>
      <protection>
        <request signatureOptions="IncludeAddressing, IncludeTimestamp, IncludeSoapBody" 
                 encryptBody="true" />
        <response signatureOptions="IncludeAddressing, IncludeTimestamp, IncludeSoapBody" 
                 encryptBody="true" />
        <fault signatureOptions="IncludeAddressing, IncludeTimestamp, IncludeSoapBody" 
                 encryptBody="false" />
      </protection>
    </kerberosSecurity>
    <requireActionHeader />
  </policy>
</policies>

Call the SetPolicy method of the proxy class with the policy name.

The following code example specifies that the policy for the client is named ClientPolicy.
```
proxy.SetPolicy("ClientPolicy")
```
```
proxy.SetPolicy("ClientPolicy");
```

Example

The following code example specifies that the policy for the client is named ClientPolicy.

Dim proxy As New ServiceWse
proxy.SetPolicy("ClientPolicy")
Console.WriteLine("Web Service returned: {0}", proxy.HelloWorld())

ServiceWse proxy = new ServiceWse();
proxy.SetPolicy("ClientPolicy");
Console.WriteLine("Web Service returned: {0}", proxy.HelloWorld());

How to: Secure a Client Using a Policy File

To security a client using a policy file

Example

See Also

Tasks

Reference

Concepts

Additional resources