1

2 WS-Trust 1.4
3OASIS Standard
42 February 2009
5Specification URIs:
6This Version:
7 http://docs.oasis-open.org/ws-sx/ws-trust/v1.4/os/ws-trust-1.4-spec-os.doc (Authoritative)
8 http://docs.oasis-open.org/ws-sx/ws-trust/v1.4/os/ws-trust-1.4-spec-os.pdf
9 http://docs.oasis-open.org/ws-sx/ws-trust/v1.4/os/ws-trust-1.4-spec-os.html
10Previous Version:
11 http://docs.oasis-open.org/ws-sx/ws-trust/v1.4/cd/ws-trust-1.4-spec-cs-01.doc (Authoritative)
12 http://docs.oasis-open.org/ws-sx/ws-trust/v1.4/cd/ws-trust-1.4-spec-cs-01.pdf
13 http://docs.oasis-open.org/ws-sx/ws-trust/v1.4/cd/ws-trust-1.4-spec-cs-01.html
14Latest Version:
15 http://docs.oasis-open.org/ws-sx/ws-trust/v1.4/ws-trust.doc
16 http://docs.oasis-open.org/ws-sx/ws-trust/v1.4/ws-trust.pdf
17 http://docs.oasis-open.org/ws-sx/ws-trust/v1.4/ws-trust.html
18
19Technical Committee:
20 OASIS Web Services Secure Exchange TC
21Chair(s):
22 Kelvin Lawrence, IBM
23 Chris Kaler, Microsoft
24Editor(s):
25 Anthony Nadalin, IBM
26 Marc Goodner, Microsoft
27 Martin Gudgin, Microsoft
28 Abbie Barbir, Nortel
29 Hans Granqvist, VeriSign
30Related work:
31 N/A
32Declared XML namespace(s):
33 http://docs.oasis-open.org/ws-sx/ws-trust/200512
34 http://docs.oasis-open.org/ws-sx/ws-trust/200802
35Abstract:
36 This specification defines extensions that build on [WS-Security] to provide a framework for
37 requesting and issuing security tokens, and to broker trust relationships.
38Status:
39 This document was last revised or approved by the WS-SX TC on the above date. The level of
40 approval is also listed above. Check the current location noted above for possible later revisions
41 of this document. This document is updated periodically on no particular schedule.
42 Technical Committee members should send comments on this specification to the Technical
43 Committee’s email list. Others should send comments to the Technical Committee by using the

1ws-trust-1.4-os 2 February 2009

2Copyright © OASIS® 1993–2009. All Rights Reserved. Page 1 of 88
44 “Send A Comment” button on the Technical Committee’s web page at http://www.oasis-
45 open.org/committees/ws-sx.
46 For information on whether any patents have been disclosed that may be essential to
47 implementing this specification, and any offers of patent licensing terms, please refer to the
48 Intellectual Property Rights section of the Technical Committee web page (http://www.oasis-
49 open.org/committees/ws-sx/ipr.php).
50 The non-normative errata page for this specification is located at http://www.oasis-
51 open.org/committees/ws-sx.

4ws-trust-1.4-os 2 February 2009

5Copyright © OASIS® 1993–2009. All Rights Reserved. Page 2 of 88
52Notices

53Copyright © OASIS® 1993–2009. All Rights Reserved.

54All capitalized terms in the following text have the meanings assigned to them in the OASIS Intellectual
55Property Rights Policy (the "OASIS IPR Policy"). The full Policy may be found at the OASIS website.
56This document and translations of it may be copied and furnished to others, and derivative works that
57comment on or otherwise explain it or assist in its implementation may be prepared, copied, published,
58and distributed, in whole or in part, without restriction of any kind, provided that the above copyright notice
59and this section are included on all such copies and derivative works. However, this document itself may
60not be modified in any way, including by removing the copyright notice or references to OASIS, except as
61needed for the purpose of developing any document or deliverable produced by an OASIS Technical
62Committee (in which case the rules applicable to copyrights, as set forth in the OASIS IPR Policy, must
63be followed) or as required to translate it into languages other than English.
64The limited permissions granted above are perpetual and will not be revoked by OASIS or its successors
65or assigns.
66This document and the information contained herein is provided on an "AS IS" basis and OASIS
67DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY
68WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY
69OWNERSHIP RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A
70PARTICULAR PURPOSE.
71OASIS requests that any OASIS Party or any other party that believes it has patent claims that would
72necessarily be infringed by implementations of this OASIS Committee Specification or OASIS Standard,
73to notify OASIS TC Administrator and provide an indication of its willingness to grant patent licenses to
74such patent claims in a manner consistent with the IPR Mode of the OASIS Technical Committee that
75produced this specification.
76OASIS invites any party to contact the OASIS TC Administrator if it is aware of a claim of ownership of
77any patent claims that would necessarily be infringed by implementations of this specification by a patent
78holder that is not willing to provide a license to such patent claims in a manner consistent with the IPR
79Mode of the OASIS Technical Committee that produced this specification. OASIS may include such
80claims on its website, but disclaims any obligation to do so.
81OASIS takes no position regarding the validity or scope of any intellectual property or other rights that
82might be claimed to pertain to the implementation or use of the technology described in this document or
83the extent to which any license under such rights might or might not be available; neither does it represent
84that it has made any effort to identify any such rights. Information on OASIS' procedures with respect to
85rights in any document or deliverable produced by an OASIS Technical Committee can be found on the
86OASIS website. Copies of claims of rights made available for publication and any assurances of licenses
87to be made available, or the result of an attempt made to obtain a general license or permission for the
88use of such proprietary rights by implementers or users of this OASIS Committee Specification or OASIS
89Standard, can be obtained from the OASIS TC Administrator. OASIS makes no representation that any
90information or list of intellectual property rights will at any time be complete, or that any claims in such list
91are, in fact, Essential Claims.
92The name "OASIS" is a trademark of OASIS, the owner and developer of this specification, and should be
93used only to refer to the organization and its official outputs. OASIS welcomes reference to, and
94implementation and use of, specifications, while reserving the right to enforce its marks against
95misleading uses. Please see http://www.oasis-open.org/who/trademark.php for above guidance.
96

7ws-trust-1.4-os 2 February 2009

8Copyright © OASIS® 1993–2009. All Rights Reserved. Page 3 of 88
97Table of Contents
981 Introduction......................................................................................................................................... 6
99 1.1 Goals and Non-Goals........................................................................................................................ 6
100 1.2 Requirements.................................................................................................................................... 7
101 1.3 Namespace....................................................................................................................................... 7
102 1.4 Schema and WSDL Files.................................................................................................................. 8
103 1.5 Terminology....................................................................................................................................... 8
104 1.5.1 Notational Conventions.............................................................................................................. 9
105 1.6 Normative References..................................................................................................................... 10
106 1.7 Non-Normative References............................................................................................................. 11
1072 Web Services Trust Model................................................................................................................ 12
108 2.1 Models for Trust Brokering and Assessment...................................................................................13
109 2.2 Token Acquisition............................................................................................................................ 13
110 2.3 Out-of-Band Token Acquisition........................................................................................................ 14
111 2.4 Trust Bootstrap................................................................................................................................ 14
1123 Security Token Service Framework.................................................................................................. 15
113 3.1 Requesting a Security Token.......................................................................................................... 15
114 3.2 Returning a Security Token............................................................................................................. 16
115 3.3 Binary Secrets................................................................................................................................. 18
116 3.4 Composition.................................................................................................................................... 18
1174 Issuance Binding............................................................................................................................... 19
118 4.1 Requesting a Security Token.......................................................................................................... 19
119 4.2 Request Security Token Collection.................................................................................................21
120 4.2.1 Processing Rules................................................................................................................. 23
121 4.3 Returning a Security Token Collection............................................................................................ 23
122 4.4 Returning a Security Token............................................................................................................. 24
123 4.4.1 wsp:AppliesTo in RST and RSTR............................................................................................ 25
124 4.4.2 Requested References............................................................................................................ 26
125 4.4.3 Keys and Entropy..................................................................................................................... 26
126 4.4.4 Returning Computed Keys....................................................................................................... 27
127 4.4.5 Sample Response with Encrypted Secret................................................................................28
128 4.4.6 Sample Response with Unencrypted Secret............................................................................28
129 4.4.7 Sample Response with Token Reference................................................................................29
130 4.4.8 Sample Response without Proof-of-Possession Token...........................................................29
131 4.4.9 Zero or One Proof-of-Possession Token Case........................................................................29
132 4.4.10 More Than One Proof-of-Possession Tokens Case...............................................................30
133 4.5 Returning Security Tokens in Headers............................................................................................ 31
1345 Renewal Binding............................................................................................................................... 33
1356 Cancel Binding.................................................................................................................................. 36
136 6.1 STS-initiated Cancel Binding........................................................................................................... 37
1377 Validation Binding............................................................................................................................. 39
1388 Negotiation and Challenge Extensions............................................................................................. 42
139 8.1 Negotiation and Challenge Framework........................................................................................... 43

10ws-trust-1.4-os 2 February 2009

11Copyright © OASIS® 1993–2009. All Rights Reserved. Page 4 of 88
140 8.2 Signature Challenges...................................................................................................................... 43
141 8.3 User Interaction Challenge.............................................................................................................. 44
142 8.3.1 Challenge Format..................................................................................................................... 45
143 8.3.2 PIN and OTP Challenges......................................................................................................... 48
144 8.4 Binary Exchanges and Negotiations................................................................................................49
145 8.5 Key Exchange Tokens..................................................................................................................... 49
146 8.6 Custom Exchanges......................................................................................................................... 50
147 8.7 Signature Challenge Example......................................................................................................... 50
148 8.8 Challenge Examples........................................................................................................................ 52
149 8.8.1 Text and choice challenge........................................................................................................ 52
150 8.8.2 PIN challenge........................................................................................................................... 54
151 8.8.3 PIN challenge with optimized response...................................................................................56
152 8.9 Custom Exchange Example............................................................................................................ 57
153 8.10 Protecting Exchanges.................................................................................................................... 58
154 8.11 Authenticating Exchanges............................................................................................................. 58
1559 Key and Token Parameter Extensions..............................................................................................60
156 9.1 On-Behalf-Of Parameters................................................................................................................ 60
157 9.2 Key and Encryption Requirements.................................................................................................. 60
158 9.3 Delegation and Forwarding Requirements......................................................................................65
159 9.4 Policies............................................................................................................................................ 66
160 9.5 Authorized Token Participants......................................................................................................... 67
16110 Key Exchange Token Binding........................................................................................................... 68
16211 Error Handling................................................................................................................................... 70
16312 Security Considerations.................................................................................................................... 71
16413 Conformance..................................................................................................................................... 73
165A. Key Exchange................................................................................................................................... 74
166 A.1 Ephemeral Encryption Keys............................................................................................................ 74
167 A.2 Requestor-Provided Keys............................................................................................................... 74
168 A.3 Issuer-Provided Keys...................................................................................................................... 75
169 A.4 Composite Keys.............................................................................................................................. 75
170 A.5 Key Transfer and Distribution.......................................................................................................... 76
171 A.5.1 Direct Key Transfer.................................................................................................................. 76
172 A.5.2 Brokered Key Distribution........................................................................................................ 76
173 A.5.3 Delegated Key Transfer........................................................................................................... 77
174 A.5.4 Authenticated Request/Reply Key Transfer.............................................................................78
175 A.6 Perfect Forward Secrecy................................................................................................................. 79
176B. WSDL................................................................................................................................................ 80
177C. Acknowledgements........................................................................................................................... 82
178
179

13ws-trust-1.4-os 2 February 2009

14Copyright © OASIS® 1993–2009. All Rights Reserved. Page 5 of 88
1801 Introduction
181[WS-Security] defines the basic mechanisms for providing secure messaging. This specification uses
182these base mechanisms and defines additional primitives and extensions for security token exchange to
183enable the issuance and dissemination of credentials within different trust domains.
184
185In order to secure a communication between two parties, the two parties must exchange security
186credentials (either directly or indirectly). However, each party needs to determine if they can "trust" the
187asserted credentials of the other party.
188
189In this specification we define extensions to [WS-Security] that provide:
190 Methods for issuing, renewing, and validating security tokens.
191 Ways to establish assess the presence of, and broker trust relationships.
192
193Using these extensions, applications can engage in secure communication designed to work with the
194general Web services framework, including WSDL service descriptions, UDDI businessServices and
195bindingTemplates, and [SOAP] [SOAP2] messages.
196
197To achieve this, this specification introduces a number of elements that are used to request security
198tokens and broker trust relationships.
199
200Section 12 is non-normative.

2011.1 Goals and Non-Goals

202The goal of WS-Trust is to enable applications to construct trusted [SOAP] message exchanges. This
203trust is represented through the exchange and brokering of security tokens. This specification provides a
204protocol agnostic way to issue, renew, and validate these security tokens.
205
206This specification is intended to provide a flexible set of mechanisms that can be used to support a range
207of security protocols; this specification intentionally does not describe explicit fixed security protocols.
208
209As with every security protocol, significant efforts must be applied to ensure that specific profiles and
210message exchanges constructed using WS-Trust are not vulnerable to attacks (or at least that the attacks
211are understood).
212
213The following are explicit non-goals for this document:
214 Password authentication
215 Token revocation
216 Management of trust policies
217
218Additionally, the following topics are outside the scope of this document:
16ws-trust-1.4-os 2 February 2009
17Copyright © OASIS® 1993–2009. All Rights Reserved. Page 6 of 88
219 Establishing a security context token
220 Key derivation

2211.2 Requirements
222The Web services trust specification must support a wide variety of security models. The following list
223identifies the key driving requirements for this specification:
224 Requesting and obtaining security tokens
225 Establishing, managing and assessing trust relationships

2261.3 Namespace
227Implementations of this specification MUST use the following [URI]s:
228 http://docs.oasis-open.org/ws-sx/ws-trust/200512
229 http://docs.oasis-open.org/ws-sx/ws-trust/200802

230When using a URI to indicate that this version of Trust is being used http://docs.oasis-open.org/ws-sx/ws-
231trust/200802 MUST be used.
232Table 1 lists XML namespaces that are used in this specification. The choice of any namespace prefix is
233arbitrary and not semantically significant.
234Table 1: Prefixes and XML Namespaces used in this specification.

Prefix Namespace Specification(s)

S11 http://schemas.xmlsoap.org/soap/envelope/ [SOAP]

S12 http://www.w3.org/2003/05/soap-envelope [SOAP12]

wsu http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss- [WS-Security]

wssecurity-utility-1.0.xsd

wsse http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss- [WS-Security]

wssecurity-secext-1.0.xsd

wsse11 http://docs.oasis-open.org/wss/oasis-wss-wsecurity- [WS-Security]

secext-1.1.xsd

wst http://docs.oasis-open.org/ws-sx/ws-trust/200512 This specification

wst14 http://docs.oasis-open.org/ws-sx/ws-trust/200802 This specification

ds http://www.w3.org/2000/09/xmldsig# [XML-Signature]

xenc http://www.w3.org/2001/04/xmlenc# [XML-Encrypt]

wsp http://schemas.xmlsoap.org/ws/2004/09/policy or [WS-Policy]

19ws-trust-1.4-os 2 February 2009

20Copyright © OASIS® 1993–2009. All Rights Reserved. Page 7 of 88
 http://www.w3.org/ns/ws-policy

wsa http://www.w3.org/2005/08/addressing [WS-Addressing]

xs http://www.w3.org/2001/XMLSchema [XML-Schema1]
[XML-Schema2]

2351.4 Schema and WSDL Files

236The schema [XML-Schema1], [XML-Schema2] for this specification can be located at:
237 http://docs.oasis-open.org/ws-sx/ws-trust/200512/ws-trust.xsd
238 http://docs.oasis-open.org/ws-sx/ws-trust/v1.4/ws-trust.xsd

239
240The WSDL for this specification can be located in Appendix II of this document as well as at:
241 http://docs.oasis-open.org/ws-sx/ws-trust/v1.4/ws-trust.wsdl

242In this document, reference is made to the wsu:Id attribute, wsu:Created and wsu:Expires
243elements in the utility schema. These were added to the utility schema with the intent that other
244specifications requiring such an ID or timestamp could reference it (as is done here).

2451.5 Terminology
246Claim – A claim is a statement made about a client, service or other resource (e.g. name, identity, key,
247group, privilege, capability, etc.).
248Security Token – A security token represents a collection of claims.
249Signed Security Token – A signed security token is a security token that is cryptographically endorsed
250by a specific authority (e.g. an X.509 certificate or a Kerberos ticket).
251Proof-of-Possession Token – A proof-of-possession (POP) token is a security token that contains
252secret data that can be used to demonstrate authorized use of an associated security token. Typically,
253although not exclusively, the proof-of-possession information is encrypted with a key known only to the
254recipient of the POP token.
255Digest – A digest is a cryptographic checksum of an octet stream.
256Signature – A signature is a value computed with a cryptographic algorithm and bound to data in such a
257way that intended recipients of the data can use the signature to verify that the data has not been altered
258and/or has originated from the signer of the message, providing message integrity and authentication.
259The signature can be computed and verified with symmetric key algorithms, where the same key is used
260for signing and verifying, or with asymmetric key algorithms, where different keys are used for signing and
261verifying (a private and public key pair are used).
262Trust Engine – The trust engine of a Web service is a conceptual component that evaluates the security-
263related aspects of a message as described in section 2 below.
264Security Token Service – A security token service (STS) is a Web service that issues security tokens
265(see [WS-Security]). That is, it makes assertions based on evidence that it trusts, to whoever trusts it (or
266to specific recipients). To communicate trust, a service requires proof, such as a signature to prove
267knowledge of a security token or set of security tokens. A service itself can generate tokens or it can rely
268on a separate STS to issue a security token with its own trust statement (note that for some security token
269formats this can just be a re-issuance or co-signature). This forms the basis of trust brokering.
22ws-trust-1.4-os 2 February 2009
23Copyright © OASIS® 1993–2009. All Rights Reserved. Page 8 of 88
270Trust – Trust is the characteristic that one entity is willing to rely upon a second entity to execute a set of
271actions and/or to make set of assertions about a set of subjects and/or scopes.
272Direct Trust – Direct trust is when a relying party accepts as true all (or some subset of) the claims in the
273token sent by the requestor.
274Direct Brokered Trust – Direct Brokered Trust is when one party trusts a second party who, in turn,
275trusts or vouches for, a third party.
276Indirect Brokered Trust – Indirect Brokered Trust is a variation on direct brokered trust where the
277second party negotiates with the third party, or additional parties, to assess the trust of the third party.
278Message Freshness – Message freshness is the process of verifying that the message has not been
279replayed and is currently valid.
280We provide basic definitions for the security terminology used in this specification. Note that readers
281should be familiar with the [WS-Security] specification.

2821.5.1 Notational Conventions

283The keywords "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD
284NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described
285in [RFC2119].
286
287Namespace URIs of the general form "some-URI" represents some application-dependent or context-
288dependent URI as defined in [URI ].
289
290This specification uses the following syntax to define outlines for messages:
291  The syntax appears as an XML instance, but values in italics indicate data types instead of literal
292 values.
293  Characters are appended to elements and attributes to indicate cardinality:
294 o "?" (0 or 1)
295 o "*" (0 or more)
296 o "+" (1 or more)
297  The character "|" is used to indicate a choice between alternatives.
298  The characters "(" and ")" are used to indicate that contained items are to be treated as a group
299 with respect to cardinality or choice.
300  The characters "[" and "]" are used to call out references and property names.
301  Ellipses (i.e., "...") indicate points of extensibility. Additional children and/or attributes MAY be
302 added at the indicated extension points but MUST NOT contradict the semantics of the parent
303 and/or owner, respectively. By default, if a receiver does not recognize an extension, the receiver
304 SHOULD ignore the extension; exceptions to this processing rule, if any, are clearly indicated
305 below.
306  XML namespace prefixes (see Table 1) are used to indicate the namespace of the element being
307 defined.
308
309Elements and Attributes defined by this specification are referred to in the text of this document using
310XPath 1.0 expressions. Extensibility points are referred to using an extended version of this syntax:

25ws-trust-1.4-os 2 February 2009

26Copyright © OASIS® 1993–2009. All Rights Reserved. Page 9 of 88
311  An element extensibility point is referred to using {any} in place of the element name. This
312 indicates that any element name can be used, from any namespace other than the namespace of
313 this specification.
314  An attribute extensibility point is referred to using @{any} in place of the attribute name. This
315 indicates that any attribute name can be used, from any namespace other than the namespace of
316 this specification.
317
318In this document reference is made to the wsu:Id attribute and the wsu:Created and wsu:Expires
319elements in a utility schema (http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-
3201.0.xsd). The wsu:Id attribute and the wsu:Created and wsu:Expires elements were added to the
321utility schema with the intent that other specifications requiring such an ID type attribute or timestamp
322element could reference it (as is done here).
323

3241.6 Normative References

325 [RFC2119] S. Bradner, "Key words for use in RFCs to Indicate Requirement Levels",
326 RFC 2119, Harvard University, March 1997.
327 http://www.ietf.org/rfc/rfc2119.txt
328 [RFC2246] IETF Standard, "The TLS Protocol", January 1999.
329 http://www.ietf.org/rfc/rfc2246.txt
330 [SOAP] W3C Note, "SOAP: Simple Object Access Protocol 1.1", 08 May 2000.
331 http://www.w3.org/TR/2000/NOTE-SOAP-20000508/
332 [SOAP12] W3C Recommendation, "SOAP 1.2 Part 1: Messaging Framework", 24
333 June 2003.
334 http://www.w3.org/TR/2003/REC-soap12-part1-20030624/
335 [URI] T. Berners-Lee, R. Fielding, L. Masinter, "Uniform Resource Identifiers
336 (URI): Generic Syntax", RFC 3986, MIT/LCS, Day Software, Adobe
337 Systems, January 2005.
338 http://www.ietf.org/rfc/rfc3986.txt
339 [WS-Addressing] W3C Recommendation, "Web Services Addressing (WS-Addressing)", 9
340 May 2006.
341 http://www.w3.org/TR/2006/REC-ws-addr-core-20060509
342 [WS-Policy] W3C Recommendation, "Web Services Policy 1.5 - Framework", 04
343 September 2007.
344 http://www.w3.org/TR/2007/REC-ws-policy-20070904/
345 W3C Member Submission, "Web Services Policy 1.2 - Framework", 25
346 April 2006.
347 http://www.w3.org/Submission/2006/SUBM-WS-Policy-20060425/
348 [WS-PolicyAttachment] W3C Recommendation, "Web Services Policy 1.5 - Attachment", 04
349 September 2007.
350 http://www.w3.org/TR/2007/REC-ws-policy-attach-20070904/
351 W3C Member Submission, "Web Services Policy 1.2 - Attachment", 25
352 April 2006.
353 http://www.w3.org/Submission/2006/SUBM-WS-PolicyAttachment-
354 20060425/
355 [WS-Security] OASIS Standard, "OASIS Web Services Security: SOAP Message Security
356 1.0 (WS-Security 2004)", March 2004.
357 http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-soap-message-
358 security-1.0.pdf

28ws-trust-1.4-os 2 February 2009

