How to: Sign a SOAP Message By Using a Kerberos Ticket

Article
09/15/2006

The following procedures detail how to use policy or code to digitally sign a SOAP message by using a Kerberos service ticket. The procedure can be used with both the KerberosToken and KerberosToken2 security tokens. To use the procedure for KerberosToken2 security tokens, do the following:

In code examples, replace KerberosToken with KerberosToken2.
In policy examples, change the value of the <TokenType> Element element from https://schemas.xmlsoap.org/ws/2003/12/kerberos/Kerberosv5ST to https://schemas.xmlsoap.org/ws/2003/12/kerberos/Kerberosv5_AP_REQ.

For more details about the difference between the KerberosToken and KerberosToken2 security tokens, see Differences between KerberosToken and KerberosToken2.

To use policy to sign a SOAP message by using a Kerberos Ticket

Define a policy assertion and digital signature requirements by adding <Policy> Element (WSE for Microsoft .NET) (1) and <Integrity> Element elements.
1. Add a <Policy> Element (WSE for Microsoft .NET) (1) element to the policy file for the application. Add the <Policy> Element (WSE for Microsoft .NET) (1) element as a child element of the <policies> Element element.
  The <Policy> Element (WSE for Microsoft .NET) (1) element defines criteria that a SOAP message must meet. The criteria are specified as child elements of the <Policy> Element (WSE for Microsoft .NET) (1) element. The Id attribute value provides a name that is used by the <request> Element (WSE for Microsoft .NET), <response> Element (WSE for Microsoft .NET), and <fault> Element elements to refer to the policy assertion when applying the policy to an endpoint.
2. Add an <Integrity> Element child element to the <Policy> Element (WSE for Microsoft .NET) (1) element.
  The <Integrity> Element element defines digital signature requirements. The Usage attribute value of "Required" specifies that a signature is required, and additional requirements are specified in child elements.
The following code example defines a policy assertion named policy-c0a22319-6b89-49ff-9b82-bdbac5f04618 and specifies that there are digital signature requirements.
```
              <wsp:Policy wsu:Id="policy-c0a22319-6b89-49ff-9b82-bdbac5f04618"
  xmlns:wsp="https://schemas.xmlsoap.org/ws/2002/12/policy"
  xmlns:wsa="https://schemas.xmlsoap.org/ws/2004/03/addressing">
  <wssp:Integrity wsp:Usage="wsp:Required" 
```
Specify the token type by adding <TokenInfo> Element, <SecurityToken> Element, and <TokenType> Element elements.
1. Add a <TokenInfo> Element child element to the <Integrity> Element element.
2. Add a <SecurityToken> Element child element to the <TokenInfo> Element element.
3. Add a <TokenType> Element child element to the <SecurityToken> Element element and set its value to https://schemas.xmlsoap.org/ws/2003/12/kerberos/Kerberosv5ST.
  The <TokenType> Element element specifies the type of security token that must be used to create the digital signature.
The following code example specifies that a KerberosToken security token must be used to digitally sign the SOAP message.
```
<wssp:Integrity wsp:Usage="wsp:Required"
  xmlns:wssp="https://schemas.xmlsoap.org/ws/2002/12/secext">
  <wssp:TokenInfo>    <wssp:SecurityToken>      <wssp:TokenType>https://schemas.xmlsoap.org/ws/2003/12/kerberos/Kerberosv5ST</wssp:TokenType>
```
Optionally, specify requirements for the token by adding <Claims> Element, <ServiceName> Element, and <TokenIssuer> Element (WSE for Microsoft .NET) (1) elements
1. Add a <Claims> Element child element to the <SecurityToken> Element element.
2. Add a <ServiceName> Element child element to the <Claims> Element element.
  The <ServiceName> Element element specifies the service principal name in the following format: host/hostname@domain, where hostname is the name of the computer receiving the SOAP message and domain is the fully qualified domain name of the Kerberos realm in which the host computer resides.
  
  Note
  
  Kerberos tickets are obtained using the current user's credentials. Therefore, when a <ServiceName> Element element is specified, WSE attempts to obtain a Kerberos service ticket from the Key Distribution Center (KDC) for communication between the current user and the computer specified in the <ServiceName> Element element.
3. Add a <TokenIssuer> Element (WSE for Microsoft .NET) (1) child element to the <SecurityToken> Element element
  The <TokenIssuer> Element (WSE for Microsoft .NET) (1) element specifies the domain, also known as the Kerberos realm, which issued the Kerberos ticket. WSE does not support Kerberos delegation, so this must be the same realm the recipient is a member of.
  
  Note
  
  The value of the <TokenIssuer> Element (WSE for Microsoft .NET) (1) element must be in uppercase.
