How to: Secure a Client Using Mixed Policy and Code

Article
09/13/2006

To secure a client using a turnkey security assertion with security credentials that should not be in a policy file, such as a user name and password, do three things:

Define and name a policy in a policy file.
In the client application's code, call the SetClientCredential generic method of the proxy class with the client's credentials.
In the client application's code, 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 SetClientCredential and SetPolicy methods.

To secure a client using a policy file and client code

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 authentication method used by the Web service that the client is calling, 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 user name and password. This user name and password should be specified in the client application's code.
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.

Select the option to specify the client credentials in code, such as Specify Username Token in code, 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. 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="usernameForCertificateSecurity"
               type="Microsoft.Web.Services3.Design.UsernameForCertificateAssertion, Microsoft.Web.Services3, Version=3.0.0.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35" />
    <extension name="x509"
               type="Microsoft.Web.Services3.Design.X509TokenProvider, 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">
    <usernameForCertificateSecurity establishSecurityContext="false" renewExpiredSecurityContext="true" signatureConfirmation="false" protectionOrder="SignBeforeEncrypting" deriveKeys="true" >
      <serviceToken>
        <x509 storeLocation="CurrentUser"
              storeName="AddressBook"
              findValue="CN=WSE2QuickStartServer"
              findType="FindBySubjectDistinguishedName" />
      </serviceToken>
      <protection>
        <request signatureOptions="IncludeAddressing, IncludeTimestamp, IncludeSoapBody"
                 encryptBody="true" />
        <response signatureOptions="IncludeAddressing, IncludeTimestamp, IncludeSoapBody"
                 encryptBody="true" />
        <fault signatureOptions="IncludeAddressing, IncludeTimestamp, IncludeSoapBody"
                 encryptBody="false" />
      </protection>
    </usernameForCertificateSecurity>
    <requireActionHeader />
  </policy>
</policies>

In the client application's code, call the SetClientCredential generic method of the proxy class with the client's credentials.

The following code example specifies the client's credentials, which is a UsernameToken security token, in code.

Note

The following code example specifies a type parameter list for the SetClientCredential generic method, but it can be omitted because the compiler will infer the type.

' This is the client's credentials that is set in code.
Dim token As UsernameToken = Nothing
Dim username As String = Environment.UserName
Dim password As String = GetUsersPassword(username)
token = New UsernameToken(username, password)

' Username and password are set through code.
proxy.SetClientCredential(Of UsernameToken)(token)

// This is the client's credentials that is set in code.
UsernameToken token = null;

string username = Environment.UserName;
string password = GetUsersPassword(username);
token = new UsernameToken(username, password);

// Username and password are set through code.
proxy.SetClientCredential<UsernameToken>(token);

Example

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

Dim proxy As New ServiceWse
' This is the client's credentials that is set in code.
Dim token As UsernameToken = Nothing
Dim username As String = Environment.UserName
Dim password As String = GetUsersPassword(username)
token = New UsernameToken(username, password)

' Username and password are set through code.
proxy.SetClientCredential(Of UsernameToken)(token)
proxy.SetPolicy("ClientPolicy")
Console.WriteLine("Web Service returned: {0}", proxy.HelloWorld())

ServiceWse proxy = new ServiceWse();

// This is the client's credentials that is set in code.
UsernameToken token = null;

string username = Environment.UserName;
string password = GetUsersPassword(username);
token = new UsernameToken(username, password);

// Username and password are set through code.
proxy.SetClientCredential<UsernameToken>(token);
proxy.SetPolicy("ClientPolicy");
Console.WriteLine("Web Service returned: {0}", proxy.HelloWorld());

How to: Secure a Client Using Mixed Policy and Code

To secure a client using a policy file and client code

Example

See Also

Tasks

Reference

Concepts

Additional resources