29Copyright © OASIS® 1993–2009. All Rights Reserved. Page 10 of 88
359 OASIS Standard, "OASIS Web Services Security: SOAP Message Security
360 1.1 (WS-Security 2004)", February 2006.
361 http://www.oasis-open.org/committees/download.php/16790/wss-v1.1-
362 spec-os-SOAPMessageSecurity.pdf
363 [XML-C14N] W3C Recommendation, "Canonical XML Version 1.0", 15 March 2001.
364 http://www.w3.org/TR/2001/REC-xml-c14n-20010315
365 W3C Recommendation, "Canonical XML Version 1.1", 2 May 2008.
366 http://www.w3.org/TR/2008/REC-xml-c14n11-20080502/
367 [XML-Encrypt] W3C Recommendation, "XML Encryption Syntax and Processing", 10
368 December 2002.
369 http://www.w3.org/TR/2002/REC-xmlenc-core-20021210/
370 [XML-Schema1] W3C Recommendation, "XML Schema Part 1: Structures Second Edition",
371 28 October 2004.
372 http://www.w3.org/TR/2004/REC-xmlschema-1-20041028/
373 [XML-Schema2] W3C Recommendation, "XML Schema Part 2: Datatypes Second Edition",
374 28 October 2004.
375 http://www.w3.org/TR/2004/REC-xmlschema-2-20041028/
376 [XML-Signature] W3C Recommendation, "XML-Signature Syntax and Processing", 12
377 February 2002.
378 http://www.w3.org/TR/2002/REC-xmldsig-core-20020212/
379 [W3C Recommendation, D. Eastlake et al. XML Signature Syntax and
380 Processing (Second Edition). 10 June 2008.
381 http://www.w3.org/TR/2008/REC-xmldsig-core-20080610/
382

3831.7 Non-Normative References

384 [Kerberos] J. Kohl and C. Neuman, "The Kerberos Network 149 Authentication
385 Service (V5)," RFC 1510, September 1993.
386 http://www.ietf.org/rfc/rfc1510.txt
387 [WS-Federation] "Web Services Federation Language," BEA, IBM, Microsoft, RSA Security,
388 VeriSign, July 2003.
389 [WS-SecurityPolicy] OASIS Standard, “WS-SecurityPolicy 1.3”, February 2009
390 http://docs.oasis-open.org/ws-sx/ws-securitypolicy/v1.3/os/ws-
391 securitypolicy-1.3-spec-os.doc
392 [X509] S. Santesson, et al,"Internet X.509 Public Key Infrastructure Qualified
393 Certificates Profile."
394 http://www.itu.int/rec/recommendation.asp?type=items&lang=e&parent=T-
395 REC-X.509-200003-I
396

31ws-trust-1.4-os 2 February 2009

32Copyright © OASIS® 1993–2009. All Rights Reserved. Page 11 of 88
3972 Web Services Trust Model
398The Web service security model defined in WS-Trust is based on a process in which a Web service can
399require that an incoming message prove a set of claims (e.g., name, key, permission, capability, etc.). If a
400message arrives without having the required proof of claims, the service SHOULD ignore or reject the
401message. A service can indicate its required claims and related information in its policy as described by
402[WS-Policy] and [WS-PolicyAttachment] specifications.
403
404Authentication of requests is based on a combination of OPTIONAL network and transport-provided
405security and information (claims) proven in the message. Requestors can authenticate recipients using
406network and transport-provided security, claims proven in messages, and encryption of the request using
407a key known to the recipient.
408
409One way to demonstrate authorized use of a security token is to include a digital signature using the
410associated secret key (from a proof-of-possession token). This allows a requestor to prove a required set
411of claims by associating security tokens (e.g., PKIX, X.509 certificates) with the messages.
412 If the requestor does not have the necessary token(s) to prove required claims to a service, it can
413 contact appropriate authorities (as indicated in the service's policy) and request the needed tokens
414 with the proper claims. These "authorities", which we refer to as security token services, may in turn
415 require their own set of claims for authenticating and authorizing the request for security tokens.
416 Security token services form the basis of trust by issuing a range of security tokens that can be used
417 to broker trust relationships between different trust domains.
418 This specification also defines a general mechanism for multi-message exchanges during token
419 acquisition. One example use of this is a challenge-response protocol that is also defined in this
420 specification. This is used by a Web service for additional challenges to a requestor to ensure
421 message freshness and verification of authorized use of a security token.
422
423This model is illustrated in the figure below, showing that any requestor may also be a service, and that
424the Security Token Service is a Web service (that is, it MAY express policy and require security tokens).
425

426
427This general security model – claims, policies, and security tokens – subsumes and supports several
428more specific models such as identity-based authorization, access control lists, and capabilities-based
34ws-trust-1.4-os 2 February 2009
35Copyright © OASIS® 1993–2009. All Rights Reserved. Page 12 of 88
429authorization. It allows use of existing technologies such as X.509 public-key certificates, XML-based
430tokens, Kerberos shared-secret tickets, and even password digests. The general model in combination
431with the [WS-Security] and [WS-Policy] primitives is sufficient to construct higher-level key exchange,
432authentication, policy-based access control, auditing, and complex trust relationships.
433
434In the figure above the arrows represent possible communication paths; the requestor MAY obtain a
435token from the security token service, or it MAY have been obtained indirectly. The requestor then
436demonstrates authorized use of the token to the Web service. The Web service either trusts the issuing
437security token service or MAY request a token service to validate the token (or the Web service MAY
438validate the token itself).
439
440In summary, the Web service has a policy applied to it, receives a message from a requestor that possibly
441includes security tokens, and MAY have some protection applied to it using [WS-Security] mechanisms.
442The following key steps are performed by the trust engine of a Web service (note that the order of
443processing is non-normative):
444 1. Verify that the claims in the token are sufficient to comply with the policy and that the message
445 conforms to the policy.
446 2. Verify that the attributes of the claimant are proven by the signatures. In brokered trust models,
447 the signature MAY NOT verify the identity of the claimant – it MAY verify the identity of the
448 intermediary, who MAY simply assert the identity of the claimant. The claims are either proven or
449 not based on policy.
450 3. Verify that the issuers of the security tokens (including all related and issuing security token) are
451 trusted to issue the claims they have made. The trust engine MAY need to externally verify or
452 broker tokens (that is, send tokens to a security token service in order to exchange them for other
453 security tokens that it can use directly in its evaluation).
454
455If these conditions are met, and the requestor is authorized to perform the operation, then the service can
456process the service request.
457In this specification we define how security tokens are requested and obtained from security token
458services and how these services MAY broker trust and trust policies so that services can perform step 3.
459Network and transport protection mechanisms such as IPsec or TLS/SSL [RFC2246] can be used in
460conjunction with this specification to support different security requirements and scenarios. If available,
461requestors should consider using a network or transport security mechanism to authenticate the service
462when requesting, validating, or renewing security tokens, as an added level of security.
463
464The [WS-Federation] specification builds on this specification to define mechanisms for brokering and
465federating trust, identity, and claims. Examples are provided in [WS-Federation] illustrating different trust
466scenarios and usage patterns.

4672.1 Models for Trust Brokering and Assessment

468This section outlines different models for obtaining tokens and brokering trust. These methods depend on
469whether the token issuance is based on explicit requests (token acquisition) or if it is external to a
470message flow (out-of-band and trust management).

37ws-trust-1.4-os 2 February 2009

38Copyright © OASIS® 1993–2009. All Rights Reserved. Page 13 of 88
4712.2 Token Acquisition
472As part of a message flow, a request MAY be made of a security token service to exchange a security
473token (or some proof) of one form for another. The exchange request can be made either by a requestor
474or by another party on the requestor's behalf. If the security token service trusts the provided security
475token (for example, because it trusts the issuing authority of the provided security token), and the request
476can prove possession of that security token, then the exchange is processed by the security token
477service.
478
479The previous paragraph illustrates an example of token acquisition in a direct trust relationship. In the
480case of a delegated request (one in which another party provides the request on behalf of the requestor
481rather than the requestor presenting it themselves), the security token service generating the new token
482MAY NOT need to trust the authority that issued the original token provided by the original requestor
483since it does trust the security token service that is engaging in the exchange for a new security token.
484The basis of the trust is the relationship between the two security token services.

4852.3 Out-of-Band Token Acquisition

486The previous section illustrated acquisition of tokens. That is, a specific request is made and the token is
487obtained. Another model involves out-of-band acquisition of tokens. For example, the token may be sent
488from an authority to a party without the token having been explicitly requested or the token may have
489been obtained as part of a third-party or legacy protocol. In any of these cases the token is not received
490in response to a direct SOAP request.

4912.4 Trust Bootstrap

492An administrator or other trusted authority MAY designate that all tokens of a certain type are trusted (e.g.
493all Kerberos tokens from a specific realm or all X.509 tokens from a specific CA). The security token
494service maintains this as a trust axiom and can communicate this to trust engines to make their own trust
495decisions (or revoke it later), or the security token service MAY provide this function as a service to
496trusting services.
497There are several different mechanisms that can be used to bootstrap trust for a service. These
498mechanisms are non-normative and are NOT REQUIRED in any way. That is, services are free to
499bootstrap trust and establish trust among a domain of services or extend this trust to other domains using
500any mechanism.
501
502Fixed trust roots – The simplest mechanism is where the recipient has a fixed set of trust relationships.
503It will then evaluate all requests to determine if they contain security tokens from one of the trusted roots.
504
505Trust hierarchies – Building on the trust roots mechanism, a service MAY choose to allow hierarchies of
506trust so long as the trust chain eventually leads to one of the known trust roots. In some cases the
507recipient MAY require the sender to provide the full hierarchy. In other cases, the recipient MAY be able
508to dynamically fetch the tokens for the hierarchy from a token store.
509
510Authentication service – Another approach is to use an authentication service. This can essentially be
511thought of as a fixed trust root where the recipient only trusts the authentication service. Consequently,
512the recipient forwards tokens to the authentication service, which replies with an authoritative statement
513(perhaps a separate token or a signed document) attesting to the authentication.

40ws-trust-1.4-os 2 February 2009

41Copyright © OASIS® 1993–2009. All Rights Reserved. Page 14 of 88
5143 Security Token Service Framework
515This section defines the general framework used by security token services for token issuance.
516
517A requestor sends a request, and if the policy permits and the recipient's requirements are met, then the
518requestor receives a security token response. This process uses the <wst:RequestSecurityToken>
519and <wst:RequestSecurityTokenResponse> elements respectively. These elements are passed as
520the payload to specific WSDL ports (described in section 1.4) that are implemented by security token
521services.
522
523This framework does not define specific actions; each binding defines its own actions.
524When requesting and returning security tokens additional parameters can be included in requests, or
525provided in responses to indicate server-determined (or used) values. If a requestor specifies a specific
526value that isn't supported by the recipient, then the recipient MAY fault with a wst:InvalidRequest (or
527a more specific fault code), or they MAY return a token with their chosen parameters that the requestor
528MAY then choose to discard because it doesn't meet their needs.
529
530The requesting and returning of security tokens can be used for a variety of purposes. Bindings define
531how this framework is used for specific usage patterns. Other specifications MAY define specific bindings
532and profiles of this mechanism for additional purposes.
533In general, it is RECOMMENDED that sources of requests be authenticated; however, in some cases an
534anonymous request MAY be appropriate. Requestors MAY make anonymous requests and it is up to the
535recipient's policy to determine if such requests are acceptable. If not a fault SHOULD be generated (but
536is NOT REQUIRED to be returned for denial-of-service reasons).
537
538The [WS-Security] specification defines and illustrates time references in terms of the dateTime type
539defined in XML Schema. It is RECOMMENDED that all time references use this type. It is further
540RECOMMENDED that all references be in UTC time. Requestors and receivers SHOULD NOT rely on
541other applications supporting time resolution finer than milliseconds. Implementations MUST NOT
542generate time instants that specify leap seconds. Also, any required clock synchronization is outside the
543scope of this document.
544
545The following sections describe the basic structure of token request and response elements identifying
546the general mechanisms and most common sub-elements. Specific bindings extend these elements with
547binding-specific sub-elements. That is, sections 3.1 and 3.2 should be viewed as patterns or templates
548on which specific bindings build.

5493.1 Requesting a Security Token

550The <wst:RequestSecurityToken> element (RST) is used to request a security token (for any
551purpose). This element SHOULD be signed by the requestor, using tokens contained/referenced in the
552request that are relevant to the request. If using a signed request, the requestor MUST prove any
553required claims to the satisfaction of the security token service.
554If a parameter is specified in a request that the recipient doesn't understand, the recipient SHOULD fault.

43ws-trust-1.4-os 2 February 2009

44Copyright © OASIS® 1993–2009. All Rights Reserved. Page 15 of 88
555The syntax for this element is as follows:
556 <wst:RequestSecurityToken Context="..." xmlns:wst="...">
557 <wst:TokenType>...</wst:TokenType>
558 <wst:RequestType>...</wst:RequestType>
559 <wst:SecondaryParameters>...</wst:SecondaryParameters>
560 ...
561 </wst:RequestSecurityToken>

562The following describes the attributes and elements listed in the schema overview above:
563/wst:RequestSecurityToken
564 This is a request to have a security token issued.
565/wst:RequestSecurityToken/@Context
566 This OPTIONAL URI specifies an identifier/context for this request. All subsequent RSTR
567 elements relating to this request MUST carry this attribute. This, for example, allows the request
568 and subsequent responses to be correlated. Note that no ordering semantics are provided; that
569 is left to the application/transport.
570/wst:RequestSecurityToken/wst:TokenType
571 This OPTIONAL element describes the type of security token requested, specified as a URI.
572 That is, the type of token that will be returned in the
573 <wst:RequestSecurityTokenResponse> message. Token type URIs are typically defined in
574 token profiles such as those in the OASIS WSS TC.
575/wst:RequestSecurityToken/wst:RequestType
576 The mandatory RequestType element is used to indicate, using a URI, the class of function that
577 is being requested. The allowed values are defined by specific bindings and profiles of WS-Trust.
578 Frequently this URI corresponds to the [WS-Addressing] Action URI provided in the message
579 header as described in the binding/profile; however, specific bindings can use the Action URI to
580 provide more details on the semantic processing while this parameter specifies the general class
581 of operation (e.g., token issuance). This parameter is REQUIRED.
582/wst:RequestSecurityToken/wst:SecondaryParameters
583 If specified, this OPTIONAL element contains zero or more valid RST parameters (except
584 wst:SecondaryParameters) for which the requestor is not the originator.
585 The STS processes parameters that are direct children of the <wst:RequestSecurityToken>
586 element. If a parameter is not specified as a direct child, the STS MAY look for the parameter
587 within the <wst:SecondaryParameters> element (if present). The STS MAY filter secondary
588 parameters if it doesn't trust them or feels they are inappropriate or introduce risk (or based on its
589 own policy).
590/wst:RequestSecurityToken/{any}
591 This is an extensibility mechanism to allow additional elements to be added. This allows
592 requestors to include any elements that the service can use to process the token request. As
593 well, this allows bindings to define binding-specific extensions. If an element is found that is not
594 understood, the recipient SHOULD fault.
595/wst:RequestSecurityToken/@{any}
596 This is an extensibility mechanism to allow additional attributes, based on schemas, to be added.
597 If an attribute is found that is not understood, the recipient SHOULD fault.

5983.2 Returning a Security Token

599The <wst:RequestSecurityTokenResponse> element (RSTR) is used to return a security token or
600response to a security token request. The <wst:RequestSecurityTokenResponseCollection>
46ws-trust-1.4-os 2 February 2009
47Copyright © OASIS® 1993–2009. All Rights Reserved. Page 16 of 88
601element (RSTRC) MUST be used to return a security token or response to a security token request on the
602final response.
603
604It should be noted that any type of parameter specified as input to a token request MAY be present on
605response in order to specify the exact parameters used by the issuer. Specific bindings describe
606appropriate restrictions on the contents of the RST and RSTR elements.
607In general, the returned token SHOULD be considered opaque to the requestor. That is, the requestor
608SHOULD NOT be required to parse the returned token. As a result, information that the requestor may
609desire, such as token lifetimes, SHOULD be returned in the response. Specifically, any field that the
610requestor includes SHOULD be returned. If an issuer doesn't want to repeat all input parameters, then, at
611a minimum, if the issuer chooses a value different from what was requested, the issuer SHOULD include
612the parameters that were changed.
613If a parameter is specified in a response that the recipient doesn't understand, the recipient SHOULD
614fault.
615In this specification the RSTR message is illustrated as being passed in the body of a message.
616However, there are scenarios where the RSTR must be passed in conjunction with an existing application
617message. In such cases the RSTR (or the RSTR collection) MAY be specified inside a header block.
618The exact location is determined by layered specifications and profiles; however, the RSTR MAY be
619located in the <wsse:Security> header if the token is being used to secure the message (note that the
620RSTR SHOULD occur before any uses of the token). The combination of which header block contains
621the RSTR and the value of the OPTIONAL @Context attribute indicate how the RSTR is processed. It
622should be noted that multiple RSTR elements can be specified in the header blocks of a message.
623It should be noted that there are cases where an RSTR is issued to a recipient who did not explicitly issue
624an RST (e.g. to propagate tokens). In such cases, the RSTR MAY be passed in the body or in a header
625block.
626The syntax for this element is as follows:
627 <wst:RequestSecurityTokenResponse Context="..." xmlns:wst="...">
628 <wst:TokenType>...</wst:TokenType>
629 <wst:RequestedSecurityToken>...</wst:RequestedSecurityToken>
630 ...
631 </wst:RequestSecurityTokenResponse>

632The following describes the attributes and elements listed in the schema overview above:
633/wst:RequestSecurityTokenResponse
634 This is the response to a security token request.
635/wst:RequestSecurityTokenResponse/@Context
636 This OPTIONAL URI specifies the identifier from the original request. That is, if a context URI is
637 specified on a RST, then it MUST be echoed on the corresponding RSTRs. For unsolicited
638 RSTRs (RSTRs that aren't the result of an explicit RST), this represents a hint as to how the
639 recipient is expected to use this token. No values are pre-defined for this usage; this is for use by
640 specifications that leverage the WS-Trust mechanisms.
641/wst:RequestSecurityTokenResponse/wst:TokenType
642 This OPTIONAL element specifies the type of security token returned.
643/wst:RequestSecurityTokenResponse/wst:RequestedSecurityToken
644 This OPTIONAL element is used to return the requested security token. Normally the requested
645 security token is the contents of this element but a security token reference MAY be used instead.
646 For example, if the requested security token is used in securing the message, then the security

49ws-trust-1.4-os 2 February 2009

50Copyright © OASIS® 1993–2009. All Rights Reserved. Page 17 of 88
647 token is placed into the <wsse:Security> header (as described in [WS-Security]) and a
648 <wsse:SecurityTokenReference> element is placed inside of the
649 <wst:RequestedSecurityToken> element to reference the token in the <wsse:Security>
650 header. The response MAY contain a token reference where the token is located at a URI
651 outside of the message. In such cases the recipient is assumed to know how to fetch the token
652 from the URI address or specified endpoint reference. It should be noted that when the token is
653 not returned as part of the message it cannot be secured, so a secure communication
654 mechanism SHOULD be used to obtain the token.
655/wst:RequestSecurityTokenResponse/{any}
656 This is an extensibility mechanism to allow additional elements to be added. If an element is
657 found that is not understood, the recipient SHOULD fault.
658/wst:RequestSecurityTokenResponse/@{any}
659 This is an extensibility mechanism to allow additional attributes, based on schemas, to be added.
660 If an attribute is found that is not understood, the recipient SHOULD fault.

6613.3 Binary Secrets

662It should be noted that in some cases elements include a key that is not encrypted. Consequently, the
663<xenc:EncryptedData> cannot be used. Instead, the <wst:BinarySecret> element can be used.
664This SHOULD only be used when the message is otherwise protected (e.g. transport security is used or
665the containing element is encrypted). This element contains a base64 encoded value that represents an
666arbitrary octet sequence of a secret (or key). The general syntax of this element is as follows (note that
667the ellipses below represent the different containers in which this element MAY appear, for example, a
668<wst:Entropy> or <wst:RequestedProofToken> element):
669.../wst:BinarySecret
670 This element contains a base64 encoded binary secret (or key). This can be either a symmetric
671 key, the private portion of an asymmetric key, or any data represented as binary octets.
672.../wst:BinarySecret/@Type
673 This OPTIONAL attribute indicates the type of secret being encoded. The pre-defined values are
674 listed in the table below:

URI Meaning
http://docs.oasis-open.org/ws-sx/ws- The private portion of a public key token
trust/200512/AsymmetricKey is returned – this URI assumes both
parties agree on the format of the octets;
other bindings and profiles MAY define
additional URIs with specific formats
http://docs.oasis-open.org/ws-sx/ws- A symmetric key token is returned
trust/200512/SymmetricKey (default)
http://docs.oasis-open.org/ws-sx/ws- A raw nonce value (typically passed as
trust/200512/Nonce entropy or key material)
675.../wst:BinarySecret/@{any}
676 This is an extensibility mechanism to allow additional attributes, based on schemas, to be added.
677 If an attribute is found that is not understood, the recipient SHOULD fault.

52ws-trust-1.4-os 2 February 2009

53Copyright © OASIS® 1993–2009. All Rights Reserved. Page 18 of 88
6783.4 Composition
679The sections below, as well as other documents, describe a set of bindings using the model framework
680described in the above sections. Each binding describes the amount of extensibility and composition with
681other parts of WS-Trust that is permitted. Additional profile documents MAY further restrict what can be
682specified in a usage of a binding.

55ws-trust-1.4-os 2 February 2009

56Copyright © OASIS® 1993–2009. All Rights Reserved. Page 19 of 88
6834 Issuance Binding
684Using the token request framework, this section defines bindings for requesting security tokens to be
685issued:
686 Issue – Based on the credential provided/proven in the request, a new token is issued, possibly
687 with new proof information.
688For this binding, the following [WS-Addressing] actions are defined to enable specific processing context
689to be conveyed to the recipient:
690 http://docs.oasis-open.org/ws-sx/ws-trust/200512/RST/Issue
691 http://docs.oasis-open.org/ws-sx/ws-trust/200512/RSTR/Issue
692 http://docs.oasis-open.org/ws-sx/ws-trust/200512/RSTRC/IssueFinal

693For this binding, the <wst:RequestType> element uses the following URI:
694 http://docs.oasis-open.org/ws-sx/ws-trust/200512/Issue

695The mechanisms defined in this specification apply to both symmetric and asymmetric keys. As an
696example, a Kerberos KDC could provide the services defined in this specification to make tokens
697available; similarly, so can a public key infrastructure. In such cases, the issuing authority is the security
698token service. It should be noted that in practice, asymmetric key usage often differs as it is common to
699reuse existing asymmetric keys rather than regenerate due to the time cost and desire to map to a
700common public key. In such cases a request might be made for an asymmetric token providing the public
701key and proving ownership of the private key. The public key is then used in the issued token.
702
703A public key directory is not really a security token service per se; however, such a service MAY
704implement token retrieval as a form of issuance. It is also possible to bridge environments (security
705technologies) using PKI for authentication or bootstrapping to a symmetric key.
706
707This binding provides a general token issuance action that can be used for any type of token being
708requested. Other bindings MAY use separate actions if they have specialized semantics.
709
710This binding supports the OPTIONAL use of exchanges during the token acquisition process as well as
711the OPTIONAL use of the key extensions described in a later section. Additional profiles are needed to
712describe specific behaviors (and exclusions) when different combinations are used.

7134.1 Requesting a Security Token

714When requesting a security token to be issued, the following OPTIONAL elements MAY be included in
715the request and MAY be provided in the response. The syntax for these elements is as follows (note that
716the base elements described above are included here italicized for completeness):
717 <wst:RequestSecurityToken xmlns:wst="...">
718 <wst:TokenType>...</wst:TokenType>
719 <wst:RequestType>...</wst:RequestType>
720 ...
721 <wsp:AppliesTo>...</wsp:AppliesTo>
722 <wst:Claims Dialect="...">...</wst:Claims>
723 <wst:Entropy>
724 <wst:BinarySecret>...</wst:BinarySecret>
725 </wst:Entropy>

58ws-trust-1.4-os 2 February 2009

59Copyright © OASIS® 1993–2009. All Rights Reserved. Page 20 of 88
 726 <wst:Lifetime>
727 <wsu:Created>...</wsu:Created>
728 <wsu:Expires>...</wsu:Expires>
729 </wst:Lifetime>
730 </wst:RequestSecurityToken>

731The following describes the attributes and elements listed in the schema overview above:
732/wst:RequestSecurityToken/wst:TokenType
733 If this OPTIONAL element is not specified in an issue request, it is RECOMMENDED that the
734 OPTIONAL element <wsp:AppliesTo> be used to indicate the target where this token will be
735 used (similar to the Kerberos target service model). This assumes that a token type can be
736 inferred from the target scope specified. That is, either the <wst:TokenType> or the
737 <wsp:AppliesTo> element SHOULD be defined within a request. If both the
738 <wst:TokenType> and <wsp:AppliesTo> elements are defined, the <wsp:AppliesTo>
739 element takes precedence (for the current request only) in case the target scope requires a
740 specific type of token.
741/wst:RequestSecurityToken/wsp:AppliesTo
742 This OPTIONAL element specifies the scope for which this security token is desired – for
743 example, the service(s) to which this token applies. Refer to [WS-PolicyAttachment] for more
744 information. Note that either this element or the <wst:TokenType> element SHOULD be
745 defined in a <wst:RequestSecurityToken> message. In the situation where BOTH fields
746 have values, the <wsp:AppliesTo> field takes precedence. This is because the issuing service
747 is more likely to know the type of token to be used for the specified scope than the requestor (and
748 because returned tokens should be considered opaque to the requestor).
749/wst:RequestSecurityToken/wst:Claims
750 This OPTIONAL element requests a specific set of claims. Typically, this element contains
751 REQUIRED and/or OPTIONAL claim information identified in a service's policy.
752/wst:RequestSecurityToken/wst:Claims/@Dialect
753 This REQUIRED attribute contains a URI that indicates the syntax used to specify the set of
754 requested claims along with how that syntax SHOULD be interpreted. No URIs are defined by
755 this specification; it is expected that profiles and other specifications will define these URIs and
756 the associated syntax.
757/wst:RequestSecurityToken/wst:Entropy
758 This OPTIONAL element allows a requestor to specify entropy that is to be used in creating the
759 key. The value of this element SHOULD be either a <xenc:EncryptedKey> or
760 <wst:BinarySecret> depending on whether or not the key is encrypted. Secrets SHOULD be
761 encrypted unless the transport/channel is already providing encryption.
762/wst:RequestSecurityToken/wst:Entropy/wst:BinarySecret
763 This OPTIONAL element specifies a base64 encoded sequence of octets representing the
764 requestor's entropy. The value can contain either a symmetric or the private key of an
765 asymmetric key pair, or any suitable key material. The format is assumed to be understood by
766 the requestor because the value space MAY be (a) fixed, (b) indicated via policy, (c) inferred from
767 the indicated token aspects and/or algorithms, or (d) determined from the returned token. (See
768 Section 3.3)
769/wst:RequestSecurityToken/wst:Lifetime
770 This OPTIONAL element is used to specify the desired valid time range (time window during
771 which the token is valid for use) for the returned security token. That is, to request a specific time
772 interval for using the token. The issuer is not obligated to honor this range – they MAY return a
773 more (or less) restrictive interval. It is RECOMMENDED that the issuer return this element with

61ws-trust-1.4-os 2 February 2009

62Copyright © OASIS® 1993–2009. All Rights Reserved. Page 21 of 88
774 issued tokens (in the RSTR) so the requestor knows the actual validity period without having to
775 parse the returned token.
776/wst:RequestSecurityToken/wst:Lifetime/wsu:Created
777 This OPTIONAL element represents the creation time of the security token. Within the SOAP
778 processing model, creation is the instant that the infoset is serialized for transmission. The
779 creation time of the token SHOULD NOT differ substantially from its transmission time. The
780 difference in time SHOULD be minimized. If this time occurs in the future then this is a request
781 for a postdated token. If this attribute isn't specified, then the current time is used as an initial
782 period.
783/wst:RequestSecurityToken/wst:Lifetime/wsu:Expires
784 This OPTIONAL element specifies an absolute time representing the upper bound on the validity
785 time period of the requested token. If this attribute isn't specified, then the service chooses the
786 lifetime of the security token. A Fault code (wsu:MessageExpired) is provided if the recipient
787 wants to inform the requestor that its security semantics were expired. A service MAY issue a
788 Fault indicating the security semantics have expired.
789
790The following is a sample request. In this example, a username token is used as the basis for the request
791as indicated by the use of that token to generate the signature. The username (and password) is
792encrypted for the recipient and a reference list element is added. The <ds:KeyInfo> element refers to
793a <wsse:UsernameToken> element that has been encrypted to protect the password (note that the
794token has the wsu:Id of "myToken" prior to encryption). The request is for a custom token type to be
795returned.
796 <S11:Envelope xmlns:S11="..." xmlns:wsu="..." xmlns:wsse="..."
797 xmlns:xenc="..." xmlns:wst="...">
798 <S11:Header>
799 ...
800 <wsse:Security>
801 <xenc:ReferenceList>...</xenc:ReferenceList>
802 <xenc:EncryptedData Id="encUsername">...</xenc:EncryptedData>
803 <ds:Signature xmlns:ds="...">
804 ...
805 <ds:KeyInfo>
806 <wsse:SecurityTokenReference>
807 <wsse:Reference URI="#myToken"/>
808 </wsse:SecurityTokenReference>
809 </ds:KeyInfo>
810 </ds:Signature>
811 </wsse:Security>
812 ...
813 </S11:Header>
814 <S11:Body wsu:Id="req">
815 <wst:RequestSecurityToken>
816 <wst:TokenType>
817 http://example.org/mySpecialToken
818 </wst:TokenType>
819 <wst:RequestType>
820 http://docs.oasis-open.org/ws-sx/ws-trust/200512/Issue
821 </wst:RequestType>
822 </wst:RequestSecurityToken>
823 </S11:Body>
824 </S11:Envelope>

64ws-trust-1.4-os 2 February 2009