The following code example specifies that a Kerberos service ticket must be used to sign SOAP messages. Furthermore, the Kerberos service ticket must be obtained from a KDC in the CONTOSO realm for the computer named computer1.
```
<wssp:Integrity wsp:Usage="wsp:Required"
  xmlns:wssp="https://schemas.xmlsoap.org/ws/2002/12/secext">
  <wssp:TokenInfo>
    <SecurityToken xmlns="https://schemas.xmlsoap.org/ws/2002/12/secext">
      <wssp:TokenType>https://schemas.xmlsoap.org/ws/2003/12/kerberos/Kerberosv5ST</wssp:TokenType>
        <wssp:TokenIssuer>CONTOSO</wssp:TokenIssuer>        <wssp:Claims>          <wssp:ServiceName>host/computer1@contoso.com</wssp:ServiceName>        </wssp:Claims>
    </SecurityToken>
  </wssp:TokenInfo>
```
Map the policy assertion to an endpoint by adding an <endpoint> Element element. Optionally, designate the policy as the default for all SOAP messages by adding the <defaultOperation> Element element.
1. Add an <endpoint> Element element to the <mappings> Element element, and set the uri attribute value to the URI of the application.
  The <endpoint> Element element maps a policy assertion to an endpoint. The uri attribute value specifies the URI of the service to which the policy is mapped.
2. Add a <defaultOperation> Element child element to the <endpoint> Element element.
  The <defaultOperation> Element element specifies the default policy for all operations at the URI specified in the uri attribute.
3. Add <request> Element (WSE for Microsoft .NET), <response> Element (WSE for Microsoft .NET), and <fault> Element child elements to the <defaultOperation> Element element. The value of the policy attribute must match the value of the Id attribute of the <Policy> Element (WSE for Microsoft .NET) (1) element that defines the policy assertion.
The following code example sets the default policy for all SOAP messages to the policy-c0a22319-6b89-49ff-9b82-bdbac5f04618 policy assertion.
```
<mappings xmlns:wse="https://schemas.microsoft.com/wse/2003/06/Policy">
  <endpoint uri="http://www.cohowinery.com/SaleWidgets.asmx">    <defaultOperation>      <request policy="#policy-c0a22319-6b89-49ff-9b82-bdbac5f04618" />      <response policy=="#policy-c0a22319-6b89-49ff-9b82-bdbac5f04618" />      <fault policy="#policy-c0a22319-6b89-49ff-9b82-bdbac5f04618" />    </defaultOperation>  </endpoint></mappings>
```
Specify the XML elements to be signed by adding a <MessageParts> Element for <Integrity> Element element to the <Integrity> Element element.
1. Add a <MessageParts> Element for <Integrity> Element child element to the <Integrity> Element element in the policy file for the application, and set the Dialect attribute value to "https://schemas.xmlsoap.org/2002/12/wsse#part".
2. Specify the parts of the message to be signed by listing them, separated by spaces, as the value of the <MessageParts> Element for <Integrity> Element element.
The following code example specifies that the <Body> element and the To, Action, MessageID, and From headers are signed.
```
<wssp:MessageParts Dialect="https://schemas.xmlsoap.org/2002/12/wsse#part">
  wsp:Body() wsp:Header(wsa:To) wsp:Header(wsa:Action) wsp:Header(wsa:MessageID) wsp:Header(wsa:From)
</wssp:MessageParts>
```
Optionally, add a KerberosToken security token that meets the policy requirements to the PolicyEnforcementSecurityTokenCache of the application where you are sending the SOAP message.

This step is optional because WSE looks in the following caches in the specified order to find a KerberosToken security token that matches the policy:
1. The Tokens collection of the SoapContext associated with the SOAP message.
2. The PolicyEnforcementSecurityTokenCache token cache.
WSE uses the first KerberosToken security token that it finds that matches the policy. If it does not find a match, WSE will attempt to request a Kerberos ticket from a KDC in the current domain or the one specified in the <TokenIssuer> Element (WSE for Microsoft .NET) (1) element (specified in step 3).

The following code example adds a KerberosToken to the PolicyEnforcementSecurityTokenCache.
```
PolicyEnforcementSecurityTokenCache.GlobalCache.Add( token )
```
```
PolicyEnforcementSecurityTokenCache.GlobalCache.Add( token );
```

