How to: Sign a SOAP Message By Using a Security Context Token

The following procedures detail how to use policy or code to digitally sign a SOAP message by using a SecurityContextToken security token.

To use policy to sign a SOAP message by using a security context token

1. 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"     xmlns:wssp="https://schemas.xmlsoap.org/ws/2002/12/secext">
   

2. 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/2004/04/security/sc/sct.
      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 SecurityContextToken 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/2004/04/security/sc/sct</wssp:TokenType>
   

3. Specify the security token service that issued the token by adding a <TokenIssuer> Element (WSE for Microsoft .NET) (1) element.

   • 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 security token service that issued the SecurityContextToken security token.

   The following code example specifies that the http://www.cohowinery.com/secureConversation.ashx security token service issued the SecurityContextToken security token.

   <wssp:SecurityToken>
     <wssp:TokenIssuer>    http://www.cohowinery.com/secureConversation.ashx  </wssp:TokenIssuer>
   

4. 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 child element to the <mappings> Element element in the policy file for the application, 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 application's 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="https://localhost/SecureConvPolicyService/SecureConvService.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>
   

5. 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 Default attribute value to "https://schemas.xmlsoap.org/2002/12/wsse#part".
      The <MessageParts> Element for <Integrity> Element element specifies the XML elements that must be signed. The Dialect attribute specifies the expression dialect used to specify the parts of the SOAP message. The only dialect supported by WSE is "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>
   

6. Optionally, add a SecurityContextToken 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 SecurityContextToken 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 SecurityContextToken security token that it finds that matches the policy. If it does not find a match, WSE will attempt to request one from the security token service specified in the <TokenIssuer> Element (WSE for Microsoft .NET) (1) element (specified in step 3).

   The following code example adds a SecurityContextToken to the PolicyEnforcementSecurityTokenCache of the application.

   PolicyEnforcementSecurityTokenCache.GlobalCache.Add( token )
   

   PolicyEnforcementSecurityTokenCache.GlobalCache.Add( token );
   

To use code to sign a SOAP message by using a security context token

1. Obtain a security context token from a security token service. See How to: Obtain a Security Token From a Security Context Token Service.

2. Create a new instance of the proxy class for the Web service and get the SoapContext for the SOAP request to the Web service.

   Service1Wse is the name of the proxy class to the Web service in the following code example.

   Dim proxy As Service1Wse = New Service1Wse
   Dim requestContext As SoapContext = proxy.RequestSoapContext
   

   Service1Wse proxy = new Service1Wse();
   SoapContext requestContext = proxy.RequestSoapContext;
   

3. Add the security context token that is issued from the security token service to the SOAP message.

   For security reasons, it is highly recommended that the security context token's derived token be used to digitally sign or encrypt the SOAP message instead of the security context token itself so that the SOAP message is signed and/or encrypted using a key that changes. When a derived token is used, both the security context token and the derived token must be added to the SOAP message. To encrypt and sign a SOAP message, derive two tokens from the security context token. Use one token to encrypt the SOAP message and the other one to sign it. This will make it more difficult for the key to be compromised.

   The following code example creates a derived token from the security context token, and then adds both tokens to the SOAP message.

   Dim secContextToken As SecurityContextToken = _
       CType(tokenIssuingResponse.RequestedSecurityToken.SigningToken, _
       SecurityContextToken)
   Dim derivedToken As DerivedKeyToken = New _
       DerivedKeyToken(CType(secContextToken, IDerivableToken))
   requestContext.Security.Tokens.Add(secContextToken)
   requestContext.Security.Tokens.Add(derivedToken)
   

   SecurityContextToken secContextToken = (SecurityContextToken) tokenIssuingResponse.RequestedSecurityToken.SigningToken;
   DerivedKeyToken derivedToken = new 
       DerivedKeyToken((IDerivableToken)secContextToken);
   requestContext.Security.Tokens.Add(secContextToken;
   requestContext.Security.Tokens.Add(derivedToken);
   

4. Sign the SOAP request to the Web service by using the security context token.

   requestContext.Security.Elements.Add(New _
     MessageSignature(derivedToken))
   

   requestContext.Security.Elements.Add(new
     MessageSignature(derivedToken));
   

5. Call the Web service.

   Dim result as Integer = proxy.AddNumbers(a, b)
   

   int result = proxy.AddNumbers(a,b);
   

Example

The following code example is a policy file specifying that all sent SOAP messages must be signed using a DerivedKeyToken that is derived from a SecurityContextToken security token.

<?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="https://localhost/SecureConvPolicyService/SecureConvService.asmx">
      <defaultOperation>
        <request policy="#policy-c0a22319-6b89-49ff-9b82-bdbac5f04618" />
        <response policy="" />
        <!-- SOAP faults are signed using the original Security Context Token -->
        <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">          <wssp:TokenInfo>            <wssp:SecurityToken wse:IdentityToken="true">              <wssp:TokenType>https://schemas.xmlsoap.org/ws/2004/04/security/sc/dk</wssp:TokenType>              <wssp:Claims>                <wse:Parent>                  <wssp:SecurityToken>                    <wssp:TokenType>https://schemas.xmlsoap.org/ws/2004/04/security/sc/sct</wssp:TokenType>                    <wssp:Claims>                      <wse:BaseToken>                        <wssp:SecurityToken                          xmlns="https://schemas.xmlsoap.org/ws/2002/12/secext">                          <wssp:TokenType>http://docs.oasis-open.org/wss/2004/01-wss-username-token-profile-1.0#UsernameToken</wssp:TokenType>                        </wssp:SecurityToken>                      </wse:BaseToken>                      <wse:IssuerToken>                        <wssp:SecurityToken>                          <wssp:TokenType>http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-x509-token-profile-1.0#X509v3</wssp:TokenType>                          <wssp:Claims>                            <wssp:SubjectName>CN=WSE2QuickStartServer</wssp:SubjectName>                          </wssp:Claims>                        </wssp:SecurityToken>                      </wse:IssuerToken>                    </wssp:Claims>                  </wssp:SecurityToken>                </wse:Parent>              </wssp:Claims>            </wssp:SecurityToken>          </wssp:TokenInfo>          <wssp:MessageParts Dialect="https://schemas.xmlsoap.org/2002/12/wsse#part">              wse:Timestamp() wse:Addressing() wsp:Body()          </wssp:MessageParts>      </wssp:Integrity>
    </wsp:Policy>
  </policies>
</policyDocument>

The following example code signs a SOAP message by using a SecurityContextToken.

' Get a security token to sign the SOAP message that is sent to the
' security token service. 
Dim token As X509SecurityToken = GetSecurityToken()
If (token Is Nothing) Then
    Throw New ApplicationException("No key provided for signature.")
End If

' Create a new instance of the proxy class for the security token 
' service.
Dim tokenIssuingServiceProxy As SecurityContextTokenServiceClient = New _
SecurityContextTokenServiceClient(new Uri( _
"http://www.cohowinery.com/TokenIssuingService/secureConversation.ashx") ))

