Using WS-Trust and WS-SecureConversation

2007-04-03

Martin Gudgin
Microsoft Corporation

May 2004

Introduction

WS-Security provides a framework for securing SOAP messages based on XML Encryption, XML Signature and the notion of security tokens. XML Encryption is used to provide confidentiality protection for portions of a SOAP envelope while XML Signature is used to provide integrity protection for the same. Security tokens typically provide some notion of identity along with information pertaining to keys used to perform cryptographic operations. Multiple security tokens can be used in a message allowing different portions of the SOAP envelope to be secured for different intermediaries. Examples of security tokens include X509 certificates, Kerberos tickets and Username tokens. While WS-Security specifies mechanisms for placing security tokens in SOAP messages and referring to those tokens from encrypted or signed data it does not define how security tokens are actually acquired; that job can either be programmatic, or performed by calling a token issuing service as specified by WS-Trust.

WS-Trust builds on the framework provided by WS-Security, defining SOAP based mechanisms for brokering trust relationships, requesting and returning security tokens. While the specification has a myriad of options, the core premise is straightforward; requests can be made asking a Security Token Service to return a security token with some particular characteristics. The request is itself based on some existing security token that the requester and the Security Token Service already have some knowledge of. This often translates to the request being signed by the requestor.

Requesting Tokens

Requests for security tokens are made by sending a Request Security Token (RST) message to the Security Token Service. The current specification defines three possible actions that can be performed; issue a new token, renew a token or validate a token. Figure 1 shows an example request to issue a token, in this case for some custom XML based security token. The request includes an X509 certificate that is used as the basis for the request, referred to from the wst:Base element in the body. The value of the wsa:Action header element and the value of the wst:RequestType element in the body tells the Security Token Service that the request is for a security token to be issued. The wst:TokenType element in the body specifies the type of token to be issued, in this case some XML based security token. The security token service will verify that it recognizes the X509 certificate and that the holder of that certificate is authorized to be issued with the custom token.

<s:Envelope xmlns:s='http://www.w3.org/2003/05/soap-envelope' 
 xmlns:wss='http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-
wssecurity-secext-1.0.xsd' 
 xmlns:wsu='http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-
wssecurity-utility-1.0.xsd'
 xmlns:wst='https://schemas.xmlsoap.org/ws/2004/04/trust'
 xmlns:wsa='https://schemas.xmlsoap.org/ws/2004/03/addressing' >
 <s:Header>
  <wsa:Action>
  https://schemas.xmlsoap.org/ws/2004/04/security/trust/RST/Issue
  </wsa:Action>
  <wsa:To>http://example.org/mywebservice</wsa:To>
  <wsa:ReplyTo>
   <wsa:Address>
   https://schemas.xmlsoap.org/ws/2004/03/addressing/role/anonymous
   </wsa:Address>
  </wsa:ReplyTo>
  <wsa:MessageID>
  uuid:3e9c26fb-f297-490f-a8c8-c6cef961bfc6
  </wsa:MessageID>
  <wss:Security>
   <wss:BinarySecurityToken wsu:Id='Me' 
    ValueType='http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-
x509-token-profile-1.0#X509v3'
    EncodingType='http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-
soap-message-security-1.0#Base64Binary' >
   dX5CZ8lqZl1X2v1s/uqwDddPOqnauJGTmKoEjQGn...
   </wss:BinarySecurityToken>
   <ds:Signature xmlns:ds='http://www.w3.org/2000/09/xmldsig#' >
    <!-- Signature over the request -->
   </ds:Signature>
  </wss:Security>
 </s:Header>
 <s:Body>
  <wst:RequestSecurityToken>
   <wst:TokenType>
   http://example.org/mysecuritytoken
   </wst:TokenType>
   <wst:RequestType>
   https://schemas.xmlsoap.org/ws/2004/04/security/trust/Issue
   </wst:RequestType>
   <wst:Base>
    <wss:SecurityTokenReference>
     <wss:Reference URI='#Me' ValueType='http://docs.oasis-
open.org/wss/2004/01/oasis-200401-wss-x509-token-profile-1.0#X509v3' />
    </wss:SecurityTokenReference>
   </wst:Base>
  </wst:RequestSecurityToken>
 </s:Body>
</s:Envelope>

Figure 1. Request for a security token

Requested Token and Proof Token

Once the security token service has verified the request, it returns the requested token, in this case the requested custom XML token, along with something called a proof token. The requested token can be used by the receiver verbatim; placed in a subsequent SOAP message and referred to using the mechanisms defined in WS-Security. The proof token contains information that the receiver needs in order to prove it is able to use the returned token. In this example, this is a secret key. In order to ensure that only the original requestor can determine the value of the secret key, the key is encrypted using the public key in the X509 certificate of the original request. The custom XML token is returned in a wst:RequestedSecurityToken element in the body of the response while the proof token, the secret key, is returned in a wst:RequestedProofToken element. Figure 2 shows an example response containing a security token and a corresponding proof token.

<s:Envelope xmlns:s='http://www.w3.org/2003/05/soap-envelope' 
 xmlns:wss='http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-
wssecurity-secext-1.0.xsd' 
 xmlns:wsu='http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-