To use code to sign a SOAP message by using a Kerberos ticket

Open the Web service client project in Visual Studio .NET 2003.
Add references to the Microsoft.Web.Services2, System.Web.Services, and System.Security assemblies.
1. On the Project menu, click Add Reference.
2. Click the .NET tab, select Microsoft.Web.Services2.dll, and then click Select.
3. On the .NET tab, select System.Web.Services.dll, and then click Select.
4. On the .NET tab, select System.Security.dll, and then click Select.
5. Click OK.
Add a Web reference to the Web service that is to receive the SOAP message encrypted with the Kerberos ticket.
1. On the Project menu, click Add Web Reference.
2. In the Add Web Reference dialog box, type the URL for the Web service in the Address box, and then click the arrow icon.
3. Verify that the items in the Available references box are the items you want to reference in your project, and then click Add Reference.
Edit the proxy class to derive from the WebServicesClientProtocol class.
1. In Solution Explorer, right-click the Reference.cs file for the Web reference just added, and then click View Code.
  
  Note
  
  If the Reference.cs file containing the proxy class is not visible, click the show all files icon on the Solution Explorer toolbar, and then expand the Reference.map node.
2. Change the base class of the proxy class to the Microsoft.Web.Services2.WebServicesClientProtocol class.
  This modifies the proxy class to emit WS-Addressing and WS-Security SOAP headers when communicating with the Web service. The following code example modifies a proxy class named Service1 to derive from Microsoft.Web.Services2.WebServicesClientProtocol.
```
Public Class Service1
   Inherits Microsoft.Web.Services2.WebServicesClientProtocol
```
```
public class Service1 : Microsoft.Web.Services2.WebServicesClientProtocol {
```
  Note
  
  If you select Update Web Reference in Visual Studio .NET 2003, the proxy class is regenerated, the base class is reset to the SoapHttpClientProtocol class, and you must repeat this step.

Add the Imports or using directives to the top of the file that communicates with the Web service.

In Solution Explorer, right-click the file containing the client code, and then click View Code.

At the top of the file, add the directives as shown in the following code example.

Imports Microsoft.Web.Services2
Imports Microsoft.Web.Services2.Security
Imports Microsoft.Web.Services2.Security.Tokens
Imports Microsoft.Web.Services2.Security.Kerberos

using Microsoft.Web.Services2;
using Microsoft.Web.Services2.Security;
using Microsoft.Web.Services2.Security.Tokens;
using Microsoft.Web.Services2.Security.Kerberos;

Add code to create a KerberosToken security token.

The hostname variable is the name of the computer hosting the target Web service, and the dnsDomainName variable is the Kerberos realm that the host is a member of. The Kerberos realm is needed only when the SOAP message sender resides in a different domain or realm from the target Web service.
```
Dim kerbToken As New KerberosToken("host/" + hostname + _
  "@" + dnsDomainName)
```
```
KerberosToken kerbToken = new KerberosToken( "host/" + hostname + "@" + dnsDomainName);
```
Specify that the KerberosToken security token must sign the SOAP request.

For information about signing portions of the SOAP message other than the defaults, see How to: Specify the Parts of a SOAP Message That Are Signed or Encrypted.
1. Get the SoapContext value for the SOAP request that is being made to the Web service.
  Service1 is the name of the proxy class to the Web service in the following code example.
```
Dim svc As New Service1()
Dim requestContext As SoapContext = svc.RequestSoapContext
```
```
Service1 svc = new Service1();
SoapContext requestContext = svc.RequestSoapContext;
```
2. Add the KerberosToken security token to the WS-Security SOAP header.
```
requestContext.Security.Tokens.Add(kerbToken)
```
```
requestContext.Security.Tokens.Add(kerbToken);
```
3. Create a new instance of the MessageSignature class by using the KerberosToken security token just added to the WS-Security SOAP header.
```
Dim sig As New MessageSignature(kerbToken)
```
```
MessageSignature sig = new MessageSignature(kerbToken);
```
4. Add the digital signature to the WS-Security SOAP header.
```
RequestContext.Security.Elements.Add(sig)
```
```
RequestContext.Security.Elements.Add(sig);
```
5. Specify the time-to-live (TTL) for the SOAP message to diminish the chance of someone intercepting the message and replaying it.
  The following code example sets the TTL to 1 minute.
