WS-Trust: Interoperable Security for Web Services

June 24, 2003

Paul Madsen


Karl Marx was probably not referring to web services security when he wrote "From each, according to his ability; to each, according to his need." If he had been, he would have been advocating an architecture in which all entities in a web services transaction would be able to make their own choices for the security characteristics they would expect of incoming SOAP messages (the "to each according to his need" part), as well as for the security mechanisms they would apply to outgoing SOAP messages (the "from each according to his ability" part). It sounds like an interoperability nightmare. If every company were to define their own policies for what a "secure" SOAP message was, in isolation from the practices and capabilities of the partners/customers they wished to do business with, the chances of any two parties being able to find an intersection between requirements and capabilities would seem vanishingly small, making interoperable security impossible.

Nevertheless, the emerging WS-Security standard for securing web services at the message layer (currently progressing towards standardization within OASIS), if applied in isolation, leads to just this sort of interoperability barrier. A SOAP client could apply arbitrary security operations (e.g. signing and encryption) to their messages in a manner fully conformant with the WS-Security specifications and the recipient SOAP Service could still be unable to validate, extract, and or process the message if its security infrastructure was not compatible with that of the client.

WS-Security will standardize how security information is added to SOAP messages. One important class of such security information is one which WS-Security calls Security Tokens -- a security token is "a collection of claims" about the sender (the sender typically proving their right to this claim through a digital signature). A fundamental issue that WS-Security neither address nor attempted to address is how two entities (a SOAP client and SOAP Service) can agree on the nature and characteristics of the security tokens that are the underpinning of WS-Security. WS-Security begins with the assumption that, if one of the parties uses a particular type of security token within the WS-Security header, then the other party will be able to interpret and process this token.

However, there are multiple viable formats for security tokens (e.g. X.509 certificates, Kerberos tickets, SAML Assertions, XACML policies, etc.), and it is unlikely that an arbitrary SOAP endpoint will be expected to understand each of these options. Consequently, there is no guarantee that there will be an intersection between the sets of supported security token formats of two different SOAP actors who wish to use WS-Security to secure their SOAP messages. This is of course not a limitation of WS-Security; it simply reflects the heterogeneity of the security environments between which WS-Security must operate.