wssecurity-utility-1.0.xsd'
 xmlns:wst='https://schemas.xmlsoap.org/ws/2004/04/trust'
 xmlns:wsa='https://schemas.xmlsoap.org/ws/2004/03/addressing' 
 xmlns:ds='http://www.w3.org/2000/09/xmldsig#'>
 <s:Header>
  <wsa:Action>
  https://schemas.xmlsoap.org/ws/2004/04/security/trust/RSTR/Issue
  </wsa:Action>
  <wsa:To>
  https://schemas.xmlsoap.org/ws/2004/03/addressing/role/anonymous
  </wsa:To>
  <wsa:MessageID>
  uuid:cca4b954-ab8c-45ce-83b9-1ee1d1e3d4eb
  </wsa:MessageID>
  <wsa:RelatesTo>
  uuid:3e9c26fb-f297-490f-a8c8-c6cef961bfc6
  </wsa:RelatesTo>
  <wss:Security>
   <wss:BinarySecurityToken wsu:Id='You' 
    ValueType='http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-
x509-token-profile-1.0#X509v3'
    EncodingType='http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-
soap-message-security-1.0#Base64Binary' >
   dX5CZ8lqZl1X2v1s/uqwDddPOqnauJGTmKoEjQGn...
   </wss:BinarySecurityToken>
   <ds:Signature>
    <!-- Signature over the response -->
   </ds:Signature>
  </wss:Security>
 </s:Header>
 <s:Body>
  <wst:RequestSecurityTokenResponse>
   <wst:TokenType>
   http://example.org/mysecuritytoken
   </wst:TokenType>
   <wst:RequestedSecurityToken>
    <p:MySecurityToken xmlns:p='http://example.org/mytoken' >
    <!-- Token data -->
    </p:MySecurityToken>
   </wst:RequestedSecurityToken>
   <wst:RequestedProofToken>
    <xenc:EncryptedKey xmlns:xenc='http://www.w3.org/2001/04/xmlenc#' >
     <xenc:EncryptionMethod 
 Algorithm='http://www.w3.org/2001/04/xmlenc#kw-rsa-oaep-mgf1p' />
     <ds:KeyInfo>
      <wss:SecurityTokenReference>
       <wss:Reference URI='#You' ValueType='http://docs.oasis-
open.org/wss/2004/01/oasis-200401-wss-x509-token-profile-1.0#X509v3' />
      </wss:SecurityTokenReference>
     </ds:KeyInfo>
     <xenc:CipherData>
      <xenc:CipherValue>COP01sQlp8kcbs0LSrD1xA==</xenc:CipherValue>
     </xenc:CipherData>
    </xenc:EncryptedKey>
   </wst:RequestedProofToken>
  </wst:RequestSecurityTokenResponse>
 </s:Body>
</s:Envelope>

Figure 2. Response containing a security token

Proof Tokens and Entropy

In the example above the issuer of the security token generates the secret key information contained in the proof token itself without any input from the requestor. WS-Trust allows the requestor to provide input to the key material via a wst:Entropy element in the request. The requestor might do this to satisfy itself as to the degree of entropy (cryptographic randomness if you will) of at least some of the material used to generate the actual key. The requester has no knowledge of how cryptographically random the key material generated at the token issuer will be. This element typically contains an xenc:EncryptedKey element containing key information encrypted for the recipient of the request. The token issuer can then use the entropy provided by the requestor when generating the secret key value for the proof token. Figure 3 shows an example request containing a wst:Entropy element.

<s:Envelope xmlns:s='http://www.w3.org/2003/05/soap-envelope' 
 xmlns:wss='http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-
wssecurity-secext-1.0.xsd' 
 xmlns:wsu='http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-
wssecurity-utility-1.0.xsd'
 xmlns:wst='https://schemas.xmlsoap.org/ws/2004/04/trust'
 xmlns:wsa='https://schemas.xmlsoap.org/ws/2004/03/addressing'
 xmlns:ds='http://www.w3.org/2000/09/xmldsig#' >
 <s:Header>
  <wsa:Action>
  https://schemas.xmlsoap.org/ws/2004/04/security/trust/RST/Issue
  </wsa:Action>
  <wsa:To>http://example.org/mywebservice</wsa:To>
  <wsa:ReplyTo>
   <wsa:Address>
   https://schemas.xmlsoap.org/ws/2004/03/addressing/role/anonymous
   </wsa:Address>
  </wsa:ReplyTo>
  <wsa:MessageID>
  uuid:3e9c26fb-f297-490f-a8c8-c6cef961bfc6
  </wsa:MessageID>
  <wss:Security>
   <wss:BinarySecurityToken wsu:Id='Me' 
    ValueType='http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-
x509-token-profile-1.0#X509v3'
    EncodingType='http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-
soap-message-security-1.0#Base64Binary' >
   dX5CZ8lqZl1X2v1s/uqwDddPOqnauJGTmKoEjQGn...
   </wss:BinarySecurityToken>
   <ds:Signature>
    <!-- Signature over the request -->
   </ds:Signature>
  </wss:Security>
 </s:Header>
 <s:Body>
  <wst:RequestSecurityToken>
   <wst:TokenType>
   http://example.org/mysecuritytoken
   </wst:TokenType>
   <wst:RequestType>
   https://schemas.xmlsoap.org/ws/2004/04/security/trust/Issue
   </wst:RequestType>
   <wst:Base>
    <wss:SecurityTokenReference>
     <wss:Reference URI='#Me' ValueType='http://docs.oasis-