65Copyright © OASIS® 1993–2009. All Rights Reserved. Page 22 of 88
8254.2 Request Security Token Collection
826There are occasions where efficiency is important. Reducing the number of messages in a message
827exchange pattern can greatly improve efficiency. One way to do this in the context of WS-Trust is to avoid
828repeated round-trips for multiple token requests. An example is requesting an identity token as well as
829tokens that offer other claims in a single batch request operation.
830
831To give an example, imagine an automobile parts supplier that wishes to offer parts to an automobile
832manufacturer. To interact with the manufacturer web service the parts supplier may have to present a
833number of tokens, such as an identity token as well as tokens with claims, such as tokens indicating
834various certifications to meet supplier requirements.
835
836It is possible for the supplier to authenticate to a trust server and obtain an identity token and then
837subsequently present that token to obtain a certification claim token. However, it may be much more
838efficient to request both in a single interaction (especially when more than two tokens are required).
839
840Here is an example of a collection of authentication requests corresponding to this scenario:
841
842 <wst:RequestSecurityTokenCollection xmlns:wst="...">
843
844 <!-- identity token request -->
845 <wst:RequestSecurityToken Context="http://www.example.com/1">
846 <wst:TokenType>
847 http://docs.oasis-open.org/wss/oasis-wss-saml-token-profile-
848 1.1#SAMLV2.0
849 </wst:TokenType>
850 <wst:RequestType>http://docs.oasis-open.org/ws-sx/ws-
851 trust/200512/BatchIssue</wst:RequestType>
852 <wsp:AppliesTo xmlns:wsp="..." xmlns:wsa="...">
853 <wsa:EndpointReference>
854 <wsa:Address>http://manufacturer.example.com/</wsa:Address>
855 </wsa:EndpointReference>
856 </wsp:AppliesTo>
857 <wsp:PolicyReference xmlns:wsp="..."
858 URI='http://manufacturer.example.com/IdentityPolicy' />
859 </wst:RequestSecurityToken>
860
861 <!-- certification claim token request -->
862 <wst:RequestSecurityToken Context="http://www.example.com/2">
863 <wst:TokenType>
864 http://docs.oasis-open.org/wss/oasis-wss-saml-token-profile-
865 1.1#SAMLV2.0
866 </wst:TokenType>
867 <wst:RequestType>http://docs.oasis-open.org/ws-sx/ws-trust/200512
868 /BatchIssue</wst:RequestType>
869 <wst:Claims xmlns:wsp="...">
870 http://manufacturer.example.com/certification
871 </wst:Claims>
872 <wsp:PolicyReference
873 URI='http://certificationbody.example.org/certificationPolicy’ />
874 </wst:RequestSecurityToken>
875 </wst:RequestSecurityTokenCollection>

876
877The following describes the attributes and elements listed in the overview above:
67ws-trust-1.4-os 2 February 2009
68Copyright © OASIS® 1993–2009. All Rights Reserved. Page 23 of 88
878
879/wst:RequestSecurityTokenCollection
880 The RequestSecurityTokenCollection (RSTC) element is used to provide multiple RST
881 requests. One or more RSTR elements in an RSTRC element are returned in the response to the
882 RequestSecurityTokenCollection.

8834.2.1 Processing Rules

884The RequestSecurityTokenCollection (RSTC) element contains 2 or more

885RequestSecurityToken elements.
886
887 1. The single RequestSecurityTokenResponseCollection response MUST contain at least
888 one RSTR element corresponding to each RST element in the request. A RSTR element
889 corresponds to an RST element if it has the same Context attribute value as the RST element.
890 Note: Each request MAY generate more than one RSTR sharing the same Context attribute
891 value
892 a. Specifically there is no notion of a deferred response
893 b. If any RST request results in an error, then no RSTRs will be returned and a SOAP Fault
894 will be generated as the entire response.
895 2. Every RST in the request MUST use an action URI value in the RequestType element that is a
896 batch version corresponding to the non-batch version, in particular one of the following:
897  http://docs.oasis-open.org/ws-sx/ws-trust/200512/BatchIssue
898  http://docs.oasis-open.org/ws-sx/ws-trust/200512/BatchValidate
899  http://docs.oasis-open.org/ws-sx/ws-trust/200512/BatchRenew
900  http://docs.oasis-open.org/ws-sx/ws-trust/200512/BatchCancel
901
902 These URIs MUST also be used for the [WS-Addressing] actions defined to enable specific
903 processing context to be conveyed to the recipient.
904
905 Note: that these operations require that the service can either succeed on all the RST requests or
906 MUST NOT perform any partial operation.
907
908 3. All Signatures MUST reference the entire RSTC. One or more Signatures referencing the entire
909 collection MAY be used.
910 4. No negotiation or other multi-leg authentication mechanisms are allowed in batch requests or
911 responses to batch requests; the communication with STS is limited to one RSTC request and
912 one RSTRC response.
913 5. This mechanism requires that every RST in a RSTC is to be handled by the single endpoint
914 processing the RSTC.
915
916If any error occurs in the processing of the RSTC or one of its contained RSTs, a SOAP fault MUST be
917generated for the entire batch request so no RSTC element will be returned.
918

70ws-trust-1.4-os 2 February 2009

71Copyright © OASIS® 1993–2009. All Rights Reserved. Page 24 of 88
9194.3 Returning a Security Token Collection
920The <wst:RequestSecurityTokenResponseCollection> element (RSTRC) MUST be used to return a
921security token or response to a security token request on the final response. Security tokens can only be
922returned in the RSTRC on the final leg. One or more <wst:RequestSecurityTokenResponse> elements
923are returned in the RSTRC.
924The syntax for this element is as follows:
925 <wst:RequestSecurityTokenResponseCollection xmlns:wst="...">
926 <wst:RequestSecurityTokenResponse>...</wst:RequestSecurityTokenResponse> +
927 </wst:RequestSecurityTokenResponseCollection>

928The following describes the attributes and elements listed in the schema overview above:
929/wst:RequestSecurityTokenResponseCollection
930 This element contains one or more <wst:RequestSecurityTokenResponse> elements for a
931 security token request on the final response.
932/wst:RequestSecurityTokenResponseCollection/wst:RequestSecurityTokenResponse
933 See section 4.4 for the description of the <wst:RequestSecurityTokenResponse> element.

9344.4 Returning a Security Token

935When returning a security token, the following OPTIONAL elements MAY be included in the response.
936Security tokens can only be returned in the RSTRC on the final leg. The syntax for these elements is as
937follows (note that the base elements described above are included here italicized for completeness):
938 <wst:RequestSecurityTokenResponse xmlns:wst="...">
939 <wst:TokenType>...</wst:TokenType>
940 <wst:RequestedSecurityToken>...</wst:RequestedSecurityToken>
941 ...
942 <wsp:AppliesTo xmlns:wsp="...”>...</wsp:AppliesTo>
943 <wst:RequestedAttachedReference>
944 ...
945 </wst:RequestedAttachedReference>
946 <wst:RequestedUnattachedReference>
947 ...
948 </wst:RequestedUnattachedReference>
949 <wst:RequestedProofToken>...</wst:RequestedProofToken>
950 <wst:Entropy>
951 <wst:BinarySecret>...</wst:BinarySecret>
952 </wst:Entropy>
953 <wst:Lifetime>...</wst:Lifetime>
954 </wst:RequestSecurityTokenResponse>

955The following describes the attributes and elements listed in the schema overview above:
956/wst:RequestSecurityTokenResponse/wsp:AppliesTo
957 This OPTIONAL element specifies the scope to which this security token applies. Refer to [WS-
958 PolicyAttachment] for more information. Note that if an <wsp:AppliesTo> was specified in the
959 request, the same scope SHOULD be returned in the response (if a <wsp:AppliesTo> is
960 returned).
961/wst:RequestSecurityTokenResponse/wst:RequestedSecurityToken
962 This OPTIONAL element is used to return the requested security token. This element is
963 OPTIONAL, but it is REQUIRED that at least one of <wst:RequestedSecurityToken> or
964 <wst:RequestedProofToken> be returned unless there is an error or part of an on-going
965 message exchange (e.g. negotiation). If returning more than one security token see section 4.3,
966 Returning Multiple Security Tokens.
73ws-trust-1.4-os 2 February 2009
74Copyright © OASIS® 1993–2009. All Rights Reserved. Page 25 of 88
 967/wst:RequestSecurityTokenResponse/wst:RequestedAttachedReference
968 Since returned tokens are considered opaque to the requestor, this OPTIONAL element is
969 specified to indicate how to reference the returned token when that token doesn't support
970 references using URI fragments (XML ID). This element contains a
971 <wsse:SecurityTokenReference> element that can be used verbatim to reference the token
972 (when the token is placed inside a message). Typically tokens allow the use of wsu:Id so this
973 element isn't required. Note that a token MAY support multiple reference mechanisms; this
974 indicates the issuer’s preferred mechanism. When encrypted tokens are returned, this element is
975 not needed since the <xenc:EncryptedData> element supports an ID reference. If this
976 element is not present in the RSTR then the recipient can assume that the returned token (when
977 present in a message) supports references using URI fragments.
978/wst:RequestSecurityTokenResponse/wst:RequestedUnattachedReference
979 In some cases tokens need not be present in the message. This OPTIONAL element is specified
980 to indicate how to reference the token when it is not placed inside the message. This element
981 contains a <wsse:SecurityTokenReference> element that can be used verbatim to
982 reference the token (when the token is not placed inside a message) for replies. Note that a token
983 MAY support multiple external reference mechanisms; this indicates the issuer’s preferred
984 mechanism.
985/wst:RequestSecurityTokenResponse/wst:RequestedProofToken
986 This OPTIONAL element is used to return the proof-of-possession token associated with the
987 requested security token. Normally the proof-of-possession token is the contents of this element
988 but a security token reference MAY be used instead. The token (or reference) is specified as the
989 contents of this element. For example, if the proof-of-possession token is used as part of the
990 securing of the message, then it is placed in the <wsse:Security> header and a
991 <wsse:SecurityTokenReference> element is used inside of the
992 <wst:RequestedProofToken> element to reference the token in the <wsse:Security>
993 header. This element is OPTIONAL, but it is REQUIRED that at least one of
994 <wst:RequestedSecurityToken> or <wst:RequestedProofToken> be returned unless
995 there is an error.
996/wst:RequestSecurityTokenResponse/wst:Entropy
997 This OPTIONAL element allows an issuer to specify entropy that is to be used in creating the key.
998 The value of this element SHOULD be either a <xenc:EncryptedKey> or
999 <wst:BinarySecret> depending on whether or not the key is encrypted (it SHOULD be unless
1000 the transport/channel is already encrypted).
1001/wst:RequestSecurityTokenResponse/wst:Entropy/wst:BinarySecret
1002 This OPTIONAL element specifies a base64 encoded sequence of octets represent the
1003 responder's entropy. (See Section 3.3)
1004/wst:RequestSecurityTokenResponse/wst:Lifetime
1005 This OPTIONAL element specifies the lifetime of the issued security token. If omitted the lifetime
1006 is unspecified (not necessarily unlimited). It is RECOMMENDED that if a lifetime exists for a
1007 token that this element be included in the response.

10084.4.1 wsp:AppliesTo in RST and RSTR

1009Both the requestor and the issuer can specify a scope for the issued token using the <wsp:AppliesTo>
1010element. If a token issuer cannot provide a token with a scope that is at least as broad as that requested
1011by the requestor then it SHOULD generate a fault. This section defines some rules for interpreting the
1012various combinations of provided scope:

76ws-trust-1.4-os 2 February 2009

77Copyright © OASIS® 1993–2009. All Rights Reserved. Page 26 of 88
1013  If neither the requestor nor the issuer specifies a scope then the scope of the issued token is
1014 implied.
1015  If the requestor specifies a scope and the issuer does not then the scope of the token is assumed
1016 to be that specified by the requestor.
1017  If the requestor does not specify a scope and the issuer does specify a scope then the scope of
1018 the token is as defined by the issuers scope
1019  If both requestor and issuer specify a scope then there are two possible outcomes:
1020 o If both the issuer and requestor specify the same scope then the issued token has that
1021 scope.
1022 o If the issuer specifies a wider scope than the requestor then the issued token has the
1023 scope specified by the issuer.
1024  The requestor and issuer MUST agree on the version of [WS-Policy] used to specify the scope of
1025 the issued token. The Trust13 assertion in [WS-SecurityPolicy] provides a mechanism to
1026 communicate which version of [WS-Policy] is to be used.
1027
1028The following table summarizes the above rules:
Requestor wsp:AppliesTo Issuer wsp:AppliesTo Results
Absent Absent OK. Implied scope.
Present Absent OK. Issued token has scope
specified by requestor.
Absent Present OK. Resulting token has scope
specified by issuer.
Present Present and matches OK.
Requestor
Present Present and specifies a scope OK. Issuer scope.
greater than specified by the
requestor

10294.4.2 Requested References

1030The token issuer can OPTIONALLY provide <wst:RequestedAttachedReference> and/or
1031<wst:RequestedUnattachedReference> elements in the RSTR. It is assumed that all token types can be
1032referred to directly when present in a message. This section outlines the expected behaviour on behalf of
1033clients and servers with respect to various permutations:
1034  If a <wst:RequestedAttachedReference> element is NOT returned in the RSTR then the client
1035 SHOULD assume that the token can be referenced by ID. Alternatively, the client MAY use token-
1036 specific knowledge to construct an STR.
1037  If a <wst:RequestedAttachedReference> element is returned in the RSTR then the token
1038 cannot be referred to by ID. The supplied STR MUST be used to refer to the token.
1039  If a <wst:RequestedUnattachedReference> element is returned then the server MAY reference
1040 the token using the supplied STR when sending responses back to the client. Thus the client
1041 MUST be prepared to resolve the supplied STR to the appropriate token. Note: the server
1042 SHOULD NOT send the token back to the client as the token is often tailored specifically to the

79ws-trust-1.4-os 2 February 2009

80Copyright © OASIS® 1993–2009. All Rights Reserved. Page 27 of 88
1043 server (i.e. it may be encrypted for the server). References to the token in subsequent messages,
1044 whether sent by the client or the server, that omit the token MUST use the supplied STR.

10454.4.3 Keys and Entropy

1046The keys resulting from a request are determined in one of three ways: specific, partial, and omitted.
1047  In the case of specific keys, a <wst:RequestedProofToken> element is included in the
1048 response which indicates the specific key(s) to use unless the key was provided by the requestor
1049 (in which case there is no need to return it).
1050  In the case of partial, the <wst:Entropy> element is included in the response, which indicates
1051 partial key material from the issuer (not the full key) that is combined (by each party) with the
1052 requestor's entropy to determine the resulting key(s). In this case a <wst:ComputedKey>
1053 element is returned inside the <wst:RequestedProofToken> to indicate how the key is
1054 computed.
1055  In the case of omitted, an existing key is used or the resulting token is not directly associated with
1056 a key.
1057
1058The decision as to which path to take is based on what the requestor provides, what the issuer provides,
1059and the issuer's policy.
1060  If the requestor does not provide entropy or issuer rejects the requestor's entropy, a proof-of-
1061 possession token MUST be returned with an issuer-provided key.
1062  If the requestor provides entropy and the responder doesn't (issuer uses the requestor's key),
1063 then a proof-of-possession token need not be returned.
1064  If both the requestor and the issuer provide entropy, then the partial form is used. Ideally both
1065 entropies are specified as encrypted values and the resultant key is never used (only keys
1066 derived from it are used). As noted above, the <wst:ComputedKey> element is returned inside
1067 the <wst:RequestedProofToken> to indicate how the key is computed.
1068
1069The following table illustrates the rules described above:
Requestor Issuer Results

Provide Entropy Uses requestor entropy as key No proof-of-possession token is