' Sign the security token request.
tokenIssuingServiceProxy.RequestSoapContext.Tokens.Add(token)
tokenIssuingServiceProxy.RequestSoapContext.Elements.Add _
(New MessageSignature(token))

' Request the token, use the signing token as the Base
Dim sct As SecurityContextToken = _
tokenIssuingServiceProxy.IssueSecurityContextTokenAuthenticated(token)

' Create a new instance of the Web service proxy.
Dim proxy As Service1Wse = New Service1Wse

' Get the SoapContext value for the SOAP request.
Dim requestContext As SoapContext = proxy.RequestSoapContext

' Convert the requested security token to a security context
' token.
Dim secContextToken As SecurityContextToken = _
    CType(tokenIssuingResponse.RequestedSecurityToken.SigningToken, _
    SecurityContextToken)

' Create a security token that is derived from the
' SecurityContextToken security token.
Dim derivedToken As DerivedKeyToken = New _
    DerivedKeyToken(CType(secContextToken, IDerivableToken))

' Add the token issued from the token issuing service to the SOAP
' message.
requestContext.Security.Tokens.Add(secContextToken)

' Add the derived security token to the SOAP message.
requestContext.Security.Tokens.Add(derivedToken)

' Sign the SOAP message by using the token issued from the security 
' token service.
requestContext.Security.Elements.Add(New MessageSignature(derivedToken))

' Communicate with the Web service.
Dim result As Integer proxy.AddNumbers(a, b)

// Get a security token to sign the SOAP message that is sent to the
// security token service. 
X509SecurityToken token = GetSecurityToken();
if (token == null)
   throw new ApplicationException("No key provided for signature.");

// Create a new instance of the proxy class for the security token 
// service.
SecurityContextTokenServiceClient tokenIssuingServiceProxy = new
SecurityContextTokenServiceClient(new Uri( 
"http://www.cohowinery.com/TokenIssuingService/secureConversation.ashx")));

// Sign the security token request.
tokenIssuingServiceProxy.RequestSoapContext.Tokens.Add(token);
tokenIssuingServiceProxy.RequestSoapContext.Elements.Add
(new MessageSignature(token));

// Request the token, use the signing token as the Base
SecurityContextToken sct =
tokenIssuingServiceProxy.IssueSecurityContextTokenAuthenticated(token);

// Get the SoapContext value for the SOAP request that will be sent
// to the target Web service.
Service1Wse proxy = new Service1Wse();
SoapContext requestContext = proxy.RequestSoapContext;

// Cast the requested security token to a security context token.
SecurityContextToken secContextToken = (SecurityContextToken)
    tokenIssuingResponse.RequestedSecurityToken.SigningToken;

// Create a security token that is derived from the
// SecurityContextToken security token.
DerivedKeyToken derivedToken = new
    DerivedKeyToken((IDerivableToken)secContextToken);

// Add the token issued from the token issuing service to the SOAP
// message.
requestContext.Security.Tokens.Add(secContextToken);

// Add the derived security token to the SOAP message.
requestContext.Security.Tokens.Add(derivedToken);

// Sign the SOAP message by using the token issued from the security
// token service.
requestContext.Security.Elements.Add(new MessageSignature(derivedToken));

// Communicate with the Web service.
int result = proxy.AddNumbers(a,b);

See Also

Tasks

How to: Verify Digital Signatures of SOAP Messages Signed Using a Security Context Token
How to: Specify the Parts of a SOAP Message That Are Signed or Encrypted

Reference

SecurityContextToken

Other Resources

Security Context Token