open.org/wss/2004/01/oasis-200401-wss-x509-token-profile-1.0#X509v3' />
    </wss:SecurityTokenReference>
   </wst:Base>
   <wst:Entropy>
    <xenc:EncryptedKey xmlns:xenc="http://www.w3.org/2001/04/xmlenc#">
     <xenc:EncryptionMethod 
 Algorithm="http://www.w3.org/2001/04/xmlenc#rsa-oaep-mgf1p" />
     <ds:KeyInfo>
      <wss:SecurityTokenReference>
       <wss:KeyIdentifier ValueType="http://docs.oasis-
open.org/wss/2004/01/oasis-200401-wss-x509-token-profile-
1.0#X509SubjectKeyIdentifier">
       bBwPfItvKp3b6TNDq+14qs58VJQ=
       </wss:KeyIdentifier>
      </wss:SecurityTokenReference>
     </ds:KeyInfo>
     <xenc:CipherData>
      <xenc:CipherValue>
      j8lrcUKF+JQISxyMyXn06lcaH2YKbn/bFYKT...
      </xenc:CipherValue>
     </xenc:CipherData>
    </xenc:EncryptedKey>
   </wst:Entropy>
  </wst:RequestSecurityToken>
 </s:Body>
</s:Envelope>

Figure 3. Request containing client provided entropy

Requesting a Token for a Specific Service

The example requests above contain no information concerning the Web service with whom the requestor actually wants to communicate securely. It is assumed that the security token service has prior knowledge of which Web service the requester needs a token for. It may be that the security token service and the actual Web service are co-located. Or that the security token service only issues tokens for communicating with a particular Web service.

There are cases where a single security token service will broker trust for multiple Web services. In these cases, the request needs to contain some information about the Web service the requester needs a token for. One way of providing this information is to provide the endpoint reference of the specific Web service in the request. Figure 4 shows such a request. The endpoint reference is communicated in the wsp:AppliesTo element. Note that in this case, the wst:TokenType element is omitted. The assumption here is that the security token service will know what token type a given endpoint expects and will issue tokens appropriately. Figure 5 shows the corresponding response, which also contains a wsp:AppliesTo element.

<s:Envelope xmlns:s='http://www.w3.org/2003/05/soap-envelope' 
 xmlns:wss='http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-
wssecurity-secext-1.0.xsd' 
 xmlns:wsu='http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-
wssecurity-utility-1.0.xsd'
 xmlns:wst='https://schemas.xmlsoap.org/ws/2004/04/trust'             
 xmlns:wsa='https://schemas.xmlsoap.org/ws/2004/03/addressing'
 xmlns:wsp='https://schemas.xmlsoap.org/ws/2002/12/policy' >
 <s:Header>y
  <wsa:Action>
  https://schemas.xmlsoap.org/ws/2004/04/security/trust/RST/Issue
  </wsa:Action>
  <wsa:To>http://example.org/sts</wsa:To>
  <wsa:ReplyTo>
   <wsa:Address>
   https://schemas.xmlsoap.org/ws/2004/03/addressing/role/anonymous
   </wsa:Address>
  </wsa:ReplyTo>
  <wsa:MessageID>
  uuid:91813257-3dfd-40c3-a253-ba961d0664a9
  </wsa:MessageID>
  <wss:Security>
   <wss:BinarySecurityToken wsu:Id='Me' 
    ValueType='http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-
x509-token-profile-1.0#X509v3'
    EncodingType='http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-
soap-message-security-1.0#Base64Binary' >
   dX5CZ8lqZl1X2v1s/uqwDddPOqnauJGTmKoEjQGn...
   </wss:BinarySecurityToken>
   <ds:Signature xmlns:ds='http://www.w3.org/2000/09/xmldsig#' >
    <!-- Signature over the request -->
   </ds:Signature>
  </wss:Security>
 </s:Header>
 <s:Body>
  <wst:RequestSecurityToken>
   <wst:RequestType>
   https://schemas.xmlsoap.org/ws/2004/04/security/trust/Issue
   </wst:RequestType>
   <wst:Base>
    <wss:SecurityTokenReference>
     <wss:Reference URI='#Me' ValueType='http://docs.oasis-
open.org/wss/2004/01/oasis-200401-wss-x509-token-profile-1.0#X509v3' />
    </wss:SecurityTokenReference>
   </wst:Base>
   <wsp:AppliesTo>
    <wsa:EndpointReference>
     <wsa:Address>http://example.org/webservice</wsa:Address>
    </wsa:EndpointReference>
   </wsp:AppliesTo>
  </wst:RequestSecurityToken>
 </s:Body>
</s:Envelope>

Figure 4. Request for a security token for a specific endpoint reference

<s:Envelope xmlns:s='http://www.w3.org/2003/05/soap-envelope' 
 xmlns:wss='http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-
wssecurity-secext-1.0.xsd' 
 xmlns:wsu='http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-
wssecurity-utility-1.0.xsd'
 xmlns:wst='https://schemas.xmlsoap.org/ws/2004/04/trust'   
 xmlns:wsa='https://schemas.xmlsoap.org/ws/2004/03/addressing'
 xmlns:wsp='https://schemas.xmlsoap.org/ws/2002/12/policy' 
 xmlns:ds='http://www.w3.org/2000/09/xmldsig#' >
 <s:Header>
  <wsa:Action>
  https://schemas.xmlsoap.org/ws/2004/04/security/trust/RSTR/Issue
  </wsa:Action>
  <wsa:To>
  https://schemas.xmlsoap.org/ws/2004/03/addressing/role/anonymous
  </wsa:To>
  <wsa:MessageID>
  uuid:74b2a468-e6fc-42d2-9a60-6ff715ad2c33
  </wsa:MessageID>
  <wsa:RelatesTo>
  uuid:91813257-3dfd-40c3-a253-ba961d0664a9
  </wsa:RelatesTo>
  <wss:Security>
   <wss:BinarySecurityToken wsu:Id='You' 
    ValueType='http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-