```
requestContext.Security.Timestamp.TtlInSeconds = 60
```
```
requestContext.Security.Timestamp.TtlInSeconds = 60;
```
6. Call the Web service.
```
svc.sayHello()
```
```
svc.sayHello();
```

Example

The following code example is a policy file specifying that all SOAP messages sent to the http://www.cohowinery.com/SaleWidgets.asmx endpoint must have the <Body> element and the To, Action, MessageID, and From headers signed by a Kerberos service ticket issued from the COHOWINERY realm for communication between the current user and the computer named computer1@cohowinery.com.

Note

This code example is designed to demonstrate WSE features and is not intended for production use.

<?xml version="1.0" encoding="utf-8"?>
<policyDocument xmlns="https://schemas.microsoft.com/wse/2003/06/Policy">
  <mappings xmlns:wse="https://schemas.microsoft.com/wse/2003/06/Policy">
    <endpoint uri="http://www.cohowinery.com/SaleWidgets.asmx">
      <defaultOperation>
        <request policy="#policy-c0a22319-6b89-49ff-9b82-bdbac5f04618" />
        <response policy="#policy-c0a22319-6b89-49ff-9b82-bdbac5f04618" />
        <fault policy="#policy-c0a22319-6b89-49ff-9b82-bdbac5f04618" />
      </defaultOperation>
    </endpoint>
  </mappings>
  <policies xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
    <wsp:Policy wsu:Id="policy-c0a22319-6b89-49ff-9b82-bdbac5f04618"
      xmlns:wsp="https://schemas.xmlsoap.org/ws/2002/12/policy"
      xmlns:wsa="https://schemas.xmlsoap.org/ws/2004/03/addressing" >
      <wssp:Integrity wsp:Usage="wsp:Required"
        xmlns:wssp="https://schemas.xmlsoap.org/ws/2002/12/secext">
        <wssp:TokenInfo>
          <SecurityToken xmlns="https://schemas.xmlsoap.org/ws/2002/12/secext">
            <wssp:TokenType>https://schemas.xmlsoap.org/ws/2003/12/kerberos/Kerberosv5ST</wssp:TokenType>
            <wssp:TokenIssuer>COHOWINERY</wssp:TokenIssuer>
            <wssp:Claims>
              <wssp:ServiceName>host/computer1@cohowinery.com</wssp:ServiceName>
            </wssp:Claims>
          </SecurityToken>
        </wssp:TokenInfo>
        <wssp:MessageParts Dialect="https://schemas.xmlsoap.org/2002/12/wsse#part">
            wsp:Body() wsp:Header(wsa:To) wsp:Header(wsa:Action) wsp:Header(wsa:MessageID) wsp:Header(wsa:From)
        </wssp:MessageParts>
      </wssp:Integrity>
    </wsp:Policy>
  </policies>
</policyDocument>

The following code example creates a new KerberosToken security token, and then signs a SOAP request by using the token.

Try
    Dim kerbToken As New KerberosToken( "host/" + hostname + _
      "@" + domainName)
    Dim svc As New Proxy.Service1() 
    Dim requestContext As SoapContext = svc.RequestSoapContext
   
    ' Set the TTL to one minute.
    requestContext.Security.Timestamp.TtlInSeconds = 60
   
    ' Add the security token. 
    requestContext.Security.Tokens.Add(kerbToken)

    ' Specify the security token to sign the message with.
    requestContext.Security.Elements.Add(new MessageSignature(kerbToken))

    MessageBox.Show( svc.sayHello() )
Catch ex As Exception
    MessageBox.Show( ex.ToString() )
End Try

try 
{
    KerberosToken kerbToken = new KerberosToken( "host/" + hostname +
      "@" + domainName);
     
    Proxy.Service1 svc = new Proxy.Service1();
    SoapContext requestContext = svc.RequestSoapContext;

    // Set the TTL to one minute.
    requestContext.Security.Timestamp.TtlInSeconds = 60;
    
    // Add the security token.                
    requestContext.Security.Tokens.Add(kerbToken);
    // Specify the security token to sign the message with.
    requestContext.Security.Elements.Add(new
      MessageSignature(kerbToken));

    MessageBox.Show( svc.sayHello() );
}
catch (Exception ex) 
{
    MessageBox.Show( ex.ToString() );
}

How to: Sign a SOAP Message By Using a Kerberos Ticket

To use policy to sign a SOAP message by using a Kerberos Ticket

To use code to sign a SOAP message by using a Kerberos ticket

Example

See Also

Tasks

Reference

Other Resources

Additional resources