returned.
Provides entropy No keys returned, key(s) derived
using entropy from both sides
according to method identified in
response
Issues own key (rejects Proof-of-possession token contains
requestor's entropy) issuer's key(s)
No Entropy provided Issues own key Proof-of-possession token contains
issuer's key(s)
Does not issue key No proof-of-possession token

82ws-trust-1.4-os 2 February 2009

83Copyright © OASIS® 1993–2009. All Rights Reserved. Page 28 of 88
10704.4.4 Returning Computed Keys
1071As previously described, in some scenarios the key(s) resulting from a token request are not directly
1072returned and must be computed. One example of this is when both parties provide entropy that is
1073combined to make the shared secret. To indicate a computed key, the <wst:ComputedKey> element
1074MUST be returned inside the <wst:RequestedProofToken> to indicate how the key is computed. The
1075following illustrates a syntax overview of the <wst:ComputedKey> element:
1076 <wst:RequestSecurityTokenResponseCollection xmlns:wst="...">
1077 <wst:RequestSecurityTokenResponse>
1078 <wst:RequestedProofToken>
1079 <wst:ComputedKey>...</wst:ComputedKey>
1080 </wst:RequestedProofToken>
1081 </wst:RequestSecurityTokenResponse>
1082 </wst:RequestSecurityTokenResponseCollection>

1083
1084The following describes the attributes and elements listed in the schema overview above:
1085/wst:RequestSecurityTokenResponse/wst:RequestedProofToken/wst:ComputedKey
1086 The value of this element is a URI describing how to compute the key. While this can be
1087 extended by defining new URIs in other bindings and profiles, the following URI pre-defines one
1088 computed key mechanism:

URI Meaning
http://docs.oasis-open.org/ws-sx/ws- The key is computed using P_SHA1 from the
trust/200512/CK/PSHA1 TLS specification to generate a bit stream
using entropy from both sides. The exact
form is:
key = P_SHA1 (EntREQ, EntRES)
It is RECOMMENDED that EntREQ be a
string of length at least 128 bits.
1089 This element MUST be returned when key(s) resulting from the token request are computed.

10904.4.5 Sample Response with Encrypted Secret

1091The following illustrates the syntax of a sample security token response. In this example the token
1092requested in section 4.1 is returned. Additionally a proof-of-possession token element is returned
1093containing the secret key associated with the <wst:RequestedSecurityToken> encrypted for the
1094requestor (note that this assumes that the requestor has a shared secret with the issuer or a public key).
1095 <wst:RequestSecurityTokenResponseCollection xmlns:wst="...”>
1096 <wst:RequestSecurityTokenResponse>
1097 <wst:RequestedSecurityToken>
1098 <xyz:CustomToken xmlns:xyz="...">
1099 ...
1100 </xyz:CustomToken>
1101 </wst:RequestedSecurityToken>
1102 <wst:RequestedProofToken>
1103 <xenc:EncryptedKey Id="newProof" xmlns:xenc="...">
1104 ...
1105 </xenc:EncryptedKey>
1106 </wst:RequestedProofToken>
1107 </wst:RequestSecurityTokenResponse>
1108 </wst:RequestSecurityTokenResponseCollection>

85ws-trust-1.4-os 2 February 2009

86Copyright © OASIS® 1993–2009. All Rights Reserved. Page 29 of 88
11094.4.6 Sample Response with Unencrypted Secret
1110The following illustrates the syntax of an alternative form where the secret is passed in the clear because
1111the transport is providing confidentiality:
1112 <wst:RequestSecurityTokenResponseCollection xmlns:wst="...”>
1113 <wst:RequestSecurityTokenResponse>
1114 <wst:RequestedSecurityToken>
1115 <xyz:CustomToken xmlns:xyz="...">
1116 ...
1117 </xyz:CustomToken>
1118 </wst:RequestedSecurityToken>
1119 <wst:RequestedProofToken>
1120 <wst:BinarySecret>...</wst:BinarySecret>
1121 </wst:RequestedProofToken>
1122 </wst:RequestSecurityTokenResponse>
1123 </wst:RequestSecurityTokenResponseCollection>

11244.4.7 Sample Response with Token Reference

1125If the returned token doesn't allow the use of the wsu:Id attribute, then a
1126<wst:RequestedAttachedReference> is returned as illustrated below. The following illustrates the
1127syntax of the returned token has a URI which is referenced.
1128 <wst:RequestSecurityTokenResponseCollection xmlns:wst="...”>
1129 <wst:RequestSecurityTokenResponse>
1130 <wst:RequestedSecurityToken>
1131 <xyz:CustomToken ID="urn:fabrikam123:5445" xmlns:xyz="...">
1132 ...
1133 </xyz:CustomToken>
1134 </wst:RequestedSecurityToken>
1135 <wst:RequestedAttachedReference>
1136 <wsse:SecurityTokenReference xmlns:wsse="...”>
1137 <wsse:Reference URI="urn:fabrikam123:5445"/>
1138 </wsse:SecurityTokenReference>
1139 </wst:RequestedAttachedReference>
1140 ...
1141 </wst:RequestSecurityTokenResponse>
1142 </wst:RequestSecurityTokenResponseCollection>

1143
1144In the example above, the recipient may place the returned custom token directly into a message and
1145include a signature using the provided proof-of-possession token. The specified reference is then placed
1146into the <ds:KeyInfo> of the signature and directly references the included token without requiring the
1147requestor to understand the details of the custom token format.

11484.4.8 Sample Response without Proof-of-Possession Token

1149The following illustrates the syntax of a response that doesn't include a proof-of-possession token. For
1150example, if the basis of the request were a public key token and another public key token is returned with
1151the same public key, the proof-of-possession token from the original token is reused (no new proof-of-
1152possession token is required).
1153 <wst:RequestSecurityTokenResponseCollection xmlns:wst="...”>
1154 <wst:RequestSecurityTokenResponse>
1155 <wst:RequestedSecurityToken>
1156 <xyz:CustomToken xmlns:xyz="...">
1157 ...
1158 </xyz:CustomToken>

88ws-trust-1.4-os 2 February 2009

89Copyright © OASIS® 1993–2009. All Rights Reserved. Page 30 of 88
 1159 </wst:RequestedSecurityToken>
1160 </wst:RequestSecurityTokenResponse>
1161 </wst:RequestSecurityTokenResponseCollection>

1162

11634.4.9 Zero or One Proof-of-Possession Token Case

1164In the zero or single proof-of-possession token case, a primary token and one or more tokens are
1165returned. The returned tokens either use the same proof-of-possession token (one is returned), or no
1166proof-of-possession token is returned. The tokens are returned (one each) in the response. The
1167following example illustrates this case. The following illustrates the syntax of a supporting security token
1168is returned that has no separate proof-of-possession token as it is secured using the same proof-of-
1169possession token that was returned.
1170
1171 <wst:RequestSecurityTokenResponseCollection xmlns:wst="...”>
1172 <wst:RequestSecurityTokenResponse>
1173 <wst:RequestedSecurityToken>
1174 <xyz:CustomToken xmlns:xyz="...">
1175 ...
1176 </xyz:CustomToken>
1177 </wst:RequestedSecurityToken>
1178 <wst:RequestedProofToken>
1179 <xenc:EncryptedKey Id="newProof" xmlns:xenc="...”>
1180 ...
1181 </xenc:EncryptedKey>
1182 </wst:RequestedProofToken>
1183 </wst:RequestSecurityTokenResponse>
1184 </wst:RequestSecurityTokenResponseCollection>

11854.4.10 More Than One Proof-of-Possession Tokens Case

1186The second case is where multiple security tokens are returned that have separate proof-of-possession
1187tokens. As a result, the proof-of-possession tokens, and possibly lifetime and other key parameters
1188elements, MAY be different. To address this scenario, the body MAY be specified using the syntax
1189illustrated below:
1190 <wst:RequestSecurityTokenResponseCollection xmlns:wst="...”>
1191 <wst:RequestSecurityTokenResponse>
1192 ...
1193 </wst:RequestSecurityTokenResponse>
1194 <wst:RequestSecurityTokenResponse>
1195 ...
1196 </wst:RequestSecurityTokenResponse>
1197 ...
1198 </wst:RequestSecurityTokenResponseCollection>

1199The following describes the attributes and elements listed in the schema overview above:
1200/wst:RequestSecurityTokenResponseCollection
1201 This element is used to provide multiple RSTR responses, each of which has separate key
1202 information. One or more RSTR elements are returned in the collection. This MUST always be
1203 used on the final response to the RST.
1204/wst:RequestSecurityTokenResponseCollection/wst:RequestSecurityTokenResponse
1205 Each RequestSecurityTokenResponse element is an individual RSTR.
1206/wst:RequestSecurityTokenResponseCollection/{any}

91ws-trust-1.4-os 2 February 2009

92Copyright © OASIS® 1993–2009. All Rights Reserved. Page 31 of 88
 1207 This is an extensibility mechanism to allow additional elements, based on schemas, to be added.
1208/wst:RequestSecurityTokenResponseCollection/@{any}
1209 This is an extensibility mechanism to allow additional attributes, based on schemas, to be added.
1210The following illustrates the syntax of a response that includes multiple tokens each, in a separate RSTR,
1211each with their own proof-of-possession token.
1212 <wst:RequestSecurityTokenResponseCollection xmlns:wst="...”>
1213 <wst:RequestSecurityTokenResponse>
1214 <wst:RequestedSecurityToken>
1215 <xyz:CustomToken xmlns:xyz="...">
1216 ...
1217 </xyz:CustomToken>
1218 </wst:RequestedSecurityToken>
1219 <wst:RequestedProofToken>
1220 <xenc:EncryptedKey Id="newProofA">
1221 ...
1222 </xenc:EncryptedKey>
1223 </wst:RequestedProofToken>
1224 </wst:RequestSecurityTokenResponse>
1225 <wst:RequestSecurityTokenResponse>
1226 <wst:RequestedSecurityToken>
1227 <abc:CustomToken xmlns:abc="...">
1228 ...
1229 </abc:CustomToken>
1230 </wst:RequestedSecurityToken>
1231 <wst:RequestedProofToken>
1232 <xenc:EncryptedKey Id="newProofB xmlns:xenc="...”>
1233 ...
1234 </xenc:EncryptedKey>
1235 </wst:RequestedProofToken>
1236 </wst:RequestSecurityTokenResponse>
1237 </wst:RequestSecurityTokenResponseCollection>

12384.5 Returning Security Tokens in Headers

1239In certain situations it is useful to issue one or more security tokens as part of a protocol other than
1240RST/RSTR. This typically requires that the tokens be passed in a SOAP header. The tokens present in
1241that element can then be referenced from elsewhere in the message. This section defines a specific
1242header element, whose type is the same as that of the <wst:RequestSecurityTokenCollection>
1243element (see Section 4.3), that can be used to carry issued tokens (and associated proof tokens,
1244references etc.) in a message.
1245 <wst:IssuedTokens xmlns:wst="...”>
1246 <wst:RequestSecurityTokenResponse>
1247 ...
1248 </wst:RequestSecurityTokenResponse>+
1249 </wst:IssuedTokens>

1250
1251The following describes the attributes and elements listed in the schema overview above:
1252/wst:IssuedTokens
1253 This header element carries one or more issued security tokens. This element schema is defined
1254 using the RequestSecurityTokenResponse schema type.
1255/wst:IssuedTokens/wst:RequestSecurityTokenResponse
1256 This element MUST appear at least once. Its meaning and semantics are as defined in Section 4.2.

94ws-trust-1.4-os 2 February 2009

95Copyright © OASIS® 1993–2009. All Rights Reserved. Page 32 of 88
1257/wst:IssuedTokens/{any}
1258 This is an extensibility mechanism to allow additional elements, based on schemas, to be added.
1259/wst:IssuedTokens/@{any}
1260 This is an extensibility mechanism to allow additional attributes, based on schemas, to be added.
1261
1262There MAY be multiple instances of the <wst:IssuedTokens> header in a given message. Such
1263instances MAY be targeted at the same actor/role. Intermediaries MAY add additional
1264<wst:IssuedTokens> header elements to a message. Intermediaries SHOULD NOT modify any
1265<wst:IssuedTokens> header already present in a message.
1266
1267It is RECOMMENDED that the <wst:IssuedTokens> header be signed to protect the integrity of the
1268issued tokens and of the issuance itself. If confidentiality protection of the <wst:IssuedTokens> header is
1269REQUIRED then the entire header MUST be encrypted using the <wsse11:EncryptedHeader> construct.
1270This helps facilitate re-issuance by the receiving party as that party can re-encrypt the entire header for
1271another party rather than having to extract and re-encrypt portions of the header.
1272
1273The following example illustrates a response that includes multiple <wst:IssuedTokens> headers.
1274 <?xml version="1.0" encoding="utf-8"?>
1275 <S11:Envelope xmlns:S11="..." xmlns:wst="..." xmlns:wsp="..." xmlns:ds="..."
1276 xmlns:x="...">
1277 <S11:Header>
1278 <wst:IssuedTokens>
1279 <wst:RequestSecurityTokenResponse>
1280 <wsp:AppliesTo>
1281 <x:SomeContext1 />
1282 </wsp:AppliesTo>
1283 <wst:RequestedSecurityToken>
1284 ...
1285 </wst:RequestedSecurityToken>
1286 ...
1287 </wst:RequestSecurityTokenResponse>
1288 <wst:RequestSecurityTokenResponse>
1289 <wsp:AppliesTo>
1290 <x:SomeContext1 />
1291 </wsp:AppliesTo>
1292 <wst:RequestedSecurityToken>
1293 ...
1294 </wst:RequestedSecurityToken>
1295 ...
1296 </wst:RequestSecurityTokenResponse>
1297 </wst:IssuedTokens>
1298 <wst:IssuedTokens S11:role="http://example.org/somerole" >
1299 <wst:RequestSecurityTokenResponse>
1300 <wsp:AppliesTo>
1301 <x:SomeContext2 />
1302 </wsp:AppliesTo>
1303 <wst:RequestedSecurityToken>
1304 ...
1305 </wst:RequestedSecurityToken>
1306 ...
1307 </wst:RequestSecurityTokenResponse>
1308 </wst:IssuedTokens>
1309 </S11:Header>
1310 <S11:Body>

97ws-trust-1.4-os 2 February 2009

98Copyright © OASIS® 1993–2009. All Rights Reserved. Page 33 of 88
1311 ...
1312 </S11:Body>
1313 </S11:Envelope>

100ws-trust-1.4-os 2 February 2009

101Copyright © OASIS® 1993–2009. All Rights Reserved. Page 34 of 88
13145 Renewal Binding
1315Using the token request framework, this section defines bindings for requesting security tokens to be
1316renewed:
1317 Renew – A previously issued token with expiration is presented (and possibly proven) and the
1318 same token is returned with new expiration semantics.
1319
1320For this binding, the following actions are defined to enable specific processing context to be conveyed to
1321the recipient:
1322 http://docs.oasis-open.org/ws-sx/ws-trust/200512/RST/Renew
1323 http://docs.oasis-open.org/ws-sx/ws-trust/200512/RSTR/Renew
1324 http://docs.oasis-open.org/ws-sx/ws-trust/200512/RSTR/RenewFinal

1325For this binding, the <wst:RequestType> element uses the following URI:
1326 http://docs.oasis-open.org/ws-sx/ws-trust/200512/Renew

1327For this binding the token to be renewed is identified in the <wst:RenewTarget> element and the
1328OPTIONAL <wst:Lifetime> element MAY be specified to request a specified renewal duration.
1329
1330Other extensions MAY be specified in the request (and the response), but the key semantics (size, type,
1331algorithms, scope, etc.) MUST NOT be altered during renewal. Token services MAY use renewal as an
1332opportunity to rekey, so the renewal responses MAY include a new proof-of-possession token as well as
1333entropy and key exchange elements.
1334
1335The request MUST prove authorized use of the token being renewed unless the recipient trusts the
1336requestor to make third-party renewal requests. In such cases, the third-party requestor MUST prove its
1337identity to the issuer so that appropriate authorization occurs.
1338
1339The original proof information SHOULD be proven during renewal.
1340
1341The renewal binding allows the use of exchanges during the renewal process. Subsequent profiles MAY
1342define restriction around the usage of exchanges.
1343
1344During renewal, all key bearing tokens used in the renewal request MUST have an associated signature.
1345All non-key bearing tokens MUST be signed. Signature confirmation is RECOMMENDED on the renewal
1346response.
1347
1348The renewal binding also defines several extensions to the request and response elements. The syntax
1349for these extension elements is as follows (note that the base elements described above are included
1350here italicized for completeness):
1351 <wst:RequestSecurityToken xmlns:wst="...”>
1352 <wst:TokenType>...</wst:TokenType>
1353 <wst:RequestType>...</wst:RequestType>
1354 ...
1355 <wst:RenewTarget>...</wst:RenewTarget>

103ws-trust-1.4-os 2 February 2009

104Copyright © OASIS® 1993–2009. All Rights Reserved. Page 35 of 88
 1356 <wst:AllowPostdating/>
1357 <wst:Renewing Allow=”...” OK=”...”/>
1358 </wst:RequestSecurityToken>

1359/wst:RequestSecurityToken/wst:RenewTarget
1360 This REQUIRED element identifies the token being renewed. This MAY contain a
1361 <wsse:SecurityTokenReference> pointing at the token to be renewed or it MAY directly contain
1362 the token to be renewed.
1363/wst:RequestSecurityToken/wst:AllowPostdating
1364 This OPTIONAL element indicates that returned tokens SHOULD allow requests for postdated
1365 tokens. That is, this allows for tokens to be issued that are not immediately valid (e.g., a token
1366 that can be used the next day).
1367/wst:RequestSecurityToken/wst:Renewing
1368 This OPTIONAL element is used to specify renew semantics for types that support this operation.
1369/wst:RequestSecurityToken/wst:Renewing/@Allow
1370 This OPTIONAL Boolean attribute is used to request a renewable token. If not specified, the
1371 default value is true. A renewable token is one whose lifetime can be extended. This is done
1372 using a renewal request. The recipient MAY allow renewals without demonstration of authorized
1373 use of the token or they MAY fault.
1374/wst:RequestSecurityToken/wst:Renewing/@OK
1375 This OPTIONAL Boolean attribute is used to indicate that a renewable token is acceptable if the
1376 requested duration exceeds the limit of the issuance service. That is, if true then tokens can be
1377 renewed after their expiration. It should be noted that the token is NOT valid after expiration for
1378 any operation except renewal. The default for this attribute is false. It NOT RECOMMENDED to
1379 use this as it can leave you open to certain types of security attacks. Issuers MAY restrict the
1380 period after expiration during which time the token can be renewed. This window is governed by
1381 the issuer's policy.
1382The following example illustrates a request for a custom token that can be renewed.
1383 <wst:RequestSecurityToken xmlns:wst="...”>
1384 <wst:TokenType>
1385 http://example.org/mySpecialToken
1386 </wst:TokenType>
1387 <wst:RequestType>
1388 http://docs.oasis-open.org/ws-sx/ws-trust/200512/Issue
1389 </wst:RequestType>
1390 <wst:Renewing/>
1391 </wst:RequestSecurityToken>

1392
1393The following example illustrates a subsequent renewal request and response (note that for brevity only
1394the request and response are illustrated). Note that the response includes an indication of the lifetime of
1395the renewed token.
1396 <wst:RequestSecurityToken xmlns:wst="...”>
1397 <wst:TokenType>
1398 http://example.org/mySpecialToken
1399 </wst:TokenType>
1400 <wst:RequestType>
1401 http://docs.oasis-open.org/ws-sx/ws-trust/200512/Renew
1402 </wst:RequestType>
1403 <wst:RenewTarget>
1404 ... reference to previously issued token ...
1405 </wst:RenewTarget>

106ws-trust-1.4-os 2 February 2009

107Copyright © OASIS® 1993–2009. All Rights Reserved. Page 36 of 88
1406 </wst:RequestSecurityToken>
1407
1408 <wst:RequestSecurityTokenResponse xmlns:wst="...”>
1409 <wst:TokenType>
1410 http://example.org/mySpecialToken
1411 </wst:TokenType>
1412 <wst:RequestedSecurityToken>...</wst:RequestedSecurityToken>
1413 <wst:Lifetime>...</wst:Lifetime>
1414 ...
1415 </wst:RequestSecurityTokenResponse>

109ws-trust-1.4-os 2 February 2009

110Copyright © OASIS® 1993–2009. All Rights Reserved. Page 37 of 88
14166 Cancel Binding
1417Using the token request framework, this section defines bindings for requesting security tokens to be
1418cancelled:
1419 Cancel – When a previously issued token is no longer needed, the Cancel binding can be used
1420 to cancel the token, terminating its use. After canceling a token at the issuer, a STS MUST not
1421 validate or renew the token. A STS MAY initiate the revocation of a token, however, revocation is
1422 out of scope of this specification and a client MUST NOT rely on it. If a client needs to ensure the
1423 validity of a token, it MUST validate the token at the issuer.
1424
1425For this binding, the following actions are defined to enable specific processing context to be conveyed to
1426the recipient:
1427 http://docs.oasis-open.org/ws-sx/ws-trust/200512/RST/Cancel
1428 http://docs.oasis-open.org/ws-sx/ws-trust/200512/RSTR/Cancel
1429 http://docs.oasis-open.org/ws-sx/ws-trust/200512/RSTR/CancelFinal

1430For this binding, the <wst:RequestType> element uses the following URI:
1431 http://docs.oasis-open.org/ws-sx/ws-trust/200512/Cancel

1432Extensions MAY be specified in the request (and the response), but the semantics are not defined by this
1433binding.
1434
1435The request MUST prove authorized use of the token being cancelled unless the recipient trusts the
1436requestor to make third-party cancel requests. In such cases, the third-party requestor MUST prove its
1437identity to the issuer so that appropriate authorization occurs.
1438In a cancel request, all key bearing tokens specified MUST have an associated signature. All non-key
1439bearing tokens MUST be signed. Signature confirmation is RECOMMENDED on the closure response.
1440
1441A cancelled token is no longer valid for authentication and authorization usages.
1442On success a cancel response is returned. This is an RSTR message with the
1443<wst:RequestedTokenCancelled> element in the body. On failure, a Fault is raised. It should be
1444noted that the cancel RSTR is informational. That is, the security token is cancelled once the cancel
1445request is processed.
1446
1447The syntax of the request is as follows:
1448 <wst:RequestSecurityToken xmlns:wst="...”>
1449 <wst:RequestType>...</wst:RequestType>
1450 ...
1451 <wst:CancelTarget>...</wst:CancelTarget>
1452 </wst:RequestSecurityToken>

1453/wst:RequestSecurityToken/wst:CancelTarget
1454 This REQUIRED element identifies the token being cancelled. Typically this contains a
1455 <wsse:SecurityTokenReference> pointing at the token, but it could also carry the token
1456 directly.
1457The following example illustrates a request to cancel a custom token.

112ws-trust-1.4-os 2 February 2009

113Copyright © OASIS® 1993–2009. All Rights Reserved. Page 38 of 88
 1458 <S11:Envelope xmlns:S11="..." xmlns:wst="..." xmlns:wsse="...">
1459 <S11:Header>
1460 <wsse:Security>
1461 ...
1462 </wsse:Security>
1463 </S11:Header>
1464 <S11:Body>
1465 <wst:RequestSecurityToken>
1466 <wst:RequestType>
1467 http://docs.oasis-open.org/ws-sx/ws-trust/200512/Cancel
1468 </wst:RequestType>
1469 <wst:CancelTarget>
1470 ...
1471 </wst:CancelTarget>
1472 </wst:RequestSecurityToken>
1473 </S11:Body>
1474 </S11:Envelope>

1475The following example illustrates a response to cancel a custom token.

1476 <S11:Envelope xmlns:S11="..." xmlns:wst="..." xmlns:wsse="...">
1477 <S11:Header>
1478 <wsse:Security>
1479 ...
1480 </wsse:Security>
1481 </S11:Header>
1482 <S11:Body>
1483 <wst:RequestSecurityTokenResponse>
1484 <wst:RequestedTokenCancelled/>
1485 </wst:RequestSecurityTokenResponse>
1486 </S11:Body>
1487 </S11:Envelope>

14886.1 STS-initiated Cancel Binding

1489Using the token request framework, this section defines an OPTIONAL binding for requesting security
1490tokens to be cancelled by the STS:
1491 STS-initiated Cancel – When a previously issued token becomes invalid on the STS, the STS-
1492 initiated Cancel binding can be used to cancel the token, terminating its use. After canceling a
1493 token, a STS MUST not validate or renew the token. This binding can be only used when STS
1494 can send one-way messages to the original token requestor.
1495
1496For this binding, the following actions are defined to enable specific processing context to be conveyed to
1497the recipient:
1498 http://docs.oasis-open.org/ws-sx/ws-trust/200512/RST/STSCancel

1499For this binding, the <wst:RequestType> element uses the following URI:
1500 http://docs.oasis-open.org/ws-sx/ws-trust/200512/STSCancel

1501Extensions MAY be specified in the request, but the semantics are not defined by this binding.
1502
1503The request MUST prove authorized use of the token being cancelled unless the recipient trusts the
1504requestor to make third-party cancel requests. In such cases, the third-party requestor MUST prove its
1505identity to the issuer so that appropriate authorization occurs.
1506In a cancel request, all key bearing tokens specified MUST have an associated signature. All non-key
1507bearing tokens MUST be signed.
115ws-trust-1.4-os 2 February 2009
116Copyright © OASIS® 1993–2009. All Rights Reserved. Page 39 of 88
1508
1509A cancelled token is no longer valid for authentication and authorization usages.
1510
1511The mechanism to determine the availability of STS-initiated Cancel binding on the STS is out of scope of
1512this specification. Similarly, how the client communicates its endpoint address to the STS so that it can
1513send the STSCancel messages to the client is out of scope of this specification. This functionality is
1514implementation specific and can be solved by different mechanisms that are not in scope for this
1515specification.
1516
1517This is a one-way operation, no response is returned from the recipient of the message.
1518
1519The syntax of the request is as follows:
1520 <wst:RequestSecurityToken xmlns:wst="...”>
1521 <wst:RequestType>...</wst:RequestType>
1522 ...
1523 <wst:CancelTarget>...</wst:CancelTarget>
1524 </wst:RequestSecurityToken>

1525/wst:RequestSecurityToken/wst:CancelTarget
1526 This REQUIRED element identifies the token being cancelled. Typically this contains a
1527 <wsse:SecurityTokenReference> pointing at the token, but it could also carry the token
1528 directly.
1529The following example illustrates a request to cancel a custom token.
1530 <?xml version="1.0" encoding="utf-8"?>
1531 <S11:Envelope xmlns:S11="..." xmlns:wst="..." xmlns:wsse="...">
1532 <S11:Header>
1533 <wsse:Security>
1534 ...
1535 </wsse:Security>
1536 </S11:Header>
1537 <S11:Body>
1538 <wst:RequestSecurityToken>
1539 <wst:RequestType>
1540 http://docs.oasis-open.org/ws-sx/ws-trust/200512/STSCancel
1541 </wst:RequestType>
1542 <wst:CancelTarget>
1543 ...
1544 </wst:CancelTarget>
1545 </wst:RequestSecurityToken>
1546 </S11:Body>
1547 </S11:Envelope>

118ws-trust-1.4-os 2 February 2009

119Copyright © OASIS® 1993–2009. All Rights Reserved. Page 40 of 88
15487 Validation Binding
1549Using the token request framework, this section defines bindings for requesting security tokens to be
1550validated:
1551 Validate – The validity of the specified security token is evaluated and a result is returned. The
1552 result MAY be a status, a new token, or both.
1553
1554It should be noted that for this binding, a SOAP Envelope MAY be specified as a "security token" if the
1555requestor desires the envelope to be validated. In such cases the recipient SHOULD understand how to
1556process a SOAP envelope and adhere to SOAP processing semantics (e.g., mustUnderstand) of the
1557version of SOAP used in the envelope. Otherwise, the recipient SHOULD fault.
1558For this binding, the following actions are defined to enable specific processing context to be conveyed to
1559the recipient:
1560 http://docs.oasis-open.org/ws-sx/ws-trust/200512/RST/Validate
1561 http://docs.oasis-open.org/ws-sx/ws-trust/200512/RSTR/Validate
1562 http://docs.oasis-open.org/ws-sx/ws-trust/200512/RSTR/ValidateFinal

1563
1564For this binding, the <wst:RequestType> element contains the following URI:
1565 http://docs.oasis-open.org/ws-sx/ws-trust/200512/Validate

1566
1567The request provides a token upon which the request is based and OPTIONAL tokens. As well, the
1568OPTIONAL <wst:TokenType> element in the request can indicate desired type response token. This
1569MAY be any supported token type or it MAY be the following URI indicating that only status is desired:
1570 http://docs.oasis-open.org/ws-sx/ws-trust/200512/RSTR/Status

1571
1572For some use cases a status token is returned indicating the success or failure of the validation. In other
1573cases a security token MAY be returned and used for authorization. This binding assumes that the
1574validation requestor and provider are known to each other and that the general issuance parameters
1575beyond requesting a token type, which is OPTIONAL, are not needed (note that other bindings and
1576profiles could define different semantics).
1577
1578For this binding an applicability scope (e.g., <wsp:AppliesTo>) need not be specified. It is assumed
1579that the applicability of the validation response relates to the provided information (e.g. security token) as
1580understood by the issuing service.
1581
1582The validation binding does not allow the use of exchanges.
1583
1584The RSTR for this binding carries the following element even if a token is returned (note that the base
1585elements described above are included here italicized for completeness):
1586 <wst:RequestSecurityToken xmlns:wst="...”>
1587 <wst:TokenType>...</wst:TokenType>
1588 <wst:RequestType>...</wst:RequestType>

121ws-trust-1.4-os 2 February 2009

122Copyright © OASIS® 1993–2009. All Rights Reserved. Page 41 of 88
 1589 <wst:ValidateTarget>... </wst:ValidateTarget>
1590 ...
1591 </wst:RequestSecurityToken>

1592
1593 <wst:RequestSecurityTokenResponse xmlns:wst="..." >
1594 <wst:TokenType>...</wst:TokenType>
1595 <wst:RequestedSecurityToken>...</wst:RequestedSecurityToken>
1596 ...
1597 <wst:Status>
1598 <wst:Code>...</wst:Code>
1599 <wst:Reason>...</wst:Reason>
1600 </wst:Status>
1601 </wst:RequestSecurityTokenResponse>

1602
1603/wst:RequestSecurityToken/wst:ValidateTarget
1604 This REQUIRED element identifies the token being validated. Typically this contains a
1605 <wsse:SecurityTokenReference> pointing at the token, but could also carry the token
1606 directly.
1607/wst:RequestSecurityTokenResponse/wst:Status
1608 When a validation request is made, this element MUST be in the response. The code value
1609 indicates the results of the validation in a machine-readable form. The accompanying text
1610 element allows for human textual display.
1611/wst:RequestSecurityTokenResponse/wst:Status/wst:Code
1612 This REQUIRED URI value provides a machine-readable status code. The following URIs are
1613 predefined, but others MAY be used.

URI Description
http://docs.oasis-open.org/ws-sx/ws-trust/200512/status/valid The Trust service
successfully validated the
input
http://docs.oasis-open.org/ws-sx/ws-trust/200512/status/invalid The Trust service did not
successfully validate the
input
1614/wst:RequestSecurityTokenResponse/wst:Status/wst:Reason
1615 This OPTIONAL string provides human-readable text relating to the status code.
1616
1617The following illustrates the syntax of a validation request and response. In this example no token is
1618requested, just a status.
1619 <wst:RequestSecurityToken xmlns:wst="...”>
1620 <wst:TokenType>
1621 http://docs.oasis-open.org/ws-sx/ws-trust/200512/RSTR/Status
1622 </wst:TokenType>
1623 <wst:RequestType>
1624 http://docs.oasis-open.org/ws-sx/ws-trust/200512/Validate
1625 </wst:RequestType>
1626 </wst:RequestSecurityToken>

1627
1628 <wst:RequestSecurityTokenResponse xmlns:wst="...”>

124ws-trust-1.4-os 2 February 2009

125Copyright © OASIS® 1993–2009. All Rights Reserved. Page 42 of 88
 1629 <wst:TokenType>
1630 http://docs.oasis-open.org/ws-sx/ws-trust/200512/RSTR/Status
1631 </wst:TokenType>
1632 <wst:Status>
1633 <wst:Code>
1634 http://docs.oasis-open.org/ws-sx/ws-trust/200512/status/valid
1635 </wst:Code>
1636 </wst:Status>
1637 ...
1638 </wst:RequestSecurityTokenResponse>

1639The following illustrates the syntax of a validation request and response. In this example a custom token
1640is requested indicating authorized rights in addition to the status.
1641 <wst:RequestSecurityToken xmlns:wst="...”>
1642 <wst:TokenType>
1643 http://example.org/mySpecialToken
1644 </wst:TokenType>
1645 <wst:RequestType>
1646 http://docs.oasis-open.org/ws-sx/ws-trust/200512/Validate
1647 </wst:RequestType>
1648 </wst:RequestSecurityToken>

1649
1650 <wst:RequestSecurityTokenResponse xmlns:wst="...”>
1651 <wst:TokenType>
1652 http://example.org/mySpecialToken
1653 </wst:TokenType>
1654 <wst:Status>
1655 <wst:Code>
1656 http://docs.oasis-open.org/ws-sx/ws-trust/200512/status/valid
1657 </wst:Code>
1658 </wst:Status>
1659 <wst:RequestedSecurityToken>...</wst:RequestedSecurityToken>
1660 ...
1661 </wst:RequestSecurityTokenResponse>

127ws-trust-1.4-os 2 February 2009

128Copyright © OASIS® 1993–2009. All Rights Reserved. Page 43 of 88
16628 Negotiation and Challenge Extensions
1663The general security token service framework defined above allows for a simple request and response for
1664security tokens (possibly asynchronous). However, there are many scenarios where a set of exchanges
1665between the parties is REQUIRED prior to returning (e.g., issuing) a security token. This section
1666describes the extensions to the base WS-Trust mechanisms to enable exchanges for negotiation and
1667challenges.
1668
1669There are potentially different forms of exchanges, but one specific form, called "challenges", provides
1670mechanisms in addition to those described in [WS-Security] for authentication. This section describes
1671how general exchanges are issued and responded to within this framework. Other types of exchanges
1672include, but are not limited to, negotiation, tunneling of hardware-based processing, and tunneling of
1673legacy protocols.
1674
1675The process is straightforward (illustrated here using a challenge):
1676

1677
1678 1. A requestor sends, for example, a <wst:RequestSecurityToken> message with a
1679 timestamp.
1680 2. The recipient does not trust the timestamp and issues a
1681 <wst:RequestSecurityTokenResponse> message with an embedded challenge.
1682 3. The requestor sends a <wst:RequestSecurityTokenReponse> message with an answer to
1683 the challenge.
1684 4. The recipient issues a <wst:RequestSecurityTokenResponseCollection> message with
1685 the issued security token and OPTIONAL proof-of-possession token.
1686
1687It should be noted that the requestor might challenge the recipient in either step 1 or step 3. In which
1688case, step 2 or step 4 contains an answer to the initiator's challenge. Similarly, it is possible that steps 2
1689and 3 could iterate multiple times before the process completes (step 4).
1690

130ws-trust-1.4-os 2 February 2009

131Copyright © OASIS® 1993–2009. All Rights Reserved. Page 44 of 88
1691The two services can use [WS-SecurityPolicy] to state their requirements and preferences for security
1692tokens and encryption and signing algorithms (general policy intersection). This section defines
1693mechanisms for legacy and more sophisticated types of negotiations.

16948.1 Negotiation and Challenge Framework

1695The general mechanisms defined for requesting and returning security tokens are extensible. This
1696section describes the general model for extending these to support negotiations and challenges.
1697
1698The exchange model is as follows:
1699 1. A request is initiated with a <wst:RequestSecurityToken> that identifies the details of the
1700 request (and MAY contain initial negotiation/challenge information)
1701 2. A response is returned with a <wst:RequestSecurityTokenResponse> that contains
1702 additional negotiation/challenge information. Optionally, this MAY return token information in the
1703 form of a <wst:RequestSecurityTokenResponseCollection> (if the exchange is two legs
1704 long).
1705 3. If the exchange is not complete, the requestor uses a
1706 <wst:RequestSecurityTokenResponse> that contains additional negotiation/challenge
1707 information.
1708 4. The process repeats at step 2 until the negotiation/challenge is complete (a token is returned or a
1709 Fault occurs). In the case where token information is returned in the final leg, it is returned in the
1710 form of a <wst:RequestSecurityTokenResponseCollection>.
1711
1712The negotiation/challenge information is passed in binding/profile-specific elements that are placed inside
1713of the <wst:RequestSecurityToken> and <wst:RequestSecurityTokenResponse> elements.
1714
1715It is RECOMMENDED that at least the <wsu:Timestamp> element be included in messages (as per
1716[WS-Security]) as a way to ensure freshness of the messages in the exchange. Other types of
1717challenges MAY also be included. For example, a <wsp:Policy> element may be used to negotiate
1718desired policy behaviors of both parties. Multiple challenges and responses MAY be included.

17198.2 Signature Challenges

1720Exchange requests are issued by including an element that describes the exchange (e.g. challenge) and
1721responses contain an element describing the response. For example, signature challenges are
1722processed using the <wst:SignChallenge> element. The response is returned in a
1723<wst:SignChallengeResponse> element. Both the challenge and the response elements are
1724specified within the <wst:RequestSecurityTokenResponse> element. Some forms of negotiation
1725MAY specify challenges along with responses to challenges from the other party. It should be noted that
1726the requestor MAY provide exchange information (e.g. a challenge) to the recipient in the initial request.
1727Consequently, these elements are also allowed within a <wst:RequestSecurityToken> element.
1728
1729The syntax of these elements is as follows:
1730 <wst:SignChallenge xmlns:wst="...”>
1731 <wst:Challenge ...>...</wst:Challenge>
1732 </wst:SignChallenge>

1733

133ws-trust-1.4-os 2 February 2009

134Copyright © OASIS® 1993–2009. All Rights Reserved. Page 45 of 88
 1734 <wst:SignChallengeResponse xmlns:wst="...”>
1735 <wst:Challenge ...>...</wst:Challenge>
1736 </wst:SignChallengeResponse>

1737
1738The following describes the attributes and tags listed in the schema above:
1739.../wst:SignChallenge
1740 This OPTIONAL element describes a challenge that requires the other party to sign a specified
1741 set of information.
1742.../wst:SignChallenge/wst:Challenge
1743 This REQUIRED string element describes the value to be signed. In order to prevent certain
1744 types of attacks (such as man-in-the-middle), it is strongly RECOMMENDED that the challenge
1745 be bound to the negotiation. For example, the challenge SHOULD track (such as using a digest
1746 of) any relevant data exchanged such as policies, tokens, replay protection, etc. As well, if the
1747 challenge is happening over a secured channel, a reference to the channel SHOULD also be
1748 included. Furthermore, the recipient of a challenge SHOULD verify that the data tracked
1749 (digested) matches their view of the data exchanged. The exact algorithm MAY be defined in
1750 profiles or agreed to by the parties.
1751.../SignChallenge/{any}
1752 This is an extensibility mechanism to allow additional negotiation types to be used.
1753.../wst:SignChallenge/@{any}
1754 This is an extensibility mechanism to allow additional attributes, based on schemas, to be added
1755 to the element.
1756.../wst:SignChallengeResponse
1757 This OPTIONAL element describes a response to a challenge that requires the signing of a
1758 specified set of information.
1759.../wst:SignChallengeResponse/wst:Challenge
1760 If a challenge was issued, the response MUST contain the challenge element exactly as
1761 received. As well, while the RSTR response SHOULD always be signed, if a challenge was
1762 issued, the RSTR MUST be signed (and the signature coupled with the message to prevent
1763 replay).
1764.../wst:SignChallengeResponse/{any}
1765 This is an extensibility mechanism to allow additional negotiation types to be used.
1766.../wst:SignChallengeResponse/@{any}
1767 This is an extensibility mechanism to allow additional attributes, based on schemas, to be added
1768 to the element.

17698.3 User Interaction Challenge

1770User interaction challenge requests are issued by including the <InteractiveChallenge> element. The
1771response is returned in a <InteractiveChallengeResponse> element. Both the challenge and response
1772elements are specified within the <wst:RequestSecurityTokenResponse> element. In some instances, the
1773requestor may issue a challenge to the recipient or provide a response to an anticipated challenge from
1774the recipient in the initial request. Consequently, these elements are also allowed within a
1775<wst:RequestSecurityToken> element. The challenge/response exchange between client and server
1776MAY be iterated over multiple legs before a final response is issued.

136ws-trust-1.4-os 2 February 2009

137Copyright © OASIS® 1993–2009. All Rights Reserved. Page 46 of 88
1777Implementations SHOULD take into account the possibility that messages in either direction may be lost
1778or duplicated. In the absence of a lower level protocol guaranteeing delivery of every message in order
1779and exactly once, which retains the ordering of requests and responses traveling in opposite directions,
1780implementations SHOULD observe the following procedures:
1781The STS SHOULD:
17821. Never send a new request while an existing request is pending,
17832. Timeout requests and retransmit them.
17843. Silently discard responses when no request is pending.
1785
1786The service consumer MAY:
17871. Respond to a repeated request with the same information
17882. Retain user input until the Challenge Interation is complete in case it is necessary to repeat the
1789 response.
1790Note that the xml:lang attribute may be used where allowed via attribute extensibility to specify a
1791language of localized elements and attributes using the language codes specified in [RFC 3066].

17928.3.1 Challenge Format

1793The syntax of the user interaction challenge element is as follows:
1794 <wst14:InteractiveChallenge xmlns:wst14="..." ...>
1795 <wst14:Title ...> xs:string </wst14:Title> ?
1796 <wst14:TextChallenge RefId="xs:anyURI" Label="xs:string"?
1797 MaxLen="xs:int"? HideText="xs:boolean"? ...>
1798 <wst14:Image MimeType="xs:string"> xs:base64Binary </wst14:Image> ?
1799 </wst14:TextChallenge> *
1800 <wst14:ChoiceChallenge RefId="xs:anyURI" Label="xs:string"?
1801 ExactlyOne="xs:boolean"? ...>
1802 <wst14:Choice RefId="xs:anyURI" Label="xs:string"? ...>
1803 <wst14:Image MimeType="xs:string"> xs:base64Binary </wst14:Image> ?
1804 </wst14:Choice> +
1805 </wst14:ChoiceChallenge> *
1806 < wst14:ContextData RefId="xs:anyURI"> xs:any </wst14:ContextData> *
1807 ...
1808 </wst14:InteractiveChallenge>

1809The following describes the attributes and elements listed in the schema outlined above:
1810
1811.../wst14:InteractiveChallenge
1812 A container element for a challenge that requires interactive user input.
1813.../wst14:InteractiveChallenge/wst14:Title
1814 An OPTIONAL element that specifies an overall title text to be displayed to the user (e.g. a title
1815 describing the purpose or nature of the challenge). How the preferred language of the requestor
1816 is communicated to the STS is left up to implementations.
1817.../wst14:InteractiveChallenge/wst14:TextChallenge
1818 An OPTIONAL element that specifies a challenge that requires textual input from the user.
1819.../wst14:InteractiveChallenge/wst14:TextChallenge/@RefId
1820 A REQUIRED attribute that specifies a reference identifier for this challenge element which is
1821 used to correlate the corresponding element in the response to the challenge.

139ws-trust-1.4-os 2 February 2009

140Copyright © OASIS® 1993–2009. All Rights Reserved. Page 47 of 88
1822.../wst14:InteractiveChallenge/wst14:TextChallenge/@MaxLen
1823 An OPTIONAL attribute that specifies the maximum length of the text string that is sent as the
1824 response to this text challenge. This value serves as a hint for the user interface software at the
1825 requestor which manifests the end-user experience for this challenge.
1826.../wst14:InteractiveChallenge/wst14:TextChallenge/@HideText
1827 An OPTIONAL attribute that specifies that the response to this text challenge MUST receive
1828 treatment as hidden text in any user interface. For example, the text entry may be displayed as a
1829 series of asterisks in the user interface. This attribute serves as a hint for the user interface
1830 software at the requestor which manifests the end-user experience for this challenge.
1831.../wst14:InteractiveChallenge/wst14:TextChallenge/@Label
1832 An OPTIONAL attribute that specifies a label for the text challenge item (e.g. a label for a text
1833 entry field) which will be shown to the user. How the preferred language of the requestor is
1834 communicated to the STS is left up to implementations.
1835.../wst14:InteractiveChallenge/wst14:TextChallenge/Image
1836 An OPTIONAL element that contains a base64 encoded inline image specific to the text
1837 challenge item to be shown to the user (e.g. an image that the user must see to respond
1838 successfully to the challenge). The image presented is intended as an additional label to a
1839 challenge element which could be CAPTCHA, selection of a previously established image secret
1840 or any other means by which images can be used to challenge a user to interact in a way to
1841 satisfy a challenge.
1842.../wst14:InteractiveChallenge/wst14:TextChallenge/Image/@MimeType
1843 A REQUIRED attribute that specifies a MIME type (e.g., image/gif, image/jpg) indicating the
1844 format of the image.
1845.../wst14:InteractiveChallenge/wst14:ChoiceChallenge
1846 An OPTIONAL element that specifies a challenge that requires a choice among multiple items by
1847 the user.
1848.../wst14:InteractiveChallenge/wst14:ChoiceChallenge/@RefId
1849 A REQUIRED attribute that specifies a reference identifier for this challenge element which is
1850 used to correlate the corresponding element in the response to the challenge.
1851.../wst14:InteractiveChallenge/wst14:ChoiceChallenge/@Label
1852 An OPTIONAL attribute that specifies a title label for the choice challenge item (e.g., a text
1853 header describing the list of choices as a whole) which will be shown to the user. How the
1854 preferred language of the requestor is communicated to the STS is left up to implementations.
1855.../wst14:InteractiveChallenge/wst14:ChoiceChallenge/@ExactlyOne
1856 An OPTIONAL attribute that specifies if exactly once choice must be selected by the user from
1857 among the child element choices. The absence of this attribute implies the value “false” which
1858 means multiple choices can be selected.
1859.../wst14:InteractiveChallenge/wst14:ChoiceChallenge/wst14:Choice
1860 A REQUIRED element that specifies a single choice item within the choice challenge.
1861.../wst14:InteractiveChallenge/wst14:ChoiceChallenge/wst14:Choice/@RefId
1862 A REQUIRED attribute that specifies a reference identifier for this specific choice item which is
1863 used to correlate the corresponding element in the response to the challenge.
1864.../wst14:InteractiveChallenge/wst14:ChoiceChallenge/wst14:Choice/@Label

142ws-trust-1.4-os 2 February 2009

143Copyright © OASIS® 1993–2009. All Rights Reserved. Page 48 of 88
1865 An OPTIONAL attribute that specifies a text label for the choice item (e.g., text describing the
1866 individual choice) which will be shown to the user. How the preferred language of the requestor is
1867 communicated to the STS is left up to implementations.
1868.../wst14:InteractiveChallenge/wst14:ChoiceChallenge/wst14:Choice/wst14:Image
1869 An OPTIONAL element that contains a base64 encoded inline image specific to the choice item
1870 to be shown to the user (e.g. an image that the user must see to respond successfully to the
1871 challenge). The image presented is intended as an additional label to a challenge element which
1872 could be CAPTCHA, selection of a previously established image secret or any other means by
1873 which images can be used to challenge a user to interact in a way to satisfy a challenge.
1874.../wst14:InteractiveChallenge/wst14:ChoiceChallenge/wst14:Choice/wst14:Image/@MimeType
1875 A REQUIRED attribute that specifies a MIME type (e.g., image/gif, image/jpg) indicating the
1876 format of the image.
1877.../wst14:InteractiveChallenge/wst14:ContextData
1878 An OPTIONAL element that specifies a value that MUST be reflected back in the response to the
1879 challenge (e.g., cookie). The element may contain any value. The actual content is opaque to the
1880 requestor; it is not required to understand its structure or semantics. This can be used by an STS,
1881 for instance, to store information between the challenge/response exchanges that would
1882 otherwise be lost if the STS were to remain stateless.
1883.../wst14:InteractiveChallenge/wst14:ContextData/@RefId
1884 A REQUIRED attribute that specifies a reference identifier for this context element which is used
1885 to correlate the corresponding element in the response to the challenge.
1886.../wst14:InteractiveChallenge/{any}
1887 This is an extensibility mechanism to allow additional elements to be specified.
1888.../wst14:InteractiveChallenge/@{any}
1889 This is an extensibility mechanism to allow additional attributes to be specified.
1890
1891The syntax of the user interaction challenge response element is as follows:
1892 <wst14:InteractiveChallengeResponse xmlns:wst14="..." ...>
1893 <wst14:TextChallengeResponse RefId="xs:anyURI" ...>
1894 xs:string
1895 </wst14:TextChallengeResponse> *
1896 <wst14:ChoiceChallengeResponse RefId="xs:anyURI"> *
1897 <wst14:ChoiceSelected RefId="xs:anyURI" /> *
1898 </wst14:ChoiceChallengeResponse>
1899 <wst14:ContextData RefId="xs:anyURI"> xs:any </wst14:ContextData> *
1900 ...
1901 </wst14:InteractiveChallengeResponse>

1902The following describes the attributes and elements listed in the schema outlined above:
1903
1904.../wst14:InteractiveChallengeResponse
1905 A container element for the response to a challenge that requires interactive user input.
1906.../wst14:InteractiveChallengeResponse/wst14:TextChallengeResponse
1907 This element value contains the user input as the response to the original text challenge issued.
1908.../wst14:InteractiveChallengeResponse/wst14:TextChallengeResponse/@RefId
1909 A required attribute that specifies the identifier for the text challenge element in the original
1910 challenge which can be used for correlation.
145ws-trust-1.4-os 2 February 2009
146Copyright © OASIS® 1993–2009. All Rights Reserved. Page 49 of 88
1911.../wst14:InteractiveChallengeResponse/wst14:ChoiceChallengeResponse
1912 A container element for the response to a choice challenge.
1913.../wst14:InteractiveChallengeResponse/wst14:ChoiceChallengeResponse/@RefId
1914 A required attribute that specifies the reference identifier for the choice challenge element in the
1915 original challenge which can be used for correlation.
1916.../wst14:InteractiveChallengeResponse/wst14:ChoiceChallengeResponse/wst14:ChoiceSelected
1917 A required element that specifies a choice item selected by the user from the choice challenge.
1918.../wst14:InteractiveChallengeResponse/wst14:ChoiceChallengeResponse/wst14:ChoiceSelected/@RefI
1919d
1920 A required attribute that specifies the reference identifier for the choice item in the original choice
1921 challenge which can be used for correlation.
1922.../wst14:InteractiveChallengeResponse/wst14:ContextData
1923 An optional element that carries a context data item from the original challenge that is simply
1924 reflected back.
1925.../wst14:InteractiveChallengeResponse/wst14:ContextData/@RefId
1926 A required attribute that specifies the reference identifier for the context data element in the
1927 original challenge which can be used for correlation.
1928.../wst14:InteractiveChallengeResponse/{any}
1929 This is an extensibility mechanism to allow additional elements to be specified.
1930.../wst14:InteractiveChallengeResponse/@{any}
1931 This is an extensibility mechanism to allow additional attributes to be specified.
1932In order to prevent certain types of attacks, such as man-in-the-middle or replay of response, the
1933challenge SHOULD be bound to the response. For example, an STS may use the <ContextData>
1934element in the challenge to include a digest of any relevant replay protection data and verify that the
1935same data is reflected back by the requestor.
1936Text provided by the STS which is intended for display SHOULD NOT contain script, markup or other
1937unprintable characters. Image data provided by the STS SHOULD NOT contain imbedded commands or
1938other content except an image to be displayed.
1939Service consumers MUST ignore any script, markup or other unprintable characters when displaying text
1940sent by the STS. Service consumers MUST insure that image data does not contain imbedded
1941commands or other content before displaying the image.

19428.3.2 PIN and OTP Challenges

1943In some situations, some additional authentication step may be required, but the Consumer cannot
1944determine this in advance of making the request. Two common cases that require user interaction are:
1945  a challenge for a secret PIN,
1946  a challenge for a one-time-password (OTP).
1947
1948This challenge may be issued by an STS using the “text challenge” format within a user interaction
1949challenge specified in the section above. A requestor responds to the challenge with the PIN/OTP value
1950along with the corresponding @RefId attribute value for the text challenge which is used by the STS to
1951correlate the response to the original challenge. This pattern of exchange requires that the requestor must
1952receive the challenge first and thus learn the @RefId attribute value to include in the response.
1953

148ws-trust-1.4-os 2 February 2009

149Copyright © OASIS® 1993–2009. All Rights Reserved. Page 50 of 88
 1954There are cases where a requestor may know a priori that the STS challenges for a single PIN/OTP and,
1955as an optimization, provide the response to the anticipated challenge in the initial request. The following
1956distinguished URIs are defined for use as the value of the @RefId attribute of a
1957<TextChallengeResponse> element to represent PIN and OTP responses using the optimization pattern.
1958
1959 http://docs.oasis-open.org/ws-sx/ws-trust/200802/challenge/PIN
1960 http://docs.oasis-open.org/ws-sx/ws-trust/200802/challenge/OTP

1961
1962An STS may choose not to support the optimization pattern above for PIN/OTP response. In some cases,
1963an OTP challenge from the STS may include a dynamic random value that the requestor must feed into
1964the OTP generating module before an OTP response is computed. In such cases, the optimized response
1965pattern may not be usable.

19668.4 Binary Exchanges and Negotiations

1967Exchange requests MAY also utilize existing binary formats passed within the WS-Trust framework. A
1968generic mechanism is provided for this that includes a URI attribute to indicate the type of binary
1969exchange.
1970
1971The syntax of this element is as follows:
1972 <wst:BinaryExchange ValueType="..." EncodingType="..." xmlns:wst="...”>
1973 </wst:BinaryExchange>

1974The following describes the attributes and tags listed in the schema above (note that the ellipses below
1975indicate that this element MAY be placed in different containers. For this specification, these are limited
1976to <wst:RequestSecurityToken> and <wst:RequestSecurityTokenResponse>):
1977.../wst:BinaryExchange
1978 This OPTIONAL element is used for a security negotiation that involves exchanging binary blobs
1979 as part of an existing negotiation protocol. The contents of this element are blob-type-specific
1980 and are encoded using base64 (unless otherwise specified).
1981.../wst:BinaryExchange/@ValueType
1982 This REQUIRED attribute specifies a URI to identify the type of negotiation (and the value space
1983 of the blob – the element's contents).
1984.../wst:BinaryExchange/@EncodingType
1985 This REQUIRED attribute specifies a URI to identify the encoding format (if different from base64)
1986 of the negotiation blob. Refer to [WS-Security] for sample encoding format URIs.
1987.../wst:BinaryExchange/@{any}
1988 This is an extensibility mechanism to allow additional attributes, based on schemas, to be added
1989 to the element.
1990Some binary exchanges result in a shared state/context between the involved parties. It is
1991RECOMMENDED that at the conclusion of the exchange, a new token and proof-of-possession token be
1992returned. A common approach is to use the negotiated key as a "secure channel" mechanism to secure
1993the new token and proof-of-possession token.
1994For example, an exchange might establish a shared secret Sx that can then be used to sign the final
1995response and encrypt the proof-of-possession token.

151ws-trust-1.4-os 2 February 2009

152Copyright © OASIS® 1993–2009. All Rights Reserved. Page 51 of 88
19968.5 Key Exchange Tokens
1997In some cases it MAY be necessary to provide a key exchange token so that the other party (either
1998requestor or issuer) can provide entropy or key material as part of the exchange. Challenges MAY NOT
1999always provide a usable key as the signature may use a signing-only certificate.
2000
2001The section describes two OPTIONAL elements that can be included in RST and RSTR elements to
2002indicate that a Key Exchange Token (KET) is desired, or to provide a KET.
2003The syntax of these elements is as follows (Note that the ellipses below indicate that this element MAY be
2004placed in different containers. For this specification, these are limited to
2005<wst:RequestSecurityToken> and <wst:RequestSecurityTokenResponse>):
2006 <wst:RequestKET xmlns:wst="..." />

2007
2008 <wst:KeyExchangeToken xmlns:wst="...”>...</wst:KeyExchangeToken>

2009
2010The following describes the attributes and tags listed in the schema above:
2011.../wst:RequestKET
2012 This OPTIONAL element is used to indicate that the receiving party (either the original requestor
2013 or issuer) SHOULD provide a KET to the other party on the next leg of the exchange.
2014.../wst:KeyExchangeToken
2015 This OPTIONAL element is used to provide a key exchange token. The contents of this element
2016 either contain the security token to be used for key exchange or a reference to it.

20178.6 Custom Exchanges

2018Using the extensibility model described in this specification, any custom XML-based exchange can be
2019defined in a separate binding/profile document. In such cases elements are defined which are carried in
2020the RST and RSTR elements.
2021
2022It should be noted that it is NOT REQUIRED that exchange elements be symmetric. That is, a specific
2023exchange mechanism MAY use multiple elements at different times, depending on the state of the
2024exchange.

20258.7 Signature Challenge Example

2026Here is an example exchange involving a signature challenge. In this example, a service requests a
2027custom token using a X.509 certificate for authentication. The issuer uses the exchange mechanism to
2028challenge the requestor to sign a random value (to ensure message freshness). The requestor provides
2029a signature of the requested data and, once validated, the issuer then issues the requested token.
2030
2031The first message illustrates the initial request that is signed with the private key associated with the
2032requestor's X.509 certificate:
2033 <S11:Envelope xmlns:S11="..." xmlns:wsse="..."
2034 xmlns:wsu="..." xmlns:wst="...">
2035 <S11:Header>
2036 ...
2037 <wsse:Security>

154ws-trust-1.4-os 2 February 2009

155Copyright © OASIS® 1993–2009. All Rights Reserved. Page 52 of 88
 2038 <wsse:BinarySecurityToken
2039 wsu:Id="reqToken"
2040 ValueType="...X509v3">
2041 MIIEZzCCA9CgAwIBAgIQEmtJZc0...
2042 </wsse:BinarySecurityToken>
2043 <ds:Signature xmlns:ds="...">
2044 ...
2045 <ds:KeyInfo>
2046 <wsse:SecurityTokenReference>
2047 <wsse:Reference URI="#reqToken"/>
2048 </wsse:SecurityTokenReference>
2049 </ds:KeyInfo>
2050 </ds:Signature>
2051 </wsse:Security>
2052 ...
2053 </S11:Header>
2054 <S11:Body>
2055 <wst:RequestSecurityToken>
2056 <wst:TokenType>
2057 http://example.org/mySpecialToken
2058 </wst:TokenType>
2059 <wst:RequestType>
2060 http://docs.oasis-open.org/ws-sx/ws-trust/200512/Issue
2061 </wst:RequestType>
2062 </wst:RequestSecurityToken>
2063 </S11:Body>
2064 </S11:Envelope>

2065
2066The issuer (recipient) service doesn't trust the sender's timestamp (or one wasn't specified) and issues a
2067challenge using the exchange framework defined in this specification. This message is signed using the
2068private key associated with the issuer's X.509 certificate and contains a random challenge that the
2069requestor must sign:
2070 <S11:Envelope xmlns:S11="..." xmlns:wsse="..." xmlns:wsu="..."
2071 xmlns:wst="...">
2072 <S11:Header>
2073 ...
2074 <wsse:Security>
2075 <wsse:BinarySecurityToken
2076 wsu:Id="issuerToken"
2077 ValueType="...X509v3">
2078 DFJHuedsujfnrnv45JZc0...
2079 </wsse:BinarySecurityToken>
2080 <ds:Signature xmlns:ds="...">
2081 ...
2082 </ds:Signature>
2083 </wsse:Security>
2084 ...
2085 </S11:Header>
2086 <S11:Body>
2087 <wst:RequestSecurityTokenResponse>
2088 <wst:SignChallenge>
2089 <wst:Challenge>Huehf...</wst:Challenge>
2090 </wst:SignChallenge>
2091 </wst:RequestSecurityTokenResponse>
2092 </S11:Body>
2093 </S11:Envelope>

2094
2095The requestor receives the issuer's challenge and issues a response that is signed using the requestor's

157ws-trust-1.4-os 2 February 2009

158Copyright © OASIS® 1993–2009. All Rights Reserved. Page 53 of 88
2096X.509 certificate and contains the challenge. The signature only covers the non-mutable elements of the
2097message to prevent certain types of security attacks:
2098 <S11:Envelope xmlns:S11="..." xmlns:wsse="..." xmlns:wsu="..."
2099 xmlns:wst="...">
2100 <S11:Header>
2101 ...
2102 <wsse:Security>
2103 <wsse:BinarySecurityToken
2104 wsu:Id="reqToken"
2105 ValueType="...X509v3">
2106 MIIEZzCCA9CgAwIBAgIQEmtJZc0...
2107 </wsse:BinarySecurityToken>
2108 <ds:Signature xmlns:ds="...">
2109 ...
2110 </ds:Signature>
2111 </wsse:Security>
2112 ...
2113 </S11:Header>
2114 <S11:Body>
2115 <wst:RequestSecurityTokenResponse>
2116 <wst:SignChallengeResponse>
2117 <wst:Challenge>Huehf...</wst:Challenge>
2118 </wst:SignChallengeResponse>
2119 </wst:RequestSecurityTokenResponse>
2120 </S11:Body>
2121 </S11:Envelope>

2122
2123The issuer validates the requestor's signature responding to the challenge and issues the requested
2124token(s) and the associated proof-of-possession token. The proof-of-possession token is encrypted for
2125the requestor using the requestor's public key.
2126 <S11:Envelope xmlns:S11="..." xmlns:wsse="..." xmlns:wsu="..."
2127 xmlns:wst="..." xmlns:xenc="...">
2128 <S11:Header>
2129 ...
2130 <wsse:Security>
2131 <wsse:BinarySecurityToken
2132 wsu:Id="issuerToken"
2133 ValueType="...X509v3">
2134 DFJHuedsujfnrnv45JZc0...
2135 </wsse:BinarySecurityToken>
2136 <ds:Signature xmlns:ds="...">
2137 ...
2138 </ds:Signature>
2139 </wsse:Security>
2140 ...
2141 </S11:Header>
2142 <S11:Body>
2143 <wst:RequestSecurityTokenResponseCollection>
2144 <wst:RequestSecurityTokenResponse>
2145 <wst:RequestedSecurityToken>
2146 <xyz:CustomToken xmlns:xyz="...">
2147 ...
2148 </xyz:CustomToken>
2149 </wst:RequestedSecurityToken>
2150 <wst:RequestedProofToken>
2151 <xenc:EncryptedKey Id="newProof">
2152 ...
2153 </xenc:EncryptedKey>
2154 </wst:RequestedProofToken>

160ws-trust-1.4-os 2 February 2009

161Copyright © OASIS® 1993–2009. All Rights Reserved. Page 54 of 88
 2155 </wst:RequestSecurityTokenResponse>
2156 </wst:RequestSecurityTokenResponseCollection>
2157 </S11:Body>
2158 </S11:Envelope>

21598.8 Challenge Examples

21608.8.1 Text and choice challenge

2161Here is an example of a user interaction challenge using both text and choice challenges. In this example,
2162a user requests a custom token using a username/password for authentication. The STS uses the
2163challenge mechanism to challenge the user for additional information in the form of a secret question (i.e.,
2164Mother’s maiden name) and an age group choice. The challenge additionally includes one contextual
2165data item that needs to be reflected back in the response. The user interactively provides the requested
2166data and, once validated, the STS issues the requested token. All messages are sent over a protected
2167transport using SSLv3.
2168
2169The requestor sends the initial request that includes the username/password for authentication as follows.
2170
2171 <S11:Envelope ...>
2172 <S11:Header>
2173 ...
2174 <wsse:Security>
2175 <wsse:UsernameToken>
2176 <wsse:Username>Zoe</wsse:Username>
2177 <wsse:Password
2178 Type="http://...#PasswordText">ILoveDogs</wsse:Password>
2179 </wsse:UsernameToken>
2180 </wsse:Security>
2181 </S11:Header>
2182 <S11:Body>
2183 <wst:RequestSecurityToken>
2184 <wst:TokenType>http://example.org/customToken</wst:TokenType>
2185 <wst:RequestType>...</wst:RequestType>
2186 </wst:RequestSecurityToken>
2187 </S11:Body>
2188 </S11:Envelope>

2189
2190The STS issues a challenge for additional information using the user interaction challenge mechanism as
2191follows.
2192
2193 <S11:Envelope ...>
2194 <S11:Header>
2195 ...
2196 </S11:Header>
2197 <S11:Body>
2198 <wst:RequestSecurityTokenResponse>
2199 <wst14:InteractiveChallenge xmlns:wst14="..." >
2200 <wst14:Title>
2201 Please answer the following additional questions to login.
2202 </wst14:Title>
2203 <wst14:TextChallenge RefId=http://.../ref#text1
2204 Label="Mother’s Maiden Name" MaxLen=80 />
2205 <wst14:ChoiceChallenge RefId="http://.../ref#choiceGroupA"
2206 Label="Your Age Group:" ExactlyOne="true">

163ws-trust-1.4-os 2 February 2009

164Copyright © OASIS® 1993–2009. All Rights Reserved. Page 55 of 88
2207 <wst14:Choice RefId="http://.../ref#choice1" Label="18-30" />
2208 <wst14:Choice RefId="http://.../ref#choice2" Label="31-40" />
2209 <wst14:Choice RefId="http://.../ref#choice3" Label="41-50" />
2210 <wst14:Choice RefId="http://.../ref#choice4" Label="50+" />
2211 </wst14:ChoiceChallenge>
2212 <wst14:ContextData RefId="http://.../ref#cookie1">
2213 ...
2214 </wst14:ContextData>
2215 </wst14:InteractiveChallenge>
2216 </wst:RequestSecurityTokenResponse>
2217 </S11:Body>
2218 </S11:Envelope>

2219
2220The requestor receives the challenge, provides the necessary user experience for soliciting the required
2221inputs, and sends a response to the challenge back to the STS as follows.
2222
2223 <S11:Envelope ...>
2224 <S11:Header>
2225 ...
2226 </S11:Header>
2227 <S11:Body>
2228 <wst:RequestSecurityTokenResponse>
2229 <wst14:InteractiveChallengeResponse xmlns:wst14="..." >
2230 <wst14:TextChallengeResponse RefId="http://.../ref#text1">
2231 Goldstein
2232 </wst14:TextChallengeResponse>
2233 <wst14:ChoiceChallengeResponse RefId="http://.../ref#choiceGroupA">
2234 <wst14:ChoiceSelected RefId="http://.../ref#choice3" />
2235 </wst14:ChoiceChallengeResponse>
2236 <wst14:ContextData RefId="http://.../ref#cookie1">
2237 ...
2238 </wst14:ContextData>
2239 </wst14:InteractiveChallengeResponse>
2240 </wst:RequestSecurityTokenResponse>
2241 </S11:Body>
2242 </S11:Envelope>

2243
2244The STS validates the response containing the inputs from the user, and issues the requested token as
2245follows.
2246
2247 <S11:Envelope ...>
2248 <S11:Header>
2249 ...
2250 </S11:Header>
2251 <S11:Body>
2252 <wst:RequestSecurityTokenResponseCollection>
2253 <wst:RequestSecurityTokenResponse>
2254 <wst:RequestedSecurityToken>
2255 <xyz:CustomToken xmlns:xyz="...">
2256 ...
2257 </xyz:CustomToken>
2258 </wst:RequestedSecurityToken>
2259 <wst:RequestedProofToken>
2260 ...
2261 </wst:RequestedProofToken>
2262 </wst:RequestSecurityTokenResponse>
2263 </wst:RequestSecurityTokenResponseCollection>

166ws-trust-1.4-os 2 February 2009

167Copyright © OASIS® 1993–2009. All Rights Reserved. Page 56 of 88
 2264 </S11:Body>
2265 </S11:Envelope>

2266

22678.8.2 PIN challenge

2268Here is an example of a user interaction challenge using a text challenge for a secret PIN. In this
2269example, a user requests a custom token using a username/password for authentication. The STS uses
2270the text challenge mechanism for an additional PIN. The user interactively provides the PIN and, once
2271validated, the STS issues the requested token. All messages are sent over a protected transport using
2272SSLv3.
2273
2274The requestor sends the initial request that includes the username/password for authentication as follows.
2275
2276 <S11:Envelope ...>
2277 <S11:Header>
2278 ...
2279 <wsse:Security>
2280 <wsse:UsernameToken>
2281 <wsse:Username>Zoe</wsse:Username>
2282 <wsse:Password Type="http://...#PasswordText">
2283 ILoveDogs
2284 </wsse:Password>
2285 </wsse:UsernameToken>
2286 </wsse:Security>
2287 </S11:Header>
2288 <S11:Body>
2289 <wst:RequestSecurityToken>
2290 <wst:TokenType>http://example.org/customToken</wst:TokenType>
2291 <wst:RequestType>...</wst:RequestType>
2292 </wst:RequestSecurityToken>
2293 </S11:Body>
2294 </S11:Envelope>

2295
2296The STS issues a challenge for a secret PIN using the text challenge mechanism as follows.
2297
2298 <S11:Envelope ...>
2299 <S11:Header>
2300 ...
2301 </S11:Header>
2302 <S11:Body>
2303 <wst:RequestSecurityTokenResponse>
2304 <wst14:InteractiveChallenge xmlns:wst14="..." >
2305 <wst14:TextChallenge
2306 RefId="http://docs.oasis-open.org/ws-sx/ws-trust/200802/challenge/PIN"
2307 Label="Please enter your PIN" />
2308 </wst14:TextChallenge>
2309 </wst14:InteractiveChallenge>
2310 </wst:RequestSecurityTokenResponse>
2311 </S11:Body>
2312 </S11:Envelope>

2313
2314The requestor receives the challenge, provides the necessary user experience for soliciting the PIN, and
2315sends a response to the challenge back to the STS as follows.

169ws-trust-1.4-os 2 February 2009

170Copyright © OASIS® 1993–2009. All Rights Reserved. Page 57 of 88
2316
2317 <S11:Envelope ...>
2318 <S11:Header>
2319 ...
2320 </S11:Header>
2321 <S11:Body>
2322 <wst:RequestSecurityTokenResponse>
2323 <wst14:InteractiveChallengeResponse xmlns:wst14="..." >
2324 <wst14:TextChallengeResponse
2325 RefId="http://docs.oasis-open.org/ws-sx/ws-trust/200802/challenge/PIN">
2326 9988
2327 </wst14:TextChallengeResponse>
2328 </wst14:InteractiveChallengeResponse>
2329 </wst:RequestSecurityTokenResponse>
2330 </S11:Body>
2331 </S11:Envelope>

2332
2333The STS validates the PIN response, and issues the requested token as follows.
2334
2335 <S11:Envelope ...>
2336 <S11:Header>
2337 ...
2338 </S11:Header>
2339 <S11:Body>
2340 <wst:RequestSecurityTokenResponseCollection>
2341 <wst:RequestSecurityTokenResponse>
2342 <wst:RequestedSecurityToken>
2343 <xyz:CustomToken xmlns:xyz="...">
2344 ...
2345 </xyz:CustomToken>
2346 </wst:RequestedSecurityToken>
2347 <wst:RequestedProofToken>
2348 ...
2349 </wst:RequestedProofToken>
2350 </wst:RequestSecurityTokenResponse>
2351 </wst:RequestSecurityTokenResponseCollection>
2352 </S11:Body>
2353 </S11:Envelope>

2354

23558.8.3 PIN challenge with optimized response

2356The following example illustrates using the optimized PIN response pattern for the same exact challenge
2357as in the previous section. This reduces the number of message exchanges to two instead of four. All
2358messages are sent over a protected transport using SSLv3.
2359
2360The requestor sends the initial request that includes the username/password for authentication as well as
2361the response to the anticipated PIN challenge as follows.
2362
2363 <S11:Envelope ...>
2364 <S11:Header>
2365 ...
2366 <wsse:Security>
2367 <wsse:UsernameToken>
2368 <wsse:Username>Zoe</wsse:Username>

172ws-trust-1.4-os 2 February 2009

173Copyright © OASIS® 1993–2009. All Rights Reserved. Page 58 of 88
 2369 <wsse:Password Type="http://...#PasswordText">
2370 ILoveDogs
2371 </wsse:Password>
2372 </wsse:UsernameToken>
2373 </wsse:Security>
2374 </S11:Header>
2375 <S11:Body>
2376 <wst:RequestSecurityToken>
2377 <wst:TokenType>http://example.org/customToken</wst:TokenType>
2378 <wst:RequestType>...</wst:RequestType>
2379 <wst14:InteractiveChallengeResponse xmlns:wst14="..." >
2380 <wst14:TextChallengeResponse
2381 RefId="http://docs.oasis-open.org/ws-sx/ws-trust/200802/challenge/PIN">
2382 9988
2383 </wst14:TextChallengeResponse>
2384 </wst14:InteractiveChallengeResponse>
2385 </wst:RequestSecurityToken>
2386 </S11:Body>
2387 </S11:Envelope>

2388
2389The STS validates the authentication credential as well as the optimized PIN response, and issues the
2390requested token as follows.
2391
2392 <S11:Envelope ...>
2393 <S11:Header>
2394 ...
2395 </S11:Header>
2396 <S11:Body>
2397 <wst:RequestSecurityTokenResponseCollection>
2398 <wst:RequestSecurityTokenResponse>
2399 <wst:RequestedSecurityToken>
2400 <xyz:CustomToken xmlns:xyz="...">
2401 ...
2402 </xyz:CustomToken>
2403 </wst:RequestedSecurityToken>
2404 <wst:RequestedProofToken>
2405 ...
2406 </wst:RequestedProofToken>
2407 </wst:RequestSecurityTokenResponse>
2408 </wst:RequestSecurityTokenResponseCollection>
2409 </S11:Body>
2410 </S11:Envelope>

2411

24128.9 Custom Exchange Example

2413Here is another illustrating the syntax for a token request using a custom XML exchange. For brevity,
2414only the RST and RSTR elements are illustrated. Note that the framework allows for an arbitrary number
2415of exchanges, although this example illustrates the use of four legs. The request uses a custom
2416exchange element and the requestor signs only the non-mutable element of the message:
2417 <wst:RequestSecurityToken xmlns:wst="...”>
2418 <wst:TokenType>
2419 http://example.org/mySpecialToken
2420 </wst:TokenType>
2421 <wst:RequestType>
2422 http://docs.oasis-open.org/ws-sx/ws-trust/200512/Issue
2423 </wst:RequestType>

175ws-trust-1.4-os 2 February 2009

176Copyright © OASIS® 1993–2009. All Rights Reserved. Page 59 of 88
 2424 <xyz:CustomExchange xmlns:xyz="...">
2425 ...
2426 </xyz:CustomExchange>
2427 </wst:RequestSecurityToken>

2428
2429The issuer service (recipient) responds with another leg of the custom exchange and signs the response
2430(non-mutable aspects) with its token:
2431 <wst:RequestSecurityTokenResponse xmlns:wst="...”>
2432 <xyz:CustomExchange xmlns:xyz="...">
2433 ...
2434 </xyz:CustomExchange>
2435 </wst:RequestSecurityTokenResponse>

2436
2437The requestor receives the issuer's exchange and issues a response that is signed using the requestor's
2438token and continues the custom exchange. The signature covers all non-mutable aspects of the
2439message to prevent certain types of security attacks:
2440 <wst:RequestSecurityTokenResponse xmlns:wst="...”>
2441 <xyz:CustomExchange xmlns:xyz="...">
2442 ...
2443 </xyz:CustomExchange>
2444 </wst:RequestSecurityTokenResponse>

2445
2446The issuer processes the exchange and determines that the exchange is complete and that a token
2447should be issued. Consequently it issues the requested token(s) and the associated proof-of-possession
2448token. The proof-of-possession token is encrypted for the requestor using the requestor's public key.
2449 <wst:RequestSecurityTokenResponseCollection xmlns:wst="...”>
2450 <wst:RequestSecurityTokenResponse>
2451 <wst:RequestedSecurityToken>
2452 <xyz:CustomToken xmlns:xyz="...">
2453 ...
2454 </xyz:CustomToken>
2455 </wst:RequestedSecurityToken>
2456 <wst:RequestedProofToken>
2457 <xenc:EncryptedKey Id="newProof" xmlns:xenc="...">
2458 ...
2459 </xenc:EncryptedKey>
2460 </wst:RequestedProofToken>
2461 <wst:RequestedProofToken>
2462 <xenc:EncryptedKey xmlns:xenc="...">...</xenc:EncryptedKey>
2463 </wst:RequestedProofToken>
2464 </wst:RequestSecurityTokenResponse>
2465 </wst:RequestSecurityTokenResponseCollection>

2466It should be noted that other example exchanges include the issuer returning a final custom exchange
2467element, and another example where a token isn't returned.

24688.10 Protecting Exchanges

2469There are some attacks, such as forms of man-in-the-middle, that can be applied to token requests
2470involving exchanges. It is RECOMMENDED that the exchange sequence be protected. This MAY be
2471built into the exchange messages, but if metadata is provided in the RST or RSTR elements, then it is
2472subject to attack.
2473
178ws-trust-1.4-os 2 February 2009
179Copyright © OASIS® 1993–2009. All Rights Reserved. Page 60 of 88
2474Consequently, it is RECOMMENDED that keys derived from exchanges be linked cryptographically to the
2475exchange. For example, a hash can be computed by computing the SHA1 of the exclusive
2476canonicalization [XML-C14N] of all RST and RSTR elements in messages exchanged. This value can
2477then be combined with the exchanged secret(s) to create a new master secret that is bound to the data
2478both parties sent/received.
2479
2480To this end, the following computed key algorithm is defined to be OPTIONALLY used in these scenarios:
URI Meaning
http://docs.oasis-open.org/ws-sx/ws- The key is computed using P_SHA1 as
trust/200512/CK/HASH follows:
H=SHA1(ExclC14N(RST...RSTRs))
X=encrypting H using negotiated
key and mechanism
Key=P_SHA1(X,H+"CK-HASH")
The octets for the "CK-HASH" string are the
UTF-8 octets.

24818.11 Authenticating Exchanges

2482After an exchange both parties have a shared knowledge of a key (or keys) that can then be used to
2483secure messages. However, in some cases it may be desired to have the issuer prove to the requestor
2484that it knows the key (and that the returned metadata is valid) prior to the requestor using the data.
2485However, until the exchange is actually completed it MAY be (and is often) inappropriate to use the
2486computed keys. As well, using a token that hasn't been returned to secure a message may complicate
2487processing since it crosses the boundary of the exchange and the underlying message security. This
2488means that it MAY NOT be appropriate to sign the final leg of the exchange using the key derived from
2489the exchange.
2490
2491For this reason an authenticator is defined that provides a way for the issuer to verify the hash as part of
2492the token issuance. Specifically, when an authenticator is returned, the
2493<wst:RequestSecurityTokenResponseCollection> element is returned. This contains one
2494RSTR with the token being returned as a result of the exchange and a second RSTR that contains the
2495authenticator (this order SHOULD be used). When an authenticator is used, RSTRs MUST use the
2496@Context element so that the authenticator can be correlated to the token issuance. The authenticator is
2497separated from the RSTR because otherwise computation of the RST/RSTR hash becomes more
2498complex. The authenticator is represented using the <wst:Authenticator> element as illustrated
2499below:
2500 <wst:RequestSecurityTokenResponseCollection xmlns:wst="...”>
2501 <wst:RequestSecurityTokenResponse Context="...">
2502 ...
2503 </wst:RequestSecurityTokenResponse>
2504 <wst:RequestSecurityTokenResponse Context="...">
2505 <wst:Authenticator>
2506 <wst:CombinedHash>...</wst:CombinedHash>
2507 ...
2508 </wst:Authenticator>
2509 </wst:RequestSecurityTokenResponse>
2510 </wst:RequestSecurityTokenResponseCollection>

181ws-trust-1.4-os 2 February 2009

182Copyright © OASIS® 1993–2009. All Rights Reserved. Page 61 of 88
2511
2512The following describes the attributes and elements listed in the schema overview above (the ... notation
2513below represents the path RSTRC/RSTR and is used for brevity):
2514.../wst:Authenticator
2515 This OPTIONAL element provides verification (authentication) of a computed hash.
2516.../wst:Authenticator/wst:CombinedHash
2517 This OPTIONAL element proves the hash and knowledge of the computed key. This is done by
2518 providing the base64 encoding of the first 256 bits of the P_SHA1 digest of the computed key and
2519 the concatenation of the hash determined for the computed key and the string "AUTH-HASH".
2520 Specifically, P_SHA1(computed-key, H + "AUTH-HASH")0-255. The octets for the "AUTH-HASH"
2521 string are the UTF-8 octets.
2522
2523This <wst:CombinedHash> element is OPTIONAL (and an open content model is used) to allow for
2524different authenticators in the future.

184ws-trust-1.4-os 2 February 2009

185Copyright © OASIS® 1993–2009. All Rights Reserved. Page 62 of 88
25259 Key and Token Parameter Extensions
2526This section outlines additional parameters that can be specified in token requests and responses.
2527Typically they are used with issuance requests, but since all types of requests MAY issue security tokens
2528they could apply to other bindings.

25299.1 On-Behalf-Of Parameters

2530In some scenarios the requestor is obtaining a token on behalf of another party. These parameters
2531specify the issuer and original requestor of the token being used as the basis of the request. The syntax
2532is as follows (note that the base elements described above are included here italicized for completeness):
2533 <wst:RequestSecurityToken xmlns:wst="...”>
2534 <wst:TokenType>...</wst:TokenType>
2535 <wst:RequestType>...</wst:RequestType>
2536 ...
2537 <wst:OnBehalfOf>...</wst:OnBehalfOf>
2538 <wst:Issuer>...</wst:Issuer>
2539 </wst:RequestSecurityToken>

2540
2541The following describes the attributes and elements listed in the schema overview above:
2542/wst:RequestSecurityToken/wst:OnBehalfOf
2543 This OPTIONAL element indicates that the requestor is making the request on behalf of another.
2544 The identity on whose behalf the request is being made is specified by placing a security token,
2545 <wsse:SecurityTokenReference> element, or <wsa:EndpointReference> element
2546 within the <wst:OnBehalfOf> element. The requestor MAY provide proof of possession of the
2547 key associated with the OnBehalfOf identity by including a signature in the RST security header
2548 generated using the OnBehalfOf token that signs the primary signature of the RST (i.e. endorsing
2549 supporting token concept from WS-SecurityPolicy). Additional signed supporting tokens
2550 describing the OnBehalfOf context MAY also be included within the RST security header.
2551/wst:RequestSecurityToken/wst:Issuer
2552 This OPTIONAL element specifies the issuer of the security token that is presented in the
2553 message. This element's type is an endpoint reference as defined in [WS-Addressing].
2554
2555In the following illustrates the syntax for a proxy that is requesting a security token on behalf of another
2556requestor or end-user.
2557 <wst:RequestSecurityToken xmlns:wst="...”>
2558 <wst:TokenType>...</wst:TokenType>
2559 <wst:RequestType>...</wst:RequestType>
2560 ...
2561 <wst:OnBehalfOf>endpoint-reference</wst:OnBehalfOf>
2562 </wst:RequestSecurityToken>

25639.2 Key and Encryption Requirements

2564This section defines extensions to the <wst:RequestSecurityToken> element for requesting specific
2565types of keys or algorithms or key and algorithms as specified by a given policy in the return token(s). In
2566some cases the service may support a variety of key types, sizes, and algorithms. These parameters
2567allow a requestor to indicate its desired values. It should be noted that the issuer's policy indicates if input
187ws-trust-1.4-os 2 February 2009
188Copyright © OASIS® 1993–2009. All Rights Reserved. Page 63 of 88
2568values must be adhered to and faults generated for invalid inputs, or if the issuer will provide alterative
2569values in the response.
2570
2571Although illustrated using the <wst:RequestSecurityToken> element, these options can also be
2572returned in a <wst:RequestSecurityTokenResponse> element.
2573The syntax for these OPTIONAL elements is as follows (note that the base elements described above are
2574included here italicized for completeness):
2575 <wst:RequestSecurityToken xmlns:wst="...”>
2576 <wst:TokenType>...</wst:TokenType>
2577 <wst:RequestType>...</wst:RequestType>
2578 ...
2579 <wst:AuthenticationType>...</wst:AuthenticationType>
2580 <wst:KeyType>...</wst:KeyType>
2581 <wst:KeySize>...</wst:KeySize>
2582 <wst:SignatureAlgorithm>...</wst:SignatureAlgorithm>
2583 <wst:EncryptionAlgorithm>...</wst:EncryptionAlgorithm>
2584 <wst:CanonicalizationAlgorithm>...</wst:CanonicalizationAlgorithm>
2585 <wst:ComputedKeyAlgorithm>...</wst:ComputedKeyAlgorithm>
2586 <wst:Encryption>...</wst:Encryption>
2587 <wst:ProofEncryption>...</wst:ProofEncryption>
2588 <wst:KeyWrapAlgorithm>...</wst:KeyWrapAlgorithm>
2589 <wst:UseKey Sig="..."> </wst:UseKey>
2590 <wst:SignWith>...</wst:SignWith>
2591 <wst:EncryptWith>...</wst:EncryptWith>
2592 </wst:RequestSecurityToken>

2593
2594The following describes the attributes and elements listed in the schema overview above:
2595/wst:RequestSecurityToken/wst:AuthenticationType
2596 This OPTIONAL URI element indicates the type of authentication desired, specified as a URI.
2597 This specification does not predefine classifications; these are specific to token services as is the
2598 relative strength evaluations. The relative assessment of strength is up to the recipient to
2599 determine. That is, requestors SHOULD be familiar with the recipient policies. For example, this
2600 might be used to indicate which of the four U.S. government authentication levels is REQUIRED.
2601/wst:RequestSecurityToken/wst:KeyType
2602 This OPTIONAL URI element indicates the type of key desired in the security token. The
2603 predefined values are identified in the table below. Note that some security token formats have
2604 fixed key types. It should be noted that new algorithms can be inserted by defining URIs in other
2605 specifications and profiles.

URI Meaning
http://docs.oasis-open.org/ws-sx/ws- A public key token is requested
trust/200512/PublicKey
http://docs.oasis-open.org/ws-sx/ws- A symmetric key token is requested (default)
trust/200512/SymmetricKey
http://docs.oasis-open.org/ws- A bearer token is requested. This key type
sx/wstrust/200512/Bearer can be used by requestors to indicate that
they want a security token to be issued that
does not require proof of possession.

2606/wst:RequestSecurityToken/wst:KeySize
190ws-trust-1.4-os 2 February 2009
191Copyright © OASIS® 1993–2009. All Rights Reserved. Page 64 of 88
2607 This OPTIONAL integer element indicates the size of the key REQUIRED specified in number of
2608 bits. This is a request, and, as such, the requested security token is not obligated to use the
2609 requested key size. That said, the recipient SHOULD try to use a key at least as strong as the
2610 specified value if possible. The information is provided as an indication of the desired strength of
2611 the security.
2612/wst:RequestSecurityToken/wst:SignatureAlgorithm
2613 This OPTIONAL URI element indicates the desired signature algorithm used within the returned
2614 token. This is specified as a URI indicating the algorithm (see [XML-Signature] for typical signing
2615 algorithms).
2616/wst:RequestSecurityToken/wst:EncryptionAlgorithm
2617 This OPTIONAL URI element indicates the desired encryption algorithm used within the returned
2618 token. This is specified as a URI indicating the algorithm (see [XML-Encrypt] for typical
2619 encryption algorithms).
2620/wst:RequestSecurityToken/wst:CanonicalizationAlgorithm
2621 This OPTIONAL URI element indicates the desired canonicalization method used within the
2622 returned token. This is specified as a URI indicating the method (see [XML-Signature] for typical
2623 canonicalization methods).
2624/wst:RequestSecurityToken/wst:ComputedKeyAlgorithm
2625 This OPTIONAL URI element indicates the desired algorithm to use when computed keys are
2626 used for issued tokens.
2627/wst:RequestSecurityToken/wst:Encryption
2628 This OPTIONAL element indicates that the requestor desires any returned secrets in issued
2629 security tokens to be encrypted for the specified token. That is, so that the owner of the specified
2630 token can decrypt the secret. Normally the security token is the contents of this element but a
2631 security token reference MAY be used instead. If this element isn't specified, the token used as
2632 the basis of the request (or specialized knowledge) is used to determine how to encrypt the key.
2633/wst:RequestSecurityToken/wst:ProofEncryption
2634 This OPTIONAL element indicates that the requestor desires any returned secrets in proof-of-
2635 possession tokens to be encrypted for the specified token. That is, so that the owner of the
2636 specified token can decrypt the secret. Normally the security token is the contents of this element
2637 but a security token reference MAY be used instead. If this element isn't specified, the token
2638 used as the basis of the request (or specialized knowledge) is used to determine how to encrypt
2639 the key.
2640/wst:RequestSecurityToken/wst:KeyWrapAlgorithm
2641 This OPTIONAL URI element indicates the desired algorithm to use for key wrapping when STS
2642 encrypts the issued token for the relying party using an asymmetric key.
2643/wst:RequestSecurityToken/wst:UseKey
2644 If the requestor wishes to use an existing key rather than create a new one, then this OPTIONAL
2645 element can be used to reference the security token containing the desired key. This element
2646 either contains a security token or a <wsse:SecurityTokenReference> element that
2647 references the security token containing the key that SHOULD be used in the returned token. If
2648 <wst:KeyType> is not defined and a key type is not implicitly known to the service, it MAY be
2649 determined from the token (if possible). Otherwise this parameter is meaningless and is ignored.
2650 Requestors SHOULD demonstrate authorized use of the public key provided.
2651/wst:RequestSecurityToken/wst:UseKey/@Sig
2652 In order to authenticate the key referenced, a signature MAY be used to prove the referenced
2653 token/key. If specified, this OPTIONAL attribute indicates the ID of the corresponding signature
193ws-trust-1.4-os 2 February 2009
194Copyright © OASIS® 1993–2009. All Rights Reserved. Page 65 of 88
 2654 (by URI reference). When this attribute is present, a key need not be specified inside the element
2655 since the referenced signature will indicate the corresponding token (and key).
2656/wst:RequestSecurityToken/wst:SignWith
2657 This OPTIONAL URI element indicates the desired signature algorithm to be used with the issued
2658 security token (typically from the policy of the target site for which the token is being requested.
2659 While any of these OPTIONAL elements MAY be included in RSTRs, this one is a likely
2660 candidate if there is some doubt (e.g., an X.509 cert that can only use DSS).
2661/wst:RequestSecurityToken/wst:EncryptWith
2662 This OPTIONAL URI element indicates the desired encryption algorithm to be used with the
2663 issued security token (typically from the policy of the target site for which the token is being
2664 requested.) While any of these OPTIONAL elements MAY be included in RSTRs, this one is a
2665 likely candidate if there is some doubt.
2666The following summarizes the various algorithm parameters defined above. T is the issued token, P is the
2667proof key.
2668
2669 SignatureAlgorithm - The signature algorithm to use to sign T
2670 EncryptionAlgorithm - The encryption algorithm to use to encrypt T
2671 CanonicalizationAlgorithm - The canonicalization algorithm to use when signing T
2672 ComputedKeyAlgorithm - The key derivation algorithm to use if using a symmetric key for P
2673 where P is computed using client, server, or combined entropy
2674 Encryption - The token/key to use when encrypting T
2675 ProofEncryption - The token/key to use when encrypting P
2676 UseKey - This is P. This is generally used when the client supplies a public-key that it wishes to
2677 be embedded in T as the proof key
2678 SignWith - The signature algorithm the client intends to employ when using P to
2679 sign
2680The encryption algorithms further differ based on whether the issued token contains asymmetric key or
2681symmetric key. Furthermore, they differ based on what type of key is used to protect the issued token
2682from the STS to the relying party. The following cases can occur:
2683 T contains symmetric key/STS uses symmetric key to encrypt T for RP
2684 EncryptWith – used to indicate symmetric algorithm that client will use to protect message to RP
2685 when using the proof key (e.g. AES256)
2686 EncryptionAlgorithm – used to indicate the symmetric algorithm that the STS SHOULD use to
2687 encrypt the T (e.g. AES256)
2688
2689 T contains symmetric key/STS uses asymmetric key to encrypt T for RP
2690 EncryptWith – used to indicate symmetric algorithm that client will use to protect message to RP
2691 when using the proof key (e.g. AES256)
2692 EncryptionAlgorithm – used to indicate the symmetric algorithm that the STS SHOULD use to
2693 encrypt T for RP (e.g. AES256)
2694 KeyWrapAlgorithm – used to indicate the KeyWrap algorithm that the STS SHOULD use to
2695 wrap the generated key that is used to encrypt the T for RP
2696
2697 T contains asymmetric key/STS uses symmetric key to encrypt T for RP

196ws-trust-1.4-os 2 February 2009

197Copyright © OASIS® 1993–2009. All Rights Reserved. Page 66 of 88
2698 EncryptWith – used to indicate the KeyWrap algorithm that the client will use to
2699 protect the symmetric key that is used to protect messages to RP when using the proof key (e.g.
2700 RSA-OAEP-MGF1P)
2701 EncryptionAlgorithm – used to indicate the symmetric algorithm that the STS SHOULD use to
2702 encrypt T for RP (e.g. AES256)
2703
2704 T contains asymmetric key/STS uses asymmetric key to encrypt T for RP
2705 EncryptWith - used to indicate the KeyWrap algorithm that the client will use to
2706 protect symmetric key that is used to protect message to RP when using the proof
2707 key (e.g. RSA-OAEP-MGF1P)
2708 EncryptionAlgorithm - used to indicate the symmetric algorithm that the STS SHOULD use to
2709 encrypt T for RP (e.g. AES256)
2710 KeyWrapAlgorithm – used to indicate the KeyWrap algorithm that the STS SHOULD use to
2711 wrap the generated key that is used to encrypt the T for RP
2712
2713The example below illustrates a request that utilizes several of these parameters. A request is made for a
2714custom token using a username and password as the basis of the request. For security, this token is
2715encrypted (see "encUsername") for the recipient using the recipient's public key and referenced in the
2716encryption manifest. The message is protected by a signature using a public key from the sender and
2717authorized by the username and password.
2718
2719The requestor would like the custom token to contain a 1024-bit public key whose value can be found in
2720the key provided with the "proofSignature" signature (the key identified by "requestProofToken"). The
2721token should be signed using RSA-SHA1 and encrypted for the token identified by
2722"requestEncryptionToken". The proof should be encrypted using the token identified by
2723"requestProofToken".
2724 <S11:Envelope xmlns:S11="..." xmlns:wsse="..." xmlns:wsu="..."
2725 xmlns:wst="..." xmlns:ds="..." xmlns:xenc="...">
2726 <S11:Header>
2727 ...
2728 <wsse:Security>
2729 <xenc:ReferenceList>...</xenc:ReferenceList>
2730 <xenc:EncryptedData Id="encUsername">...</xenc:EncryptedData>
2731 <wsse:BinarySecurityToken wsu:Id="requestEncryptionToken"
2732 ValueType="...SomeTokenType" xmlns:x="...">
2733 MIIEZzCCA9CgAwIBAgIQEmtJZc0...
2734 </wsse:BinarySecurityToken>
2735 <wsse:BinarySecurityToken wsu:Id="requestProofToken"
2736 ValueType="...SomeTokenType" xmlns:x="...">
2737 MIIEZzCCA9CgAwIBAgIQEmtJZc0...
2738 </wsse:BinarySecurityToken>
2739 <ds:Signature Id="proofSignature">
2740 ... signature proving requested key ...
2741 ... key info points to the "requestedProofToken" token ...
2742 </ds:Signature>
2743 </wsse:Security>
2744 ...
2745 </S11:Header>
2746 <S11:Body wsu:Id="req">
2747 <wst:RequestSecurityToken>
2748 <wst:TokenType>

199ws-trust-1.4-os 2 February 2009

200Copyright © OASIS® 1993–2009. All Rights Reserved. Page 67 of 88
 2749 http://example.org/mySpecialToken
2750 </wst:TokenType>
2751 <wst:RequestType>
2752 http://docs.oasis-open.org/ws-sx/ws-trust/200512/Issue
2753 </wst:RequestType>
2754 <wst:KeyType>
2755 http://docs.oasis-open.org/ws-sx/ws-trust/200512/PublicKey
2756 </wst:KeyType>
2757 <wst:KeySize>1024</wst:KeySize>
2758 <wst:SignatureAlgorithm>
2759 http://www.w3.org/2000/09/xmldsig#rsa-sha1
2760 </wst:SignatureAlgorithm>
2761 <wst:Encryption>
2762 <Reference URI="#requestEncryptionToken"/>
2763 </wst:Encryption>
2764 <wst:ProofEncryption>
2765 <wsse:Reference URI="#requestProofToken"/>
2766 </wst:ProofEncryption>
2767 <wst:UseKey Sig="#proofSignature"/>
2768 </wst:RequestSecurityToken>
2769 </S11:Body>
2770 </S11:Envelope>

27719.3 Delegation and Forwarding Requirements

2772This section defines extensions to the <wst:RequestSecurityToken> element for indicating
2773delegation and forwarding requirements on the requested security token(s).
2774The syntax for these extension elements is as follows (note that the base elements described above are
2775included here italicized for completeness):
2776 <wst:RequestSecurityToken xmlns:wst="...”>
2777 <wst:TokenType>...</wst:TokenType>
2778 <wst:RequestType>...</wst:RequestType>
2779 ...
2780 <wst:DelegateTo>...</wst:DelegateTo>
2781 <wst:Forwardable>...</wst:Forwardable>
2782 <wst:Delegatable>...</wst:Delegatable>
2783 <wst:ActAs>...</wst:ActAs>
2784 </wst:RequestSecurityToken>

2785/wst:RequestSecurityToken/wst:DelegateTo
2786 This OPTIONAL element indicates that the requested or issued token be delegated to another
2787 identity. The identity receiving the delegation is specified by placing a security token or
2788 <wsse:SecurityTokenReference> element within the <wst:DelegateTo> element.
2789/wst:RequestSecurityToken/wst:Forwardable
2790 This OTPIONAL element, of type xs:boolean, specifies whether the requested security token
2791 SHOULD be marked as "Forwardable". In general, this flag is used when a token is normally
2792 bound to the requestor's machine or service. Using this flag, the returned token MAY be used
2793 from any source machine so long as the key is correctly proven. The default value of this flag is
2794 true.
2795/wst:RequestSecurityToken/wst:Delegatable
2796 This OPTIONAL element, of type xs:boolean, specifies whether the requested security token
2797 SHOULD be marked as "Delegatable". Using this flag, the returned token MAY be delegated to
2798 another party. This parameter SHOULD be used in conjunction with <wst:DelegateTo>. The
2799 default value of this flag is false.
2800/wst:RequestSecurityToken/wst:ActAs
202ws-trust-1.4-os 2 February 2009
203Copyright © OASIS® 1993–2009. All Rights Reserved. Page 68 of 88
 2801 This OTPIONAL element indicates that the requested token is expected to contain information
2802 about the identity represented by the content of this element and the token requestor intends to
2803 use the returned token to act as this identity. The identity that the requestor wants to act-as is
2804 specified by placing a security token or <wsse:SecurityTokenReference> element within the
2805 <wst:ActAs> element.
2806The following illustrates the syntax of a request for a custom token that can be delegated to the indicated
2807recipient (specified in the binary security token) and used in the specified interval.
2808 <wst:RequestSecurityToken xmlns:wst="...”>
2809 <wst:TokenType>
2810 http://example.org/mySpecialToken
2811 </wst:TokenType>
2812 <wst:RequestType>
2813 http://docs.oasis-open.org/ws-sx/ws-trust/200512/Issue
2814 </wst:RequestType>
2815 <wst:DelegateTo>
2816 <wsse:BinarySecurityToken xmlns:wsse="...">
2817 ...
2818 </wsse:BinarySecurityToken>
2819 </wst:DelegateTo>
2820 <wst:Delegatable>true</wst:Delegatable>
2821 </wst:RequestSecurityToken>

28229.4 Policies
2823This section defines extensions to the <wst:RequestSecurityToken> element for passing policies.
2824
2825The syntax for these extension elements is as follows (note that the base elements described above are
2826included here italicized for completeness):
2827 <wst:RequestSecurityToken xmlns:wst="...”>
2828 <wst:TokenType>...</wst:TokenType>
2829 <wst:RequestType>...</wst:RequestType>
2830 ...
2831 <wsp:Policy xmlns:wsp="...”>...</wsp:Policy>
2832 <wsp:PolicyReference xmlns:wsp="...”>...</wsp:PolicyReference>
2833 </wst:RequestSecurityToken>

2834
2835The following describes the attributes and elements listed in the schema overview above:
2836/wst:RequestSecurityToken/wsp:Policy
2837 This OPTIONAL element specifies a policy (as defined in [WS-Policy]) that indicates desired
2838 settings for the requested token. The policy specifies defaults that can be overridden by the
2839 elements defined in the previous sections.
2840/wst:RequestSecurityToken/wsp:PolicyReference
2841 This OPTIONAL element specifies a reference to a policy (as defined in [WS-Policy]) that
2842 indicates desired settings for the requested token. The policy specifies defaults that can be
2843 overridden by the elements defined in the previous sections.
2844
2845The following illustrates the syntax of a request for a custom token that provides a set of policy
2846statements about the token or its usage requirements.
2847 <wst:RequestSecurityToken xmlns:wst="...”>
2848 <wst:TokenType>
2849 http://example.org/mySpecialToken

205ws-trust-1.4-os 2 February 2009

206Copyright © OASIS® 1993–2009. All Rights Reserved. Page 69 of 88
 2850 </wst:TokenType>
2851 <wst:RequestType>
2852 http://docs.oasis-open.org/ws-sx/ws-trust/200512/Issue
2853 </wst:RequestType>
2854 <wsp:Policy xmlns:wsp="...">
2855 ...
2856 </wsp:Policy>
2857 </wst:RequestSecurityToken>

28589.5 Authorized Token Participants

2859This section defines extensions to the <wst:RequestSecurityToken> element for passing information
2860about which parties are authorized to participate in the use of the token. This parameter is typically used
2861when there are additional parties using the token or if the requestor needs to clarify the actual parties
2862involved (for some profile-specific reason).
2863It should be noted that additional participants will need to prove their identity to recipients in addition to
2864proving their authorization to use the returned token. This typically takes the form of a second signature
2865or use of transport security.
2866
2867The syntax for these extension elements is as follows (note that the base elements described above are
2868included here italicized for completeness):
2869 <wst:RequestSecurityToken xmlns:wst="...”>
2870 <wst:TokenType>...</wst:TokenType>
2871 <wst:RequestType>...</wst:RequestType>
2872 ...
2873 <wst:Participants>
2874 <wst:Primary>...</wst:Primary>
2875 <wst:Participant>...</wst:Participant>
2876 </wst:Participants>
2877 </wst:RequestSecurityToken>

2878
2879The following describes elements and attributes used in a <wsc:SecurityContextToken> element.
2880/wst:RequestSecurityToken/wst:Participants/
2881 This OPTIONAL element specifies the participants sharing the security token. Arbitrary types
2882 MAY be used to specify participants, but a typical case is a security token or an endpoint
2883 reference (see [WS-Addressing]).
2884/wst:RequestSecurityToken/wst:Participants/wst:Primary
2885 This OPTIONAL element specifies the primary user of the token (if one exists).
2886/wst:RequestSecurityToken/wst:Participants/wst:Participant
2887 This OPTIONAL element specifies participant (or multiple participants by repeating the element)
2888 that play a (profile-dependent) role in the use of the token or who are allowed to use the token.
2889/wst:RequestSecurityToken/wst:Participants/{any}
2890 This is an extensibility option to allow other types of participants and profile-specific elements to
2891 be specified.

208ws-trust-1.4-os 2 February 2009

209Copyright © OASIS® 1993–2009. All Rights Reserved. Page 70 of 88
289210Key Exchange Token Binding
2893Using the token request framework, this section defines a binding for requesting a key exchange token
2894(KET). That is, if a requestor desires a token that can be used to encrypt key material for a recipient.
2895
2896For this binding, the following actions are defined to enable specific processing context to be conveyed to
2897the recipient:
2898 http://docs.oasis-open.org/ws-sx/ws-trust/200512/RST/KET
2899 http://docs.oasis-open.org/ws-sx/ws-trust/200512/RSTR/KET
2900 http://docs.oasis-open.org/ws-sx/ws-trust/200512/RSTR/KETFinal

2901
2902For this binding, the RequestType element contains the following URI:
2903 http://docs.oasis-open.org/ws-sx/ws-trust/200512/KET

2904
2905For this binding very few parameters are specified as input. OPTIONALLY the <wst:TokenType>
2906element can be specified in the request can indicate desired type response token carrying the key for key
2907exchange; however, this isn't commonly used.
2908The applicability scope (e.g. <wsp:AppliesTo>) MAY be specified if the requestor desires a key
2909exchange token for a specific scope.
2910
2911It is RECOMMENDED that the response carrying the key exchange token be secured (e.g., signed by the
2912issuer or someone who can speak on behalf of the target for which the KET applies).
2913
2914Care should be taken when using this binding to prevent possible man-in-the-middle and substitution
2915attacks. For example, responses to this request SHOULD be secured using a token that can speak for
2916the desired endpoint.
2917
2918The RSTR for this binding carries the <RequestedSecurityToken> element even if a token is returned
2919(note that the base elements described above are included here italicized for completeness):
2920 <wst:RequestSecurityToken xmlns:wst="...”>
2921 <wst:TokenType>...</wst:TokenType>
2922 <wst:RequestType>...</wst:RequestType>
2923 ...
2924 </wst:RequestSecurityToken>

2925
2926 <wst:RequestSecurityTokenResponseCollection xmlns:wst="...”>
2927 <wst:RequestSecurityTokenResponse>
2928 <wst:TokenType>...</wst:TokenType>
2929 <wst:RequestedSecurityToken>...</wst:RequestedSecurityToken>
2930 ...
2931 </wst:RequestSecurityTokenResponse>
2932 </wst:RequestSecurityTokenResponseCollection>

2933

211ws-trust-1.4-os 2 February 2009

212Copyright © OASIS® 1993–2009. All Rights Reserved. Page 71 of 88
2934The following illustrates the syntax for requesting a key exchange token. In this example, the KET is
2935returned encrypted for the requestor since it had the credentials available to do that. Alternatively the
2936request could be made using transport security (e.g. TLS) and the key could be returned directly using
2937<wst:BinarySecret>.
2938 <wst:RequestSecurityToken xmlns:wst="...”>
2939 <wst:RequestType>
2940 http://docs.oasis-open.org/ws-sx/ws-trust/200512/KET
2941 </wst:RequestType>
2942 </wst:RequestSecurityToken>

2943
2944 <wst:RequestSecurityTokenResponseCollection xmlns:wst="...”>
2945 <wst:RequestSecurityTokenResponse>
2946 <wst:RequestedSecurityToken>
2947 <xenc:EncryptedKey xmlns:xenc="...”>...</xenc:EncryptedKey>
2948 </wst:RequestedSecurityToken>
2949 </wst:RequestSecurityTokenResponse>
2950 </wst:RequestSecurityTokenResponseCollection>

214ws-trust-1.4-os 2 February 2009

215Copyright © OASIS® 1993–2009. All Rights Reserved. Page 72 of 88
295111 Error Handling
2952There are many circumstances where an error can occur while processing security information. Errors
2953use the SOAP Fault mechanism. Note that the reason text provided below is RECOMMENDED, but
2954alternative text MAY be provided if more descriptive or preferred by the implementation. The tables below
2955are defined in terms of SOAP 1.1. For SOAP 1.2, the Fault/Code/Value is env:Sender (as defined in
2956SOAP 1.2) and the Fault/Code/Subcode/Value is the faultcode below and the Fault/Reason/Text is the
2957faultstring below. It should be noted that profiles MAY provide second-level detail fields, but they should
2958be careful not to introduce security vulnerabilities when doing so (e.g., by providing too detailed
2959information).
Error that occurred (faultstring) Fault code (faultcode)
The request was invalid or malformed wst:InvalidRequest
Authentication failed wst:FailedAuthentication
The specified request failed wst:RequestFailed
Security token has been revoked wst:InvalidSecurityToken
Insufficient Digest Elements wst:AuthenticationBadElements
The specified RequestSecurityToken is not wst:BadRequest
understood.

The request data is out-of-date wst:ExpiredData

The requested time range is invalid or wst:InvalidTimeRange

unsupported

The request scope is invalid or unsupported wst:InvalidScope

A renewable security token has expired wst:RenewNeeded

The requested renewal failed wst:UnableToRenew

217ws-trust-1.4-os 2 February 2009

218Copyright © OASIS® 1993–2009. All Rights Reserved. Page 73 of 88
296012 Security Considerations
2961As stated in the Goals section of this document, this specification is meant to provide extensible
2962framework and flexible syntax, with which one could implement various security mechanisms. This
2963framework and syntax by itself does not provide any guarantee of security. When implementing and using
2964this framework and syntax, one must make every effort to ensure that the result is not vulnerable to any
2965one of a wide range of attacks.
2966
2967It is not feasible to provide a comprehensive list of security considerations for such an extensible set of
2968mechanisms. A complete security analysis must be conducted on specific solutions based on this
2969specification. Below we illustrate some of the security concerns that often come up with protocols of this
2970type, but we stress that this is not an exhaustive list of concerns.
2971
2972The following statements about signatures and signing apply to messages sent on unsecured channels.
2973
2974It is critical that all the security-sensitive message elements must be included in the scope of the message
2975signature. As well, the signatures for conversation authentication must include a timestamp, nonce, or
2976sequence number depending on the degree of replay prevention required as described in [WS-Security]
2977and the UsernameToken Profile. Also, conversation establishment should include the policy so that
2978supported algorithms and algorithm priorities can be validated.
2979
2980It is required that security token issuance messages be signed to prevent tampering. If a public key is
2981provided, the request should be signed by the corresponding private key to prove ownership. As well,
2982additional steps should be taken to eliminate replay attacks (refer to [WS-Security] for additional
2983information). Similarly, all token references should be signed to prevent any tampering.
2984
2985Security token requests are susceptible to denial-of-service attacks. Care should be taken to mitigate
2986such attacks as is warranted by the service.
2987
2988For security, tokens containing a symmetric key or a password should only be sent to parties who have a
2989need to know that key or password.
2990
2991For privacy, tokens containing personal information (either in the claims, or indirectly by identifying who is
2992currently communicating with whom) should only be sent according to the privacy policies governing
2993these data at the respective organizations.
2994
2995For some forms of multi-message exchanges, the exchanges are susceptible to attacks whereby
2996signatures are altered. To address this, it is suggested that a signature confirmation mechanism be used.
2997In such cases, each leg should include the confirmation of the previous leg. That is, leg 2 includes
2998confirmation for leg 1, leg 3 for leg 2, leg 4 for leg 3, and so on. In doing so, each side can confirm the
2999correctness of the message outside of the message body.
3000

220ws-trust-1.4-os 2 February 2009

221Copyright © OASIS® 1993–2009. All Rights Reserved. Page 74 of 88
3001There are many other security concerns that one may need to consider in security protocols. The list
3002above should not be used as a "check list" instead of a comprehensive security analysis.
3003
3004It should be noted that use of unsolicited RSTRs implies that the recipient is prepared to accept such
3005issuances. Recipients should ensure that such issuances are properly authorized and recognize their use
3006could be used in denial-of-service attacks.
3007In addition to the consideration identified here, readers should also review the security considerations in
3008[WS-Security].
3009
3010Both token cancellation bindings defined in this specification require that the STS MUST NOT validate or
3011renew the token after it has been successfully canceled. The STS must take care to ensure that the token
3012is properly invalidated before confirming the cancel request or sending the cancel notification to the client.
3013This can be more difficult if the token validation or renewal logic is physically separated from the issuance
3014and cancellation logic. It is out of scope of this spec how the STS propagates the token cancellation to its
3015other components. If STS cannot ensure that the token was properly invalidated it MUST NOT send the
3016cancel notification or confirm the cancel request to the client.
3017

223ws-trust-1.4-os 2 February 2009

224Copyright © OASIS® 1993–2009. All Rights Reserved. Page 75 of 88
301813 Conformance
3019
3020An implementation conforms to this specification if it satisfies all of the MUST or REQUIRED level
3021requirements defined within this specification. A SOAP Node MUST NOT use the XML namespace
3022identifier for this specification (listed in Section 1.3) within SOAP Envelopes unless it is compliant with this
3023specification.
3024This specification references a number of other specifications (see the table above). In order to comply
3025with this specification, an implementation MUST implement the portions of referenced specifications
3026necessary to comply with the required provisions of this specification. Additionally, the implementation of
3027the portions of the referenced specifications that are specifically cited in this specification MUST comply
3028with the rules for those portions as established in the referenced specification.
3029Additionally normative text within this specification takes precedence over normative outlines (as
3030described in section 1.5.1), which in turn take precedence over the XML Schema [XML Schema Part 1,
3031Part 2] and WSDL [WSDL 1.1] descriptions. That is, the normative text in this specification further
3032constrains the schemas and/or WSDL that are part of this specification; and this specification contains
3033further constraints on the elements defined in referenced schemas.
3034This specification defines a number of extensions; compliant services are NOT REQUIRED to implement
3035OPTIONAL features defined in this specification. However, if a service implements an aspect of the
3036specification, it MUST comply with the requirements specified (e.g. related "MUST" statements). If an
3037OPTIONAL message is not supported, then the implementation SHOULD Fault just as it would for any
3038other unrecognized/unsupported message. If an OPTIONAL message is supported, then the
3039implementation MUST satisfy all of the MUST and REQUIRED sections of the message.

226ws-trust-1.4-os 2 February 2009

227Copyright © OASIS® 1993–2009. All Rights Reserved. Page 76 of 88
3040A. Key Exchange
3041Key exchange is an integral part of token acquisition. There are several mechanisms by which keys are
3042exchanged using [WS-Security] and WS-Trust. This section highlights and summarizes these
3043mechanisms. Other specifications and profiles MAY provide additional details on key exchange.
3044
3045Care must be taken when employing a key exchange to ensure that the mechanism does not provide an
3046attacker with a means of discovering information that could only be discovered through use of secret
3047information (such as a private key).
3048
3049It is therefore important that a shared secret should only be considered as trustworthy as its source. A
3050shared secret communicated by means of the direct encryption scheme described in section I.1 is
3051acceptable if the encryption key is provided by a completely trustworthy key distribution center (this is the
3052case in the Kerberos model). Such a key would not be acceptable for the purposes of decrypting
3053information from the source that provided it since an attacker might replay information from a prior
3054transaction in the hope of learning information about it.
3055
3056In most cases the other party in a transaction is only imperfectly trustworthy. In these cases both parties
3057SHOULD contribute entropy to the key exchange by means of the <wst:entropy> element.

3058A.1 Ephemeral Encryption Keys

3059The simplest form of key exchange can be found in [WS-Security] for encrypting message data. As
3060described in [WS-Security] and [XML-Encrypt], when data is encrypted, a temporary key can be used to
3061perform the encryption which is, itself, then encrypted using the <xenc:EncryptedKey> element.
3062
3063The illustrates the syntax for encrypting a temporary key using the public key in an issuer name and serial
3064number:
3065 <xenc:EncryptedKey xmlns:xenc="...">
3066 ...
3067 <ds:KeyInfo xmlns:ds="...">
3068 <wsse:SecurityTokenReference xmlns:wsse="...">
3069 <ds:X509IssuerSerial>
3070 <ds:X509IssuerName>
3071 DC=ACMECorp, DC=com
3072 </ds:X509IssuerName>
3073 <ds:X509SerialNumber>12345678</ds:X509SerialNumber>
3074 </ds:X509IssuerSerial>
3075 </wsse:SecurityTokenReference>
3076 </ds:KeyInfo>
3077 ...
3078 </xenc:EncryptedKey>

3079A.2 Requestor-Provided Keys

3080When a request sends a message to an issuer to request a token, the client can provide proposed key
3081material using the <wst:Entropy> element. If the issuer doesn't contribute any key material, this is
3082used as the secret (key). This information is encrypted for the issuer either using

229ws-trust-1.4-os 2 February 2009

230Copyright © OASIS® 1993–2009. All Rights Reserved. Page 77 of 88
3083<xenc:EncryptedKey> or by using a transport security. If the requestor provides key material that the
3084recipient doesn't accept, then the issuer SHUOLD reject the request. Note that the issuer need not return
3085the key provided by the requestor.
3086
3087The following illustrates the syntax of a request for a custom security token and includes a secret that is to
3088be used for the key. In this example the entropy is encrypted for the issuer (if transport security was used
3089for confidentiality then the <wst:Entropy> element would contain a <wst:BinarySecret> element):
3090 <wst:RequestSecurityToken xmlns:wst="...”>
3091 <wst:TokenType>
3092 http://example.org/mySpecialToken
3093 </wst:TokenType>
3094 <wst:RequestType>
3095 http://docs.oasis-open.org/ws-sx/ws-trust/200512/Issue
3096 </wst:RequestType>
3097 <wst:Entropy>
3098 <xenc:EncryptedData xmlns:xenc="...">...</xenc:EncryptedData>
3099 </wst:Entropy>
3100 </wst:RequestSecurityToken>

3101A.3 Issuer-Provided Keys

3102If a requestor fails to provide key material, then issued proof-of-possession tokens contain an issuer-
3103provided secret that is encrypted for the requestor (either using <xenc:EncryptedKey> or by using a
3104transport security).
3105
3106The following illustrates the syntax of a token being returned with an associated proof-of-possession
3107token that is encrypted using the requestor's public key.
3108 <wst:RequestSecurityTokenResponseCollection xmlns:wst="...”>
3109 <wst:RequestSecurityTokenResponse>
3110 <wst:RequestedSecurityToken>
3111 <xyz:CustomToken xmlns:xyz="...">
3112 ...
3113 </xyz:CustomToken>
3114 </wst:RequestedSecurityToken>
3115 <wst:RequestedProofToken>
3116 <xenc:EncryptedKey xmlns:xenc="..." Id="newProof">
3117 ...
3118 </xenc:EncryptedKey>
3119 </wst:RequestedProofToken>
3120 </wst:RequestSecurityTokenResponse>
3121 </wst:RequestSecurityTokenResponseCollection>

3122A.4 Composite Keys

3123The safest form of key exchange/generation is when both the requestor and the issuer contribute to the
3124key material. In this case, the request sends encrypted key material. The issuer then returns additional
3125encrypted key material. The actual secret (key) is computed using a function of the two pieces of data.
3126Ideally this secret is never used and, instead, keys derived are used for message protection.
3127
3128The following example illustrates a server, having received a request with requestor entropy returning its
3129own entropy, which is used in conjunction with the requestor's to generate a key. In this example the
3130entropy is not encrypted because the transport is providing confidentiality (otherwise the
3131<wst:Entropy> element would have an <xenc:EncryptedData> element).
232ws-trust-1.4-os 2 February 2009
233Copyright © OASIS® 1993–2009. All Rights Reserved. Page 78 of 88
 3132 <wst:RequestSecurityTokenResponseCollection xmlns:wst="...”>
3133 <wst:RequestSecurityTokenResponse>
3134 <wst:RequestedSecurityToken>
3135 <xyz:CustomToken xmlns:xyz="...">
3136 ...
3137 </xyz:CustomToken>
3138 </wst:RequestedSecurityToken>
3139 <wst:Entropy>
3140 <wst:BinarySecret>UIH...</wst:BinarySecret>
3141 </wst:Entropy>
3142 </wst:RequestSecurityTokenResponse>
3143 </wst:RequestSecurityTokenResponseCollection>

3144A.5 Key Transfer and Distribution

3145There are also a few mechanisms where existing keys are transferred to other parties.

3146A.5.1 Direct Key Transfer

3147If one party has a token and key and wishes to share this with another party, the key can be directly
3148transferred. This is accomplished by sending an RSTR (either in the body or header) to the other party.
3149The RSTR contains the token and a proof-of-possession token that contains the key encrypted for the
3150recipient.
3151
3152In the following example a custom token and its associated proof-of-possession token are known to party
3153A who wishes to share them with party B. In this example, A is a member in a secure on-line chat
3154session and is inviting B to join the conversation. After authenticating B, A sends B an RSTR. The RSTR
3155contains the token and the key is communicated as a proof-of-possession token that is encrypted for B:
3156 <wst:RequestSecurityTokenResponseCollection xmlns:wst="...”>
3157 <wst:RequestSecurityTokenResponse>
3158 <wst:RequestedSecurityToken>
3159 <xyz:CustomToken xmlns:xyz="...">
3160 ...
3161 </xyz:CustomToken>
3162 </wst:RequestedSecurityToken>
3163 <wst:RequestedProofToken>
3164 <xenc:EncryptedKey xmlns:xenc="..." Id="newProof">
3165 ...
3166 </xenc:EncryptedKey>
3167 </wst:RequestedProofToken>
3168 </wst:RequestSecurityTokenResponse>
3169 </wst:RequestSecurityTokenResponseCollection>

3170A.5.2 Brokered Key Distribution

3171A third party MAY also act as a broker to transfer keys. For example, a requestor may obtain a token and
3172proof-of-possession token from a third-party STS. The token contains a key encrypted for the target
3173service (either using the service's public key or a key known to the STS and target service). The proof-of-
3174possession token contains the same key encrypted for the requestor (similarly this can use public or
3175symmetric keys).
3176
3177In the following example a custom token and its associated proof-of-possession token are returned from a
3178broker B to a requestor R for access to service S. The key for the session is contained within the custom

235ws-trust-1.4-os 2 February 2009

236Copyright © OASIS® 1993–2009. All Rights Reserved. Page 79 of 88
3179token encrypted for S using either a secret known by B and S or using S's public key. The same secret is
3180encrypted for R and returned as the proof-of-possession token:
3181 <wst:RequestSecurityTokenResponseCollection xmlns:wst="...”>
3182 <wst:RequestSecurityTokenResponse>
3183 <wst:RequestedSecurityToken>
3184 <xyz:CustomToken xmlns:xyz="...">
3185 ...
3186 <xenc:EncryptedKey xmlns:xenc="...">
3187 ...
3188 </xenc:EncryptedKey>
3189 ...
3190 </xyz:CustomToken>
3191 </wst:RequestedSecurityToken>
3192 <wst:RequestedProofToken>
3193 <xenc:EncryptedKey Id="newProof">
3194 ...
3195 </xenc:EncryptedKey>
3196 </wst:RequestedProofToken>
3197 </wst:RequestSecurityTokenResponse>
3198 </wst:RequestSecurityTokenResponseCollection>

3199A.5.3 Delegated Key Transfer

3200Key transfer can also take the form of delegation. That is, one party transfers the right to use a key
3201without actually transferring the key. In such cases, a delegation token, e.g. XrML, is created that
3202identifies a set of rights and a delegation target and is secured by the delegating party. That is, one key
3203indicates that another key can use a subset (or all) of its rights. The delegate can provide this token and
3204prove itself (using its own key – the delegation target) to a service. The service, assuming the trust
3205relationships have been established and that the delegator has the right to delegate, can then authorize
3206requests sent subject to delegation rules and trust policies.
3207
3208In this example a custom token is issued from party A to party B. The token indicates that B (specifically
3209B's key) has the right to submit purchase orders. The token is signed using a secret key known to the
3210target service T and party A (the key used to ultimately authorize the requests that B makes to T), and a
3211new session key that is encrypted for T. A proof-of-possession token is included that contains the
3212session key encrypted for B. As a result, B is effectively using A's key, but doesn't actually know the key.
3213 <wst:RequestSecurityTokenResponseCollection xmlns:wst="...”>
3214 <wst:RequestSecurityTokenResponse>
3215 <wst:RequestedSecurityToken>
3216 <xyz:CustomToken xmlns:xyz="...">
3217 ...
3218 <xyz:DelegateTo>B</xyz:DelegateTo>
3219 <xyz:DelegateRights>
3220 SubmitPurchaseOrder
3221 </xyz:DelegateRights>
3222 <xenc:EncryptedKey xmlns:xenc="...">
3223 ...
3224 </xenc:EncryptedKey>
3225 <ds:Signature xmlns:ds="...">...</ds:Signature>
3226 ...
3227 </xyz:CustomToken>
3228 </wst:RequestedSecurityToken>
3229 <wst:RequestedProofToken>
3230 <xenc:EncryptedKey xmlns:xenc="..." Id="newProof">
3231 ...
3232 </xenc:EncryptedKey>

238ws-trust-1.4-os 2 February 2009

239Copyright © OASIS® 1993–2009. All Rights Reserved. Page 80 of 88
 3233 </wst:RequestedProofToken>
3234 </wst:RequestSecurityTokenResponse>
3235 </wst:RequestSecurityTokenResponseCollection>

3236A.5.4 Authenticated Request/Reply Key Transfer

3237In some cases the RST/RSTR mechanism is not used to transfer keys because it is part of a simple
3238request/reply. However, there may be a desire to ensure mutual authentication as part of the key
3239transfer. The mechanisms of [WS-Security] can be used to implement this scenario.
3240
3241Specifically, the sender wishes the following:
3242  Transfer a key to a recipient that they can use to secure a reply
3243  Ensure that only the recipient can see the key
3244  Provide proof that the sender issued the key
3245
3246This scenario could be supported by encrypting and then signing. This would result in roughly the
3247following steps:
3248 1. Encrypt the message using a generated key
3249 2. Encrypt the key for the recipient
3250 3. Sign the encrypted form, any other relevant keys, and the encrypted key
3251
3252However, if there is a desire to sign prior to encryption then the following general process is used:
3253 1. Sign the appropriate message parts using a random key (or ideally a key derived from a random
3254 key)
3255 2. Encrypt the appropriate message parts using the random key (or ideally another key derived from
3256 the random key)
3257 3. Encrypt the random key for the recipient
3258 4. Sign just the encrypted key
3259
3260This would result in a <wsse:Security> header that looks roughly like the following:
3261 <wsse:Security xmlns:wsse="..." xmlns:wsu="..."
3262 xmlns:ds="..." xmlns:xenc="...">
3263 <wsse:BinarySecurityToken wsu:Id="myToken">
3264 ...
3265 </wsse:BinarySecurityToken>
3266 <ds:Signature>
3267 ...signature over #secret using token #myToken...
3268 </ds:Signature>
3269 <xenc:EncryptedKey Id="secret">
3270 ...
3271 </xenc:EncryptedKey>
3272 <xenc:RefrenceList>
3273 ...manifest of encrypted parts using token #secret...
3274 </xenc:RefrenceList>
3275 <ds:Signature>
3276 ...signature over key message parts using token #secret...
3277 </ds:Signature>
3278 </wsse:Security>

3279
241ws-trust-1.4-os 2 February 2009
242Copyright © OASIS® 1993–2009. All Rights Reserved. Page 81 of 88
3280As well, instead of an <xenc:EncryptedKey> element, the actual token could be passed using
3281<xenc:EncryptedData>. The result might look like the following:
3282 <wsse:Security xmlns:wsse="..." xmlns:wsu="..."
3283 xmlns:ds="..." xmlns:xenc="...">
3284 <wsse:BinarySecurityToken wsu:Id="myToken">
3285 ...
3286 </wsse:BinarySecurityToken>
3287 <ds:Signature>
3288 ...signature over #secret or #Esecret using token #myToken...
3289 </ds:Signature>
3290 <xenc:EncryptedData Id="Esecret”>
3291 ...Encrypted version of a token with Id="secret"...
3292 </xenc:EncryptedData>
3293 <xenc:RefrenceList>
3294 ...manifest of encrypted parts using token #secret...
3295 </xenc:RefrenceList>
3296 <ds:Signature>
3297 ...signature over key message parts using token #secret...
3298 </ds:Signature>
3299 </wsse:Security>

3300A.6 Perfect Forward Secrecy

3301In some situations it is desirable for a key exchange to have the property of perfect forward secrecy. This
3302means that it is impossible to reconstruct the shared secret even if the private keys of the parties are
3303disclosed.
3304
3305The most straightforward way to attain perfect forward secrecy when using asymmetric key exchange is
3306to dispose of one's key exchange key pair periodically (or even after every key exchange), replacing it
3307with a fresh one. Of course, a freshly generated public key must still be authenticated (using any of the
3308methods normally available to prove the identity of a public key's owner).
3309
3310The perfect forward secrecy property MAY be achieved by specifying a <wst:entropy> element that
3311contains an <xenc:EncryptedKey> that is encrypted under a public key pair created for use in a single
3312key agreement. The public key does not require authentication since it is only used to provide additional
3313entropy. If the public key is modified, the key agreement will fail. Care should be taken, when using this
3314method, to ensure that the now-secret entropy exchanged via the <wst:entropy> element is not
3315revealed elsewhere in the protocol (since such entropy is often assumed to be publicly revealed plaintext,
3316and treated accordingly).
3317
3318Although any public key scheme might be used to achieve perfect forward secrecy (in either of the above
3319methods) it is generally desirable to use an algorithm that allows keys to be generated quickly. The Diffie-
3320Hellman key exchange is often used for this purpose since generation of a key only requires the
3321generation of a random integer and calculation of a single modular exponent.

244ws-trust-1.4-os 2 February 2009

245Copyright © OASIS® 1993–2009. All Rights Reserved. Page 82 of 88
3322B. WSDL
3323The WSDL below does not fully capture all the possible message exchange patterns, but captures the
3324typical message exchange pattern as described in this document.
3325 <?xml version="1.0"?>
3326 <wsdl:definitions
3327 targetNamespace="http://docs.oasis-open.org/ws-sx/ws-
3328 trust/200512/wsdl"
3329 xmlns:tns="http://docs.oasis-open.org/ws-sx/ws-trust/200512/wsdl"
3330 xmlns:wst="http://docs.oasis-open.org/ws-sx/ws-trust/200512"
3331 xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
3332 xmlns:xs="http://www.w3.org/2001/XMLSchema"
3333 xmlns:wsam="http://www.w3.org/2007/05/addressing/metadata"
3334 >
3335 <!-- this is the WS-I BP-compliant way to import a schema -->
3336 <wsdl:types>
3337 <xs:schema>
3338 <xs:import
3339 namespace="http://docs.oasis-open.org/ws-sx/ws-trust/200512"
3340 schemaLocation="http://docs.oasis-open.org/ws-sx/ws-trust/200512/ws-
3341 trust.xsd"/>
3342 </xs:schema>
3343 </wsdl:types>
3344
3345 <!-- WS-Trust defines the following GEDs -->
3346 <wsdl:message name="RequestSecurityTokenMsg">
3347 <wsdl:part name="request" element="wst:RequestSecurityToken" />
3348 </wsdl:message>
3349 <wsdl:message name="RequestSecurityTokenResponseMsg">
3350 <wsdl:part name="response"
3351 element="wst:RequestSecurityTokenResponse" />
3352 </wsdl:message>
3353 <wsdl:message name="RequestSecurityTokenCollectionMsg">
3354 <wsdl:part name="requestCollection"
3355 element="wst:RequestSecurityTokenCollection"/>
3356 </wsdl:message>
3357 <wsdl:message name="RequestSecurityTokenResponseCollectionMsg">
3358 <wsdl:part name="responseCollection"
3359 element="wst:RequestSecurityTokenResponseCollection"/>
3360 </wsdl:message>
3361
3362 <!-- This portType an example of a Requestor (or other) endpoint that
3363 Accepts SOAP-based challenges from a Security Token Service -->
3364 <wsdl:portType name="WSSecurityRequestor">
3365 <wsdl:operation name="Challenge">
3366 <wsdl:input message="tns:RequestSecurityTokenResponseMsg"/>
3367 <wsdl:output message="tns:RequestSecurityTokenResponseMsg"/>
3368 </wsdl:operation>
3369 </wsdl:portType>
3370
3371 <!-- This portType is an example of an STS supporting full protocol -->
3372 <wsdl:portType name="SecurityTokenService">
3373 <wsdl:operation name="Cancel">
3374 <wsdl:input wsam:Action="http://docs.oasis-open.org/ws-sx/ws-
3375 trust/200512/RST/Cancel" message="tns:RequestSecurityTokenMsg"/>
3376 <wsdl:output wsam:Action="http://docs.oasis-open.org/ws-sx/ws-
3377 trust/200512/RSTR/CancelFinal" message="tns:RequestSecurityTokenResponseMsg"/>
3378 </wsdl:operation>

247ws-trust-1.4-os 2 February 2009

248Copyright © OASIS® 1993–2009. All Rights Reserved. Page 83 of 88
3379 <wsdl:operation name="Issue">
3380 <wsdl:input wsam:Action="http://docs.oasis-open.org/ws-sx/ws-
3381 trust/200512/RST/Issue" message="tns:RequestSecurityTokenMsg"/>
3382 <wsdl:output wsam:Action="http://docs.oasis-open.org/ws-sx/ws-
3383 trust/200512/RSTRC/IssueFinal"
3384 message="tns:RequestSecurityTokenResponseCollectionMsg"/>
3385 </wsdl:operation>
3386 <wsdl:operation name="Renew">
3387 <wsdl:input wsam:Action="http://docs.oasis-open.org/ws-sx/ws-
3388 trust/200512/RST/Renew" message="tns:RequestSecurityTokenMsg"/>
3389 <wsdl:output wsam:Action="http://docs.oasis-open.org/ws-sx/ws-
3390 trust/200512/RSTR/RenewFinal" message="tns:RequestSecurityTokenResponseMsg"/>
3391 </wsdl:operation>
3392 <wsdl:operation name="Validate">
3393 <wsdl:input wsam:Action="http://docs.oasis-open.org/ws-sx/ws-
3394 trust/200512/RST/Validate" message="tns:RequestSecurityTokenMsg"/>
3395 <wsdl:output wsam:Action=http://docs.oasis-open.org/ws-sx/ws-
3396 trust/200512/RSTR/ValidateFinal
3397 message="tns:RequestSecurityTokenResponseMsg"/>
3398 </wsdl:operation>
3399 <wsdl:operation name="KeyExchangeToken">
3400 <wsdl:input wsam:Action="http://docs.oasis-open.org/ws-sx/ws-
3401 trust/200512/RST/KET" message="tns:RequestSecurityTokenMsg"/>
3402 <wsdl:output wsam:Action="http://docs.oasis-open.org/ws-sx/ws-
3403 trust/200512/RSTR/KETFinal" message="tns:RequestSecurityTokenResponseMsg"/>
3404 </wsdl:operation>
3405 <wsdl:operation name="RequestCollection">
3406 <wsdl:input message="tns:RequestSecurityTokenCollectionMsg"/>
3407 <wsdl:output message="tns:RequestSecurityTokenResponseCollectionMsg"/>
3408 </wsdl:operation>
3409 </wsdl:portType>
3410
3411 <!-- This portType is an example of an endpoint that accepts
3412 Unsolicited RequestSecurityTokenResponse messages -->
3413 <wsdl:portType name="SecurityTokenResponseService">
3414 <wsdl:operation name="RequestSecurityTokenResponse">
3415 <wsdl:input message="tns:RequestSecurityTokenResponseMsg"/>
3416 </wsdl:operation>
3417 </wsdl:portType>
3418
3419 </wsdl:definitions>
3420

250ws-trust-1.4-os 2 February 2009

251Copyright © OASIS® 1993–2009. All Rights Reserved. Page 84 of 88
3421C. Acknowledgements
3422The following individuals have participated in the creation of this specification and are gratefully
3423acknowledged:
3424Original Authors of the initial contribution:
3425 Steve Anderson, OpenNetwork
3426 Jeff Bohren, OpenNetwork
3427 Toufic Boubez, Layer 7
3428 Marc Chanliau, Computer Associates
3429 Giovanni Della-Libera, Microsoft
3430 Brendan Dixon, Microsoft
3431 Praerit Garg, Microsoft
3432 Martin Gudgin (Editor), Microsoft
3433 Phillip Hallam-Baker, VeriSign
3434 Maryann Hondo, IBM
3435 Chris Kaler, Microsoft
3436 Hal Lockhart, Oracle Corporation
3437 Robin Martherus, Oblix
3438 Hiroshi Maruyama, IBM
3439 Anthony Nadalin (Editor), IBM
3440 Nataraj Nagaratnam, IBM
3441 Andrew Nash, Reactivity
3442 Rob Philpott, RSA Security
3443 Darren Platt, Ping Identity
3444 Hemma Prafullchandra, VeriSign
3445 Maneesh Sahu, Actional
3446 John Shewchuk, Microsoft
3447 Dan Simon, Microsoft
3448 Davanum Srinivas, Computer Associates
3449 Elliot Waingold, Microsoft
3450 David Waite, Ping Identity
3451 Doug Walter, Microsoft
3452 Riaz Zolfonoon, RSA Security
3453
3454Original Acknowledgments of the initial contribution:
3455 Paula Austel, IBM
3456 Keith Ballinger, Microsoft
3457 Bob Blakley, IBM
3458 John Brezak, Microsoft
3459 Tony Cowan, IBM
3460 Cédric Fournet, Microsoft
3461 Vijay Gajjala, Microsoft
3462 HongMei Ge, Microsoft
3463 Satoshi Hada, IBM
3464 Heather Hinton, IBM
3465 Slava Kavsan, RSA Security
3466 Scott Konersmann, Microsoft
3467 Leo Laferriere, Computer Associates
253ws-trust-1.4-os 2 February 2009
254Copyright © OASIS® 1993–2009. All Rights Reserved. Page 85 of 88
3468 Paul Leach, Microsoft
3469 Richard Levinson, Computer Associates
3470 John Linn, RSA Security
3471 Michael McIntosh, IBM
3472 Steve Millet, Microsoft
3473 Birgit Pfitzmann, IBM
3474 Fumiko Satoh, IBM
3475 Keith Stobie, Microsoft
3476 T.R. Vishwanath, Microsoft
3477 Richard Ward, Microsoft
3478 Hervey Wilson, Microsoft
3479
3480TC Members during the development of this specification:
3481Don Adams, Tibco Software Inc.
3482Jan Alexander, Microsoft Corporation
3483Steve Anderson, BMC Software
3484Donal Arundel, IONA Technologies
3485Howard Bae, Oracle Corporation
3486Abbie Barbir, Nortel Networks Limited
3487Charlton Barreto, Adobe Systems
3488Mighael Botha, Software AG, Inc.
3489Toufic Boubez, Layer 7 Technologies Inc.
3490Norman Brickman, Mitre Corporation
3491Melissa Brumfield, Booz Allen Hamilton
3492Lloyd Burch, Novell
3493Geoff Bullen, Microsoft Corporation
3494Scott Cantor, Internet2
3495Greg Carpenter, Microsoft Corporation
3496Steve Carter, Novell
3497Ching-Yun (C.Y.) Chao, IBM
3498Martin Chapman, Oracle Corporation
3499Kate Cherry, Lockheed Martin
3500Henry (Hyenvui) Chung, IBM
3501Luc Clement, Systinet Corp.
3502Paul Cotton, Microsoft Corporation
3503Glen Daniels, Sonic Software Corp.
3504Peter Davis, Neustar, Inc.
3505Martijn de Boer, SAP AG
3506Duane DeCouteau, Veterans Health Administration
3507Werner Dittmann, Siemens AG
3508Abdeslem DJAOUI, CCLRC-Rutherford Appleton Laboratory
3509Fred Dushin, IONA Technologies
3510Petr Dvorak, Systinet Corp.

256ws-trust-1.4-os 2 February 2009

257Copyright © OASIS® 1993–2009. All Rights Reserved. Page 86 of 88
3511Colleen Evans, Microsoft Corporation
3512Ruchith Fernando, WSO2
3513Mark Fussell, Microsoft Corporation
3514Vijay Gajjala, Microsoft Corporation
3515Marc Goodner, Microsoft Corporation
3516Hans Granqvist, VeriSign
3517Martin Gudgin, Microsoft Corporation
3518Tony Gullotta, SOA Software Inc.
3519Jiandong Guo, Sun Microsystems
3520Phillip Hallam-Baker, VeriSign
3521Patrick Harding, Ping Identity Corporation
3522Heather Hinton, IBM
3523Frederick Hirsch, Nokia Corporation
3524Jeff Hodges, Neustar, Inc.
3525Will Hopkins, Oracle Corporation
3526Alex Hristov, Otecia Incorporated
3527John Hughes, PA Consulting
3528Diane Jordan, IBM
3529Venugopal K, Sun Microsystems
3530Chris Kaler, Microsoft Corporation
3531Dana Kaufman, Forum Systems, Inc.
3532Paul Knight, Nortel Networks Limited
3533Ramanathan Krishnamurthy, IONA Technologies
3534Christopher Kurt, Microsoft Corporation
3535Kelvin Lawrence, IBM
3536Hubert Le Van Gong, Sun Microsystems
3537Jong Lee, Oracle Corporation
3538Rich Levinson, Oracle Corporation
3539Tommy Lindberg, Dajeil Ltd.
3540Mark Little, JBoss Inc.
3541Hal Lockhart, Oracle Corporation
3542Mike Lyons, Layer 7 Technologies Inc.
3543Eve Maler, Sun Microsystems
3544Ashok Malhotra, Oracle Corporation
3545Anand Mani, CrimsonLogic Pte Ltd
3546Jonathan Marsh, Microsoft Corporation
3547Robin Martherus, Oracle Corporation
3548Miko Matsumura, Infravio, Inc.
3549Gary McAfee, IBM
3550Michael McIntosh, IBM
3551John Merrells, Sxip Networks SRL
3552Jeff Mischkinsky, Oracle Corporation
259ws-trust-1.4-os 2 February 2009
260Copyright © OASIS® 1993–2009. All Rights Reserved. Page 87 of 88
3553Prateek Mishra, Oracle Corporation
3554Bob Morgan, Internet2
3555Vamsi Motukuru, Oracle Corporation
3556Raajmohan Na, EDS
3557Anthony Nadalin, IBM
3558Andrew Nash, Reactivity, Inc.
3559Eric Newcomer, IONA Technologies
3560Duane Nickull, Adobe Systems
3561Toshihiro Nishimura, Fujitsu Limited
3562Rob Philpott, RSA Security
3563Denis Pilipchuk, Oracle Corporation
3564Darren Platt, Ping Identity Corporation
3565Martin Raepple, SAP AG
3566Nick Ragouzis, Enosis Group LLC
3567Prakash Reddy, CA
3568Alain Regnier, Ricoh Company, Ltd.
3569Irving Reid, Hewlett-Packard
3570Bruce Rich, IBM
3571Tom Rutt, Fujitsu Limited
3572Maneesh Sahu, Actional Corporation
3573Frank Siebenlist, Argonne National Laboratory
3574Joe Smith, Apani Networks
3575Davanum Srinivas, WSO2
3576David Staggs, Veterans Health Administration
3577Yakov Sverdlov, CA
3578Gene Thurston, AmberPoint
3579Victor Valle, IBM
3580Asir Vedamuthu, Microsoft Corporation
3581Greg Whitehead, Hewlett-Packard
3582Ron Williams, IBM
3583Corinna Witt, Oracle Corporation
3584Kyle Young, Microsoft Corporation
3585

262ws-trust-1.4-os 2 February 2009

263Copyright © OASIS® 1993–2009. All Rights Reserved. Page 88 of 88