x509-token-profile-1.0#X509v3'
    EncodingType='http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-
soap-message-security-1.0#Base64Binary' >
   dX5CZ8lqZl1X2v1s/uqwDddPOqnauJGTmKoEjQGn...
   </wss:BinarySecurityToken>
   <ds:Signature>
    <!-- Signature over the response -->
   </ds:Signature>
  </wss:Security>
 </s:Header>
 <s:Body>
  <wst:RequestSecurityTokenResponse>
   <wst:TokenType>
   http://example.org/mysecuritytoken
   </wst:TokenType>
   <wsp:AppliesTo>
    <wsa:EndpointReference>
     <wsa:Address>http://example.org/webservice</wsa:Address>
    </wsa:EndpointReference>
   </wsp:AppliesTo>
   <wst:RequestedSecurityToken>
    <p:MySecurityToken xmlns:p='http://example.org/mytoken' >
    <!-- Token data -->
    </p:MySecurityToken>
   </wst:RequestedSecurityToken>
   <wst:RequestedProofToken>
    <xenc:EncryptedKey xmlns:xenc='http://www.w3.org/2001/04/xmlenc#' >
     <xenc:EncryptionMethod 
 Algorithm='http://www.w3.org/2001/04/xmlenc#kw-rsa-oaep-mgf1p' />
     <ds:KeyInfo>
      <wss:SecurityTokenReference>
       <wss:Reference URI='#You' ValueType='http://docs.oasis-
open.org/wss/2004/01/oasis-200401-wss-x509-token-profile-1.0#X509v3' />
      </wss:SecurityTokenReference>
     </ds:KeyInfo>
     <xenc:CipherData>
      <xenc:CipherValue>5wVATYvs9JS6Y/gl0Ch8Zw==</xenc:CipherValue>
     </xenc:CipherData>
    </xenc:EncryptedKey>
   </wst:RequestedProofToken>
  </wst:RequestSecurityTokenResponse>
 </s:Body>
</s:Envelope>

Figure 5. Response containing a security token for a specific endpoint reference

Other Token Characteristics

WS-Trust allows various characteristics of the requested token to be specified in the request. For example, a validity period or lifetime for a token can be specified as can information concerning key length, key types and token issuer information amongst other things. The security token service typically indicates in the response the characteristics of the returned token. Figure 6 shows a request for a token with a specific lifetime, while Figure 7 shows an example response containing lifetime information.

<s:Envelope xmlns:s='http://www.w3.org/2003/05/soap-envelope' 
 xmlns:wss='http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-
wssecurity-secext-1.0.xsd' 
 xmlns:wsu='http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-
wssecurity-utility-1.0.xsd'
 xmlns:wst='https://schemas.xmlsoap.org/ws/2004/04/trust'             
 xmlns:wsa='https://schemas.xmlsoap.org/ws/2004/03/addressing'
 xmlns:wsp='https://schemas.xmlsoap.org/ws/2002/12/policy' >
 <s:Header>
  <wsa:Action>
  https://schemas.xmlsoap.org/ws/2004/04/security/trust/RST/Issue
  </wsa:Action>
  <wsa:To>http://example.org/sts</wsa:To>
  <wsa:ReplyTo>
   <wsa:Address>
   https://schemas.xmlsoap.org/ws/2004/03/addressing/role/anonymous
   </wsa:Address>
  </wsa:ReplyTo>
  <wsa:MessageID>
  uuid:1079685e-6830-4081-b108-345add21e4eb
  </wsa:MessageID>
  <wss:Security>
   <wss:BinarySecurityToken wsu:Id='Me' 
    ValueType='http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-
x509-token-profile-1.0#X509v3'
    EncodingType='http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-
soap-message-security-1.0#Base64Binary' >
   dX5CZ8lqZl1X2v1s/uqwDddPOqnauJGTmKoEjQGn...
   </wss:BinarySecurityToken>
   <ds:Signature xmlns:ds='http://www.w3.org/2000/09/xmldsig#' >
    <!-- Signature over the request -->
   </ds:Signature>
  </wss:Security>
 </s:Header>
 <s:Body>
  <wst:RequestSecurityToken>
   <wst:RequestType>
   https://schemas.xmlsoap.org/ws/2004/04/security/trust/Issue
   </wst:RequestType>
   <wst:Base>
    <wss:SecurityTokenReference>
     <wss:Reference URI='#Me' ValueType='http://docs.oasis-
open.org/wss/2004/01/oasis-200401-wss-x509-token-profile-1.0#X509v3' />
    </wss:SecurityTokenReference>
   </wst:Base>
   <wsp:AppliesTo>
    <wsa:EndpointReference>
     <wsa:Address>http://example.org/webservice</wsa:Address>
    </wsa:EndpointReference>   
   </wsp:AppliesTo>
   <wst:Lifetime>
    <wsu:Created>2004-05-06T22:04:34</wsu:Created>
    <wsu:Expires>2004-05-07T10:04:34</wsu:Expires>
   </wst:Lifetime>
  </wst:RequestSecurityToken>
 </s:Body>