Therefore, interoperable application of WS-Security across security domains with different security infrastructures will require either mechanisms by which actors can come to an agreement on the nature of security token they will use in any subsequent SOAP transactions, or mechanisms by which different security tokens can be mapped into others, such that individual SOAP actors can be guaranteed to receive only security tokens that they will be able to understand and process. Fortunately, the larger framework for securing web services, of which WS-Security is a part, defines additional components that will support both scenarios for addressing this interoperability issue. I mean WS-SecurityPolicy and WS-Trust respectively.

  • WS-SecurityPolicy (released for industry review in December 2002, but not yet submitted to a standards body) specifies how web services actors can assert to potential transaction partners their policies with respect to WS-Security mechanisms, including their capabilitities and preferences with respect to security tokens (e.g. a SOAP service can assert "I can process X.509 certificates and SAML assertions but my first choice is SAML').

  • WS-Trust is a proposal (released at the same time as WS-SecurityPolicy) that enables security token interoperability by defining a request/response protocol by which SOAP actors can request of some trusted authority that a particular security token be exchanged for another.

The remainder of this article provides an overview of the WS-Trust proposal and presents an example scenario to demonstrate the interplay between WS-Trust and WS-Security.

Note: Bilal Siddiqui provides a thorough overview of WS-Security in Web Services Security, Part 2 -- please refer to that article for the details of how WS-Security enables message level security through XML Signatures and XML Encryption.

WS-Trust Overview

As its name suggests, WS-Trust is motivated by more than enabling interoperability between the multiple formats for security tokens that might be used in a WS-Security protected message. It also addresses the issue of trust interoperability. Even if a given security token's format is acceptable to a recipient of a WS-Security-protected SOAP message, interoperability at the syntax level is no guarantee that the recipient will be able to trust the token. For example, for a SOAP Service to support Kerberos tokens does not mean that it would be able to accept Kerberos tickets from arbitrary Kerberos Key Distribution Centers -- the service would not have the necessary trust (in the form of shared symmetric keys) with these KDCs in order to decrypt and verify such tickets.

In principle, the recipient of a WS-Security-protected SOAP message will have three potential issues with the security token contained within the Security header:

  1. format -- the recipient may find the format or syntax of the token incomprehensible. For instance, the incoming security token may be a Kerberos ticket and the recipient does not have the necessary Kerberos functionality in order to parse and interpret this binary token. Other recipients might find an X.509 certificate equally cryptic.

  2. trust -- the recipient may be unable to build a chain-of-trust from its own trust anchors (e.g. its X.509 Certificate Authority, a local Kerberos KDC, or a SAML Authority) to the issuer or signer of the token.

  3. namespace -- the recipient may be unable to directly comprehend the set of claims within the token because of syntactical differences. For instance, a SAML Attribute assertion might assert that the sender has the role of "Purchasing Officer" whilst the recipient's authorization policies are expressed in terms of "ProcurementAdmin." While these roles may "mean" the same thing (i.e. "the subject is authorized to place orders up to $5,000 in a 24 hour period"), the difference in syntax would prevent appropriate processing.

WS-Trust addresses all three of these potential interoperability issues by defining a simple request/response for security token exchange. A client sends a RequestSecurityToken to a Security Token Service, the request includes the security token that the client is asking to be exchanged. The Security Token Service (STS) responds back with a RequestSecurityTokenResponse that contains the new token. The three interoperability issues identified above can be addressed through this exchange as follows:

  1. format -- the returned token is in a format understandable by the recipient

  2. trust -- the returned token will be signed by the STS; it is expected that the recipient and the STS will have an established trust relationship such that the recipient will be able to verify and trust the new token.

  3. namespace -- the STS will ensure that the returned token will use syntax appropriate to the expectations of the recipient.

In addition to token exchange, the WS-Trust request/response protocol is general enough to support token issuance (the client presents a claim to the STS for the STS to authorize through the issuance of a corresponding security token) and token validation (the client presents a token to the STS and asks that its validity be determined.) Issuance and validation can be thought of as special cases of exchange, as both the client claim in the issuance case and the STS validity assertion response in the validation case can be thought of as tokens. The different applications of WS-Trust are shown below:

Figure 2. WS-Trust applications.

The token exchange, issuance, and validation applications have analogies in existing security technologies. In X.509 a subject presents their claimed identity along with supporting evidence to a Registration Authority which, after verification, requests of a Certificate Authority that a certificate be issued. Likewise, in Kerberos, a client authenticates to the Key Distribution Center in order to be granted a Ticket Granting Ticket (an issuance) that the client will subsequently use to request a new ticket targeted for a particular service (an exchange).

For the X.509 world, there already exists a proposal for XML-based token issuance and token validation, namely, the X-KRSS and X-KISS components of the XML Key Management Specification (XKMS) currently being standardized under the W3C. It remains to be seen how WS-Trust and XKMS will compete, cooperate, or coexist in this area.

WS-Trust Scenario

In this section we'll explore how WS-Security and WS-Trust may be used together to afford both message-layer security and interoperability across security infrastructures for a SOAP-based Web Service. We will see that the web service itself will be afforded the required authentication of clients and integrity and confidentiality of messages, while being insulated from much of the details and complexity of the underlying infrastructure, with the result being transparent (to the service) security.

The basic architecture is shown in the figure below. A SOAP client sends a SOAP message to a business application SOAP service (for the sake of this example a purchasing application), which, after appropriate business processing, sends the SOAP response back. Supporting this fundamental exchange are the components of the security infrastructure, a SOAP gateway and a security token service (STS), which work together to ensure that the SOAP service receives only messages with "appropriate" security tokens.

Figure 3. WS-Trust scenario components

The SOAP gateway and STS will use WS-Trust messages to enable interoperable processing of the more fundamental WS-Security protected SOAP message sent between the client and the service.

For this scenario, we make the following assumptions:

  1. The client understands X.509 certificates only. It uses an XML Signature (keyed by the private key associated with an X.509 certificate issued to it by some known Certificate Authority) to protect the integrity of its outgoing messages and to allow their provenance to be determined.

  2. The service understands SAML only. It will accept only SAML Authentication Assertions as Security Tokens within the SOAP messages it receives.

  3. The service does not directly trust the client.

  4. The client is not required to anticipate the preference that the service has for SAML Assertions.

Message flow

I discuss here only the incoming SOAP request sent by the client. The message flow could be run in reverse to ensure that the associated SOAP response would be processable and trusted by the client on its receipt.

Message 1 -- WS-Security message with X.509 certificate

The SOAP client sends the initial WS-Security protected request to the SOAP service. The request is shown below:

(In this and subsequent XML listings, some details (e.g. full namespace declarations) are omitted for the sake of clarity.)

1  <soap:Envelope>

2  <soap:Header>

3  <ws:Security>

4  	 <ws:BinarySecurityToken id="X509token" ValueType="X.509">

5	sdfOIDFKLSoidefsdflk …

6  	</ws:BinarySecurityToken>

7	 <ds:Signature>

8            <ds:Reference>

9             <ds:Ref URI="#PO"/>

10           </ds:Reference>

11           <ds:SignatureValue>akjsdflaksf</ds:SignatureValue>

12	     <ds:KeyInfo>

13             <ws:BinarySecurityTokenReference URI="#X509token"/>

14           </ds:KeyInfo>

15	</ds:Signature>

16  </ws:Security>

17  </soap:Header>

18  <soap:Body>

19  	<po:PurchaseOrder ID="PO"/>

20  </soap:Body>

21  </soap:Envelope>

The identity of the client (and the integrity of the message) is asserted through an XML Signature [Lines 7-15], keyed by a private key associated with the X.509 certificate contained within the BinarySecurityToken element [Lines 4-6]. The X.509 certificate is an assertion as to the binding between the identity of the client and a public key -- it is through the XML Signature that the SOAP client demonstrates that they have the associated private key and does indeed own the identity asserted within the certificate.

The SOAP client sent the SOAP request to the address specified in the service's WSDL document -- this address is the SOAP gateway. Alternatively the WSDL could specify the service itself and the gateway would intercept these requests. Either way, the gateway acts as the first line of defense for the services it fronts. Consequently, it is the gateway that is first presented with the incoming WS-Security protected SOAP message, and it is therefore the gateway that must make the first decision regarding its security processing (SOAP gateways typically offer capabilities beyond security, e.g. schema validation.)

It may be the case that the gateway is aware of the service's "preference" for SAML and would therefore be able to identify the incompatibility were it to forward on the SOAP message as-is (i.e. with its embedded X.509 certificate) to the targeted service. Alternatively and less efficiently, it could route all incoming SOAP requests to an appropriate STS authority for "token processing". Either way, before the incoming SOAP request is passed onto the service, the X.509 certificate must be mapped into an appropriate SAML Assertion through the gateway requesting this operation of the STS using a WS-Trust Token Exchange Request.

Message 2 - WS-Trust Token Exchange Request

If the gateway were to remove the X.509 certificate (and associated XML Signature) from the SOAP message before delivering it onto the service, then the service would indeed be protected from the X.509 syntax. Beyond the obvious security implications of sending the message over this last leg in an unsecured manner, it is the certificate that contained the identity of the client, and it is most likely that this identity is relevant both to further security processing (i.e. is the request authorized) and to subsequent business processing (i.e. who gets charged). Consequently, the identity of the SOAP client must somehow persist to the SOAP service to enable this processing. There is therefore a need for a conversion of the X.509 security token to a format comprehensible to the SOAP service, (which, given our initial assumptions, is a SAML Authentication assertion).

For a mapping between X.509 and SAML to occur, it is apparent that some system entity must be able to comprehend both formats (and understand their correspondence). In this scenario it is the STS that is responsible for comprehending multiple security token formats. WS-Trust provides a protocol by which the SOAP gateway can request such a token conversion from the STS.

The following XML illustrates the request from the gateway to the Token Service for the creation of a SAML Assertion based on the X.509 certificate sent in the original SOAP message.

1  <soap:Envelope>

2  <soap:Header>

3   <ws:Security>


5   </ws:Security>

6  </soap:Header>

7  <soap:Body>

8  	<wstrust:RequestSecurityToken>

9	   <wstrust:TokenType>SAML</TokenType>

10	   <wstrust:RequestType>ReqExchange</RequestType>

11	   <wstrust:OnBehalfOf>

12             <ws:BinarySecurityToken id="originaltoken"


13  	        sdfOIDFKLSoidefsdflk …

14	       </ws:BinarySecurityToken> 

15         </wstrust:OnBehalfOf>

16  	</wstrust:RequestSecurityToken>

17  </soap:Body>

18  </soap:Envelope>

The SOAP Body contains the RequestSecurityToken element [Lines 8-16]. The type of token that is being requested is identified as SAML [Line 9]; the token for which it is being exchanged is listed within the OnBehalfOf element [Lines 11-15]. The OnBehalfOf element also notifies the STS that this request is being made by the gateway on behalf of some other entity, namely the client whose identity is asserted to in the contained token.

The signature calculated by the client over the original SOAP message is not included in the RequestSecurityToken; the assumption is that the gateway would have verified this signature before sending the RequestSecurityToken. It could be the case that the STS's policy required that this Signature be sent as well for audit purposes or for the STS itself to perform the signature validation if the gateway were unable to build the required chain of certificates.

Not shown are the mechanisms by which the gateway would authenticate to the STS and by which the integrity of the request would be ensured. These mechanisms could be applied at the transport layer (with the previously identified limitations) or at the message layer. If the latter, the above message would have additional security tokens and signatures in the ws:Security element [Lines 3-5].

If there were no gateway in the picture, this WS-Trust request could also have been composed and sent by the service to the STS. The implication however is that the service would necessarily have more security "smarts", even if only the ability to recognize security tokens that it was incapable of dealing with.

Message 3 -- WS-Trust Security Token Exchange Response

After receiving the RequestSecurityToken message, and verifying that it was indeed sent by the gateway, the STS will extract the submitted security token from the request and, after processing, create an appropriate token in response. In this scenario, this token will be a SAML Authentication Assertion in the name of the client, targeted to the service and signed by the STS. The following listing shows the RequestSecurityTokenResponse message that the STS returns to the gateway.

1  <soap:Envelope>

2  <soap:Header>

3   <ws:Security>


7   </ws:Security>

8  </soap:Header>

9  <soap:Body>

10  	<wstrust:RequestSecurityTokenResponse>

11	   <wstrust:TokenType>SAML</TokenType>

12	     <wstrust:RequestedSecurityToken>

13              <saml:Assertion

14              	AssertionID="2se8e/vaskfsdif="

15              	Issuer=""

16              	IssueInstant="2002-06-19T16:58:33.173Z">

17                <saml:Conditions

18              	NotBefore="2002-06-19T16:53:33.173Z"

19              	NotOnOrAfter="2002-06-19T17:08:33.173Z"/>

20                <saml:AuthenticationStatement

21              	AuthenticationMethod="urn:oasis:names:tc:SAML:1.0:am:X.509"

22              	AuthenticationInstant="2002-06-19T16:57:30.000Z">

23                  <saml:Subject>

24              	<saml:NameIdentifier 


25              	<saml:SubjectConfirmation>

26              	  <saml:ConfirmationMethod>

27              	  urn:oasis:names:tc:SAML:1.0:cm:sender-vouches

28              	  </saml:ConfirmationMethod>

29              	</saml:SubjectConfirmation>

30                  </saml:Subject>

31               </saml:AuthenticationStatement>

32              <ds:Signature> 

       <-- calculated by STS --> </ds:Signature>

33              </saml:Assertion>

34         </wstrust:RequestedSecurityToken>

35  	</wstrust:RequestSecurityTokenResponse>

36  </soap:Body>

37  </soap:Envelope>

The STS returns to the gateway the SAML assertion in the RequestedSecurityToken element [Lines 13-34] -- the SAML assertion signed by the STS and recorded in the Signature element [Line 32]. It is the application of this signature that allows the STS to broker the trust between the client and the Sender; it was through the trust that the STS was able to place in the original X.509 certificate that it issued a corresponding SAML assertion.

This dynamic brokering of trust is more comparable to the way in which Kerberos enables cross-domain trust than to the X.509 world. Kerberos accomplishes cross-domain trust through its authorities playing an active "run-time" role in the trust brokering. If a client in one Kerberos realm wants to access a service belonging to another realm, it must first ask its own KDC for a ticket for the KDC of the other realm and then use this ticket to request of this remote KDC a ticket for the desired service. Although the SOAP client in our scenario is oblivious to the brokering being performed on its behalf by the actively involved STS (which plays the role of an authority for the service), the similarities between Kerberos and the WS-Trust model are clear. Indeed, many aspects of the WS-Trust proposal have direct analogies in Kerberos, e.g. forwardable and proxyable tokens.

Note that the NameIdentifier element [Line 24] carries an identifier for the client in a namespace that is presumably meaningful to the service, this identified by the NameQualifier attribute. Although the original identifier was contained within the binary X.509 certificate and was not consequently visible in Message 1, the assumption is that by default it would not be directly meaningful to the service. The ConfirmationMethod element [Lines 26-28] lists sender-vouches, meaning that the ultimate sender of this assertion (the gateway) will be acting on behalf of the subject within the assertion.

It could well be the case that the STS could return to the gateway additional SAML assertions targeted for the service. For instance, if the STS played the role of an Authorization Policy Decision Point, it could create a SAML AuthorizationDecisionStatement defining the client's privileges with respect to the service.

Message 4 -- WS-Security message with SAML Token

The gateway receives the RequestSecurityTokenResponse message from the STS. It is the gateway's responsibility to extract the SAML assertion from the message and use it to recreate a version of the original SOAP message that the service will be able to understand. The following listing shows the WS-Security/SAML protected message that the gateway forwards on to the service.

1  <soap:Envelope>

2  <soap:Header>

3  <ws:Security>

4        <saml:Assertion

5              	AssertionID="2se8e/vaskfsdif="

6              	Issuer=""

7              	IssueInstant="2002-06-19T16:58:33.173Z">

8                <saml:Conditions

9              	NotBefore="2002-06-19T16:53:33.173Z"

10              	NotOnOrAfter="2002-06-19T17:08:33.173Z"/>

11                <saml:AuthenticationStatement

12              	AuthenticationMethod="urn:oasis:names:tc:SAML:1.0:am:X.509"

13              	AuthenticationInstant="2002-06-19T16:57:30.000Z">

14                  <saml:Subject>

15              	<saml:NameIdentifier>


16              	<saml:SubjectConfirmation>

17              	  <saml:ConfirmationMethod>

18              	  urn:oasis:names:tc:SAML:1.0:cm:sender-vouches

19              	  </saml:ConfirmationMethod>

20              	</saml:SubjectConfirmation>

21                  </saml:Subject>

22               </saml:AuthenticationStatement>

23              <ds:Signature> 

            <-- calculated by STS --> </ds:Signature>

24      </saml:Assertion>

25  </ws:Security>

26  </soap:Header>

27  <soap:Body>

28  	<po:PurchaseOrder ID="PO"/>

29  </soap:Body>

30  </soap:Envelope>

The gateway has inserted the SAML Assertion it received from the STS in the SOAP header [Lines 4-24]. As the ConfirmationMethod [Lines 17-19] lists sender-vouches, the service will likely require additional mechanisms in order to place confidence in the SAML Assertion beyond the fact that it has been signed by the STS. It will require that the gateway authenticate so that the sender of the SAML assertion can be verified in addition to its creator.


This article has demonstrated how WS-Trust can enable interoperable WS-Security based message-layer security. The client and service in our scenario were insulated from the fact that they share neither a common security token format nor direct trust through the intervention of the gateway and STS in message processing on their behalf.

The benefit of this model is more transparent security to the client and service. The burden of understanding security token formats and managing trust relationships with external entities is removed from their shoulders (actually those of their developers and administrators) and placed on the STS (a service dedicated to this role).

This model of dedicated security services accessed through SOAP-based interfaces is also relevant for other security processing (e.g. digital signature creation, data encryption, authorization decisions etc.) With the burden of such functionality removed, the business applications can concentrate even more on the business logic and leave security to the infrastructure. Additionally, because security processing is performed in a centralized manner, the model offers advantages for ensuring these security protections are applied in a consistent and policy-respecting manner.


Marx's ideas have been difficult to implement in a social context. Perhaps it will be in web services security that it will find application -- from each SOAP client, according to its security processing abilities, to each SOAP service, according to its security policy.


  • Read the WS-Trust proposal at IBM's site.

  • Read the working draft of the WS-Security SOAP Message Security specification at the OASIS Web Services Security document page.

  • Read the working draft of the WS-Security X.509 Certificate Token Profile specification at the OASIS Web Services Security document page.

  • Read the working draft of the WS-Security SAML Token Profile specification at the OASIS Web Services Security document page.