How to: Secure a Web Service Using a Policy File

Article
09/13/2006

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

Define and name a policy.
Apply a PolicyAttribute attribute to the Web service specifying the name of the policy.

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

To secure a Web service using a turnkey security assertion

Open the Web service 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 Web service's policy, such as ServicePolicy. This name is used in the policy file and the Web service's code.
5. Click OK to dismiss the dialog.
The WSE Security Settings Wizard appears.
Click Next.
Click Secure a service 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 Web service 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 called Thumbprints. For more information about digital signature confirmations, see SignatureConfirmation.

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

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 signed.
Sign and Encrypt	SOAP messages must be signed and the SOAP body encrypted.
Sign, Encrypt, Encrypt Signature	SOAP messages must be signed, and the SOAP body and 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 decreased only 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.

Optionally, specify the security credentials that are used to encrypt SOAP responses or digitally sign SOAP requests from the Web service, and then click Next.

Note

Depending on the authentication method chosen, this dialog might not appear.
Click Finish.

This dialog displays the turnkey security assertion and its settings that were 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 first.

Note

By default, the WSE Settings 3.0 Tool adds a <requireActionHeader> Element to any policy that has protection requirements. By adding this policy assertion, WSE is helping to mitigate attacks against SOAP requests that contain the SOAPAction HTTP header, but do not include the WS-Addressing <Action> SOAP header. When WSE receives a SOAP message that does not contain an <Action> SOAP header, but does contain a SOAPAction HTTP header, it dispatches the SOAP message to the Web service method based on the SOAPAction header. The SOAPAction header, however cannot be digitally signed and thus is prone to being changed without a recipient knowing so. By contrast, the <Action> SOAP header, which WSE dispatches the SOAP message on when present by default, a Web service's policy can require to be digitally signed by including the IncludeAddressing option in the signatureOptions attribute of the <request> element. By combining the use of the <requireActionHeader> Element and requiring the <Action> header to be signed allows WSE to detect for a Web service that the action value has changed. WSE throws a SOAP fault when it detects that it has changed.

Note

Avoid using the System.Web.Services.Protocols.SoapServiceRoutingStyle.RequestElement routing style, which is not the default, because an unexpected policy might be applied to incoming SOAP requests. This problem arises when a Web service has a policy that has per-action protection requirements and the System.Web.Services.Protocols.SoapServiceRoutingStyle.RequestElement routing style, which causes ASP.NET to dispatch incoming SOAP requests to a Web service method's code base upon the first child element of the <Body> element. Per-action protection requirements are specified by using the requestAction attribute of the <protection> Element in a policy file. When the SOAP message's action is different than the name of the first child element of the <Body> element, then the policy requirements are enforced based on the action, yet the SOAP message is not dispatched to the Web service method corresponding to the action. It is dispatched to the Web service method that is named the same as the first child element of the <Body> element. To ensure the routing style is not set to RequestElement, check the RoutingStyle property of the System.Web.Services.Protocols.SoapDocumentServiceAttribute that is applied to the class implementing the ASP.NET Web service. When the RoutingStyle property is not specified, the default value is SoapAction.

Click OK.

The WSE Settings 3.0 Tool is dismissed.

The following code example shows a policy named ServicePolicy 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="ServicePolicy">
    <kerberosSecurity establishSecurityContext="false" signatureConfirmation="false" protectionOrder="SignBeforeEncrypting" deriveKeys="false">
      <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>

Apply a PolicyAttribute attribute to the Web service.

The PolicyAttribute attribute can be applied to the class that is implementing the Web service methods. This applies the policy to all Web service methods (operations) within that class.

The following code example specifies that all Web service methods within the Service class adhere to the ServicePolicy policy.

<WebService(Namespace:="https://www.contoso.com/")> _
<WebServiceBinding(ConformsTo:=WsiProfiles.BasicProfile1_1)> _
<Policy("ServicePolicy")> _
Public Class Service
    Inherits System.Web.Services.WebService

[WebService(Namespace = "https://www.contoso.com/")]
[WebServiceBinding(ConformsTo = WsiProfiles.BasicProfile1_1)]
[Policy("ServicePolicy")] 
public class Service : System.Web.Services.WebService
{

Example

The following code example applies the ServicePolicy policy to all Web service methods in the Service class.

Imports System.Web
Imports System.Web.Services
Imports System.Web.Services.Protocols
Imports Microsoft.Web.Services3
Imports Microsoft.Web.Services3.Design

<WebService(Namespace:="https://www.contoso.com/")> _
<WebServiceBinding(ConformsTo:=WsiProfiles.BasicProfile1_1)> _
<Policy("ServicePolicy")> _
Public Class Service
    Inherits System.Web.Services.WebService
    Public Sub Service()

    End Sub

    <WebMethod()> _
    Public Function SayHello() As String
        Return "Hello World"
    End Function

End Class

using System;
using System.Web;
using System.Web.Services;
using System.Web.Services.Protocols;
using Microsoft.Web.Services3;
using Microsoft.Web.Services3.Design;

[WebService(Namespace = "https://www.contoso.com/")]
[WebServiceBinding(ConformsTo = WsiProfiles.BasicProfile1_1)]
[Policy("ServicePolicy")] 
public class Service : System.Web.Services.WebService
{
    public Service () {

    }

    [WebMethod]
    public string SayHello() {
        return "Hello World";
    }
    
}

How to: Secure a Web Service Using a Policy File

To secure a Web service using a turnkey security assertion

Example

See Also

Tasks

Reference

Concepts

Additional resources