</s:Envelope>

Figure 6. Request for a security token with a specific lifetime

<s:Envelope xmlns:s='http://www.w3.org/2003/05/soap-envelope' 
 xmlns:wss='http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-
wssecurity-secext-1.0.xsd' 
 xmlns:wsu='http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-
wssecurity-utility-1.0.xsd'
 xmlns:wst='https://schemas.xmlsoap.org/ws/2004/04/trust'   
 xmlns:wsa='https://schemas.xmlsoap.org/ws/2004/03/addressing' 
 xmlns:ds='http://www.w3.org/2000/09/xmldsig#' >
 <s:Header>
  <wsa:Action>
  https://schemas.xmlsoap.org/ws/2004/04/security/trust/RSTR/Issue
  </wsa:Action>
  <wsa:To>
  https://schemas.xmlsoap.org/ws/2004/03/addressing/role/anonymous
  </wsa:To>
  <wsa:MessageID>
  uuid:7c0ac5e6-2ca5-4cf6-ad9b-96b720442079
  </wsa:MessageID>
  <wsa:RelatesTo>
  uuid:1079685e-6830-4081-b108-345add21e4eb
  </wsa:RelatesTo>
  <wss:Security>
   <wss:BinarySecurityToken wsu:Id='You' 
    ValueType='http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-
x509-token-profile-1.0#X509v3'
    EncodingType='http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-
soap-message-security-1.0#Base64Binary' >
   dX5CZ8lqZl1X2v1s/uqwDddPOqnauJGTmKoEjQGn...
   </wss:BinarySecurityToken>
   <ds:Signature>
    <!-- Signature over the response -->
   </ds:Signature>
  </wss:Security>
 </s:Header>
 <s:Body>
  <wst:RequestSecurityTokenResponse>
   <wst:TokenType>
   http://example.org/mysecuritytoken
   </wst:TokenType>
   <wsp:AppliesTo>
    <wsa:EndpointReference>
     <wsa:Address>http://example.org/webservice</wsa:Address>
    </wsa:EndpointReference>   
   </wsp:AppliesTo>
   <wst:Lifetime>
    <wsu:Created>2004-05-06T22:04:34</wsu:Created>
    <wsu:Expires>2004-05-07T10:04:34</wsu:Expires>
   </wst:Lifetime>
   <wst:RequestedSecurityToken>
    <p:MySecurityToken xmlns:p='http://example.org/mytoken' >
    <!-- Token data -->
    </p:MySecurityToken>
   </wst:RequestedSecurityToken>
   <wst:RequestedProofToken>
    <xenc:EncryptedKey xmlns:xenc='http://www.w3.org/2001/04/xmlenc#' >
     <xenc:EncryptionMethod 
 Algorithm='http://www.w3.org/2001/04/xmlenc#kw-rsa-oaep-mgf1p' />
     <ds:KeyInfo>
      <wss:SecurityTokenReference>
       <wss:Reference URI='#You' ValueType='http://docs.oasis-
open.org/wss/2004/01/oasis-200401-wss-x509-token-profile-1.0#X509v3' />
      </wss:SecurityTokenReference>
     </ds:KeyInfo>
     <xenc:CipherData xmlns:xenc='http://www.w3.org/2001/04/xmlenc#' >
      <xenc:CipherValue>1yLLyrm3qudM1b89dYsRGw==</xenc:CipherValue>
     </xenc:CipherData>
    </xenc:EncryptedKey>
   </wst:RequestedProofToken>
  </wst:RequestSecurityTokenResponse>
 </s:Body>
</s:Envelope>

Figure 7. Response containing a security token with lifetime information

Security Token Service and WSE 2.0

The Web Services Enhancements Toolkit Version 2.0 implements the latest version of the WS-Trust specification. It provides a SecurityTokenService class as the base class for processing issuance, renewal and validation requests for security tokens. For a custom security token one derives a class from SecurityContextService to handle such requests. The CustomXmlSecurityToken sample that ships with WSE 2.0 contains an example of such a class.

WS-SecureConversation

WS-Security provides mechanisms for securing a single message in a one-way message exchange. Often interactions between a Web service and a consumer will result in multiple messages being exchanged. While each message could be secured in isolation, it is more efficient to establish some form of context that the Web service and consumer share and use that context to reduce the burden with respect to securing each message exchanged. WS-SecureConversation defines a Security Context Token to perform this task.

What Are Security Context Tokens?

A Security Context Token is a type of security token that represents a security context that is shared by the two communicating parties; the Web service and the consumer of that Web service. The security context is identified by a URI and typically contains keys that are used as the basis of providing integrity and/or confidentiality protection for messages transmitted between the two parties. A security context may well contain no identity information. A security context provides a way to provide session based security, rather than establishing new keys for every message. Figure 8 shows an example Security Context Token. The identifier is contained in the wsc:Identifier element and the context also includes creation and expiration time information. The consumer and the Web service refer to the Security Context Token by its identifier when they secure messages they exchange. They will only use this Security Context Token (and the key material associated with it ) until it expires. If they wish to continue exchanging messages they will establish a new Security Context Token.

<wsc:SecurityContextToken 
 xmlns:wsu='http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-
wssecurity-utility-1.0.xsd'
 xmlns:wsc='https://schemas.xmlsoap.org/ws/2004/04/sc' 
 wsu:Id='MySCT'>
 <wsc:Identifier></wsc:Identifier>
 <wsu:Created>2004-05-07T21:24:06</wsu:Created>
 <wsu:Expires>2004-05-08T09:24:06</wsu:Expires>
</wsc:SecurityContextToken>

Figure 8. A Security Context Token

Issuing Security Context Tokens

WS-SecureConversation defines a binding for WS-Trust, wsa:Action and wst:RequestType URIs, specifically for issuing Security Context Tokens. Figure 9 shows an example request while Figure 10 shows an example response. Note that just like the custom XML token case, a proof token is returned, a secret which is also part of the shared security context.

<s:Envelope xmlns:s='http://www.w3.org/2003/05/soap-envelope' 
 xmlns:wss='http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-
wssecurity-secext-1.0.xsd' 
 xmlns:wsu='http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-
wssecurity-utility-1.0.xsd'
 xmlns:wst='https://schemas.xmlsoap.org/ws/2004/04/trust'
 xmlns:wsa='https://schemas.xmlsoap.org/ws/2004/03/addressing'
 xmlns:wsp='https://schemas.xmlsoap.org/ws/2002/12/policy' >
 <s:Header>
  <wsa:Action>
  https://schemas.xmlsoap.org/ws/2004/04/security/trust/RST/SCT
  </wsa:Action>
  <wsa:To>http://example.org/sts</wsa:To>
  <wsa:ReplyTo>
   <wsa:Address>
   https://schemas.xmlsoap.org/ws/2004/03/addressing/role/anonymous
   </wsa:Address>
  </wsa:ReplyTo>
  <wsa:MessageID>
  uuid:23c919ef-fcab-42c6-8023-5ded0e6da932
  </wsa:MessageID>
  <wss:Security>
   <wss:BinarySecurityToken wsu:Id='Me' 
    ValueType='http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-
x509-token-profile-1.0#X509v3'
    EncodingType='http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-
soap-message-security-1.0#Base64Binary' >
   dX5CZ8lqZl1X2v1s/uqwDddPOqnauJGTmKoEjQGn...
   </wss:BinarySecurityToken>
   <ds:Signature xmlns:ds='http://www.w3.org/2000/09/xmldsig#' >
    <!-- Signature over the request -->
   </ds:Signature>
  </wss:Security>
 </s:Header>
 <s:Body>
  <wst:RequestSecurityToken>
   <wst:RequestType>
   https://schemas.xmlsoap.org/ws/2004/04/security/trust/Issue
   </wst:RequestType>
   <wst:Base>
    <wss:SecurityTokenReference>
     <wss:Reference URI='#Me' ValueType='http://docs.oasis-
open.org/wss/2004/01/oasis-200401-wss-x509-token-profile-1.0#X509v3' />
    </wss:SecurityTokenReference>
   </wst:Base>
   <wsp:AppliesTo>
    <wsa:EndpointReference>
     <wsa:Address>http://example.org/webservice</wsa:Address>
    </wsa:EndpointReference>   
   </wsp:AppliesTo>
   <wst:Lifetime>
    <wsu:Created>2004-05-06T22:04:34</wsu:Created>
    <wsu:Expires>2004-05-07T10:04:34</wsu:Expires>
   </wst:Lifetime>
  </wst:RequestSecurityToken>
 </s:Body>
</s:Envelope>

Figure 9. Request for a security context token

<s:Envelope xmlns:s='http://www.w3.org/2003/05/soap-envelope' 
 xmlns:wss='http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-
wssecurity-secext-1.0.xsd' 
 xmlns:wsu='http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-
wssecurity-utility-1.0.xsd'
 xmlns:wst='https://schemas.xmlsoap.org/ws/2004/04/trust'
 xmlns:wsc='http://schemsa.xmlsoap.org/ws/2004/04/sc'
 xmlns:wsa='https://schemas.xmlsoap.org/ws/2004/03/addressing' 
 xmlns:ds='http://www.w3.org/2000/09/xmldsig#' >
 <s:Header>
  <wsa:Action>
  https://schemas.xmlsoap.org/ws/2004/04/security/trust/RSTR/SCT
  </wsa:Action>
  <wsa:To>
  https://schemas.xmlsoap.org/ws/2004/03/addressing/role/anonymous
  </wsa:To>
  <wsa:MessageID>
  uuid:515742a6-ec89-4915-845a-87a30046e89f
  </wsa:MessageID>
  <wsa:RelatesTo>
  uuid:23c919ef-fcab-42c6-8023-5ded0e6da932
  </wsa:RelatesTo>
  <wss:Security>
   <wss:BinarySecurityToken wsu:Id='You' 
    ValueType='http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-
x509-token-profile-1.0#X509v3'
    EncodingType='http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-
soap-message-security-1.0#Base64Binary' >
   dX5CZ8lqZl1X2v1s/uqwDddPOqnauJGTmKoEjQGn...
   </wss:BinarySecurityToken>
   <ds:Signature>
    <!-- Signature over the response -->
   </ds:Signature>
  </wss:Security>
 </s:Header>
 <s:Body>
  <wst:RequestSecurityTokenResponse>
   <wst:TokenType>
   https://schemas.xmlsoap.org/ws/2004/04/security/sc/sct
   </wst:TokenType>
   <wsp:AppliesTo>
    <wsa:EndpointReference>
     <wsa:Address>http://example.org/webservice</wsa:Address>
    </wsa:EndpointReference>   
   </wsp:AppliesTo>
   <wst:Lifetime>
    <wsu:Created>2004-05-06T22:04:34</wsu:Created>
    <wsu:Expires>2004-05-07T10:04:34</wsu:Expires>
   </wst:Lifetime>
   <wst:RequestedSecurityToken>
    <wsc:SecurityContextToken>
     <wsc:Identifier></wsc:Identifier>
     <wsu:Created>2004-05-07T21:24:06</wsu:Created>
     <wsu:Expires>2004-05-08T09:24:06</wsu:Expires>
    </wsc:SecurityContextToken>
   </wst:RequestedSecurityToken>
   <wst:RequestedProofToken>
    <xenc:EncryptedKey xmlns:xenc='http://www.w3.org/2001/04/xmlenc#' >
     <xenc:EncryptionMethod 
 Algorithm='http://www.w3.org/2001/04/xmlenc#kw-rsa-oaep-mgf1p' />
     <ds:KeyInfo>
      <wss:SecurityTokenReference>
       <wss:Reference URI='#You' ValueType='http://docs.oasis-
open.org/wss/2004/01/oasis-200401-wss-x509-token-profile-1.0#X509v3' />
      </wss:SecurityTokenReference>
     </ds:KeyInfo>
     <xenc:CipherData xmlns:xenc='http://www.w3.org/2001/04/xmlenc#' >
      <xenc:CipherValue>YhSUhHleqdCkMvRiNI6zjw==</xenc:CipherValue>
     </xenc:CipherData>
    </xenc:EncryptedKey>
   </wst:RequestedProofToken>
  </wst:RequestSecurityTokenResponse>
 </s:Body>
</s:Envelope>

Figure 10. Response containing a security context token

Security Context Tokens and WSE 2.0

The Web Services Enhancements Toolkit Version 2.0 implements the latest version of the WS-SecureConversation specification. It provides a SecurityContextTokenService class for issuing Security Context Tokens. A given virtual directory can be configured to automatically issue Security Context Tokens by adding an autoIssueSecurityContextToken element to web.config as shown in Figure 11. This configures the virtual directory to respond to Request Security Token requests.

<configuration>
 <configSections>
  <section name='microsoft.web.services2' 
  type='Microsoft.Web.Services2.Configuration.WebServicesConfiguration, 
Microsoft.Web.Services2, Version=2.0.0.0, Culture=neutral, 
PublicKeyToken=31bf3856ad364e35' />
 </configSections>

 <microsoft.web.services2>
  . . .
  <tokenIssuer>
   <autoIssueSecurityContextToken enabled='true' />
   . . .
  </tokenIssuer>
 </microsoft.web.services2>
</configuration>

Figure 11. web.config showing autoIssueSecurityContextToken element

WSE 2.0 also provides a SecurityContextTokenServiceClient class for requesting a Security Context Token from a service. Figure 12 shows some sample code; the clientToken is used as the basis of the request while the serverToken is used to encrypt the entropy the requestor provides such that only the server can see that information.

public SecurityContextToken GetSCT ( SecurityToken clientToken,
                                     SecurityToken serverToken,
                                     EndpointReference epr )
{
 SecurityContextTokenServiceClient proxy = new 
 SecurityContextTokenServiceClient ( epr );
 return proxy.IssueSecurityContextTokenAuthenticated ( clientToken,
                                                       serverToken );
}

Figure 12. Using the SecurityContextTokenServiceClient class

Derived Keys

It is considered bad practice to sign and encrypt data using the same key as certain attacks are more likely to succeed in this case. Likewise signing or encrypting multiple messages with the same key is also considered bad practice as it gives an attacker more information to work with. So, establishing a security context establishes a secret, but using that secret directly to secure multiple messages is undesirable. The WS-SecureConversation specification defines another token type, Derived Key Token, to deal with this issue. Keys are derived from the original secret and the derived key is used to secure the message. For example, one could derive a pair of keys for each message to be sent, one key for signing and one for encrypting. The specification provides many different mechanisms for deriving keys, but also defines a specific algorithm, identified with the URI https://schemas.xmlsoap.org/ws/2004/04/security/sc/dk/p_sha1. This algorithm takes a secret, a label and a nonce and generates key material by computing a digest from those inputs. Figure 13 shows an example Derived Key Token which refers to the Security Context Token shown in Figure 8 and contains label and nonce values along with a key length Figure 14 shows an example message secured using two derived key tokens, one for signing and one for encrypting.

<wsc:DerivedKeyToken 
 xmlns:wss='http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-
wssecurity-secext-1.0.xsd'
 xmlns:wsu='http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-
wssecurity-utility-1.0.xsd'
 xmlns:wsc='https://schemas.xmlsoap.org/ws/2004/04/sc' 
Algorithm='https://schemas.xmlsoap.org/ws/2004/04/security/sc/dk/p_sha1'
 >
 <wss:SecurityTokenReference>
  <wss:Reference URI='#MySCT' 
 ValueType='https://schemas.xmlsoap.org/ws/2004/04/security/sc/sct' />
 </wss:SecurityTokenReference>
 <wsc:Length>16</wsc:Length>
 <wsc:Label>MyLabelText</wsc:Label>
 <wsc:Nonce>CXrD7xEjbLQzN6au+RRfTQ==</wsc:Nonce>
</wsc:DerivedKeyToken>

Figure 13. A Derived Key Token

<s:Envelope xmlns:s='http://www.w3.org/2003/05/soap-envelope' 
 xmlns:wss='http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-
wssecurity-secext-1.0.xsd' 
 xmlns:wsu='http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-
wssecurity-utility-1.0.xsd'
 xmlns:wst='https://schemas.xmlsoap.org/ws/2004/04/trust'
 xmlns:wsc='http://schemsa.xmlsoap.org/ws/2004/04/sc'
 xmlns:wsa='https://schemas.xmlsoap.org/ws/2004/03/addressing'
 xmlns:ds='http://www.w3.org/2000/09/xmldsig#' 
 xmlns:xenc='http://www.w3.org/2001/04/xmlenc#' >
 <s:Header>
  <wsa:Action>
  http://example.org/someaction
  </wsa:Action>
  <wsa:To>
  http://example.org/myservice
  </wsa:To>
  <wsa:MessageID>
  uuid:515742a6-ec89-4915-845a-87a30046e89f
  </wsa:MessageID>
  <wss:Security>
   <wsc:SecurityContextToken wsu:Id='MySCT'>
    <wsc:Identifier>
    uuid:f5293037-9b6b-4b12-b6a0-e50acebcfe10
    </wsc:Identifier>
    <wsu:Created>2004-05-07T21:24:06</wsu:Created>
    <wsu:Expires>2004-05-08T09:24:06</wsu:Expires>
   </wsc:SecurityContextToken>
   <wsc:DerivedKeyToken wsu:Id='DKS'
Algorithm='https://schemas.xmlsoap.org/ws/2004/04/security/sc/dk/p_sha1'
>
    <wss:SecurityTokenReference>
     <wss:Reference URI='#MySCT' 
 ValueType='https://schemas.xmlsoap.org/ws/2004/04/security/sc/sct' />
    </wss:SecurityTokenReference>
    <wsc:Length>16</wsc:Length>
    <wsc:Label>MySigningToken</wsc:Label>
    <wsc:Nonce>zJ5S/QxANfr281MMYuicHA==</wsc:Nonce>
   </wsc:DerivedKeyToken>
   <ds:Signature>
    <!-- Signature over the response -->
    <ds:KeyInfo>
     <wss:SecurityTokenReference>
      <wss:Reference URI='#DKS' 
 ValueType='https://schemas.xmlsoap.org/ws/2004/04/security/sc/dk' />
     </wss:SecurityTokenReference>
    </ds:KeyInfo>
   </ds:Signature>
   <wsc:DerivedKeyToken wsu:Id='DKE'
Algorithm='https://schemas.xmlsoap.org/ws/2004/04/security/sc/dk/p_sha1'
>
    <wss:SecurityTokenReference>
     <wss:Reference URI='#MySCT' 
 ValueType='https://schemas.xmlsoap.org/ws/2004/04/security/sc/sct' />
    </wss:SecurityTokenReference>
    <wsc:Length>16</wsc:Length>
    <wsc:Label>MySigningToken</wsc:Label>
    <wsc:Nonce>3i3H6t+0AUSF+fOjNaK7Hg==</wsc:Nonce>
   </wsc:DerivedKeyToken>
   <xenc:ReferenceList>
    <xenc:DataReference URI='#Body' />
   </xenc:ReferenceList>
  </wss:Security>
 </s:Header>
 <s:Body wsu:Id='Body' >
  <xenc:EncryptedData >
   <xenc:EncryptionMethod 
 Algorithm='http://www.w3.org/2001/04/xmlenc#aes128-cbc' >
   <ds:KeyInfo>
    <wss:SecurityTokenReference>
     <wss:Reference URI='#DKE' 
 ValueType='https://schemas.xmlsoap.org/ws/2004/04/security/sc/dk' />
    </wss:SecurityTokenReference>
   </ds:KeyInfo>
   <xenc:CipherData>
    <xenc:CipherValue>
    dtSVth1Vswa2AHocj80DdZaRmkNPlhwLMdPT+6aByE/4...
    </xenc:CipherValue>
   </xenc:CipherData>
  </xenc:EncryptedData>
 </s:Body>
</s:Envelope>

Figure 14. Use of DerivedKeyToken in a message

Derived Key Tokens and WSE 2.0

The Web Services Enhancements Toolkit Version 2.0 provides a DerivedKeyToken class for dealing with Derived Key Tokens. The constructor for the DerivedKeyToken class takes another token as input, the token that contains the base secret used in the derivation. Figure 15 shows example code for constructed a DerivedKeyToken and signing a message with the resulting secret.

public void SignMessageWithDK ( SoapEnvelope env,
                                SecurityContextToken sct )
{
  DerivedKeyToken dk = new DerivedKeyToken ( sct );
  env.Context.Security.Tokens.Add ( sct );
  env.Context.Security.Tokens.Add ( dk );
  env.Context.Security.Elements.Add ( new MessageSignature ( dk ));
}

Figure 15. Use of DerivedKeyToken and signing a message with the resulting secret

Summary

WS-Trust provides a framework for managing security tokens of various types while WS-SecureConversation defines a couple of token types and provides mechanisms for establishing a secure session between communicating parties. The Web Services Enhancements Toolkit Version 2.0 provides implementations of both specifications to enable Web Service producers and consumers to secure their applications.

Share via