idnits 2.17.1
draft-richer-oauth-xml-01.txt:
Checking boilerplate required by RFC 5378 and the IETF Trust (see
https://trustee.ietf.org/license-info):
----------------------------------------------------------------------------
No issues found here.
Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt:
----------------------------------------------------------------------------
No issues found here.
Checking nits according to https://www.ietf.org/id-info/checklist :
----------------------------------------------------------------------------
No issues found here.
Miscellaneous warnings:
----------------------------------------------------------------------------
== The copyright year in the IETF Trust and authors Copyright Line does not
match the current year
== Using lowercase 'not' together with uppercase 'MUST', 'SHALL', 'SHOULD',
or 'RECOMMENDED' is not an accepted usage according to RFC 2119. Please
use uppercase 'NOT' together with RFC 2119 keywords (if that is what you
mean).
Found 'SHOULD not' in this paragraph:
This extension does not define a required namespace for the OAuth
XML encoding, and a supporting server SHOULD not use a namespace.
-- The document date (April 23, 2012) is 4385 days in the past. Is this
intentional?
Checking references for intended status: Experimental
----------------------------------------------------------------------------
== Missing Reference: 'REF' is mentioned on line 147, but not defined
== Outdated reference: A later version (-31) exists of
draft-ietf-oauth-v2-23
** Obsolete normative reference: RFC 4627 (Obsoleted by RFC 7158, RFC 7159)
Summary: 1 error (**), 0 flaws (~~), 4 warnings (==), 1 comment (--).
Run idnits with the --verbose option for more detailed information about
the items above.
--------------------------------------------------------------------------------
2 Network Working Group J. Richer, Ed.
3 Internet-Draft The MITRE Corporation
4 Intended status: Experimental April 23, 2012
5 Expires: October 25, 2012
7 Alternate Encoding for OAuth 2 Token Responses
8 draft-richer-oauth-xml-01
10 Abstract
12 This document describes a method of representing the JSON structured
13 responses from the OAuth 2 Token Endpoint into XML and form encoded
14 responses.
16 Requirements Language
18 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
19 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
20 document are to be interpreted as described in RFC 2119 [RFC2119].
22 Status of this Memo
24 This Internet-Draft is submitted in full conformance with the
25 provisions of BCP 78 and BCP 79.
27 Internet-Drafts are working documents of the Internet Engineering
28 Task Force (IETF). Note that other groups may also distribute
29 working documents as Internet-Drafts. The list of current Internet-
30 Drafts is at http://datatracker.ietf.org/drafts/current/.
32 Internet-Drafts are draft documents valid for a maximum of six months
33 and may be updated, replaced, or obsoleted by other documents at any
34 time. It is inappropriate to use Internet-Drafts as reference
35 material or to cite them other than as "work in progress."
37 This Internet-Draft will expire on October 25, 2012.
39 Copyright Notice
41 Copyright (c) 2012 IETF Trust and the persons identified as the
42 document authors. All rights reserved.
44 This document is subject to BCP 78 and the IETF Trust's Legal
45 Provisions Relating to IETF Documents
46 (http://trustee.ietf.org/license-info) in effect on the date of
47 publication of this document. Please review these documents
48 carefully, as they describe your rights and restrictions with respect
49 to this document. Code Components extracted from this document must
50 include Simplified BSD License text as described in Section 4.e of
51 the Trust Legal Provisions and are provided without warranty as
52 described in the Simplified BSD License.
54 Table of Contents
56 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3
57 2. Content Negotiation . . . . . . . . . . . . . . . . . . . . . 3
58 2.1. Form Parameter . . . . . . . . . . . . . . . . . . . . . . 3
59 2.2. Accept Header . . . . . . . . . . . . . . . . . . . . . . 4
60 3. Encoding . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
61 3.1. XML . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
62 3.2. Form Encoding . . . . . . . . . . . . . . . . . . . . . . 5
63 4. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
64 4.1. Standard OAuth Token . . . . . . . . . . . . . . . . . . . 5
65 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 6
66 6. Security Considerations . . . . . . . . . . . . . . . . . . . 6
67 7. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 6
68 8. Normative References . . . . . . . . . . . . . . . . . . . . . 6
69 Appendix A. General XML Encoding Rules . . . . . . . . . . . . . 7
70 A.1. Objects and Members . . . . . . . . . . . . . . . . . . . 7
71 A.2. Type Identifiers . . . . . . . . . . . . . . . . . . . . . 7
72 A.3. Strings and Numbers . . . . . . . . . . . . . . . . . . . 7
73 A.4. Arrays . . . . . . . . . . . . . . . . . . . . . . . . . . 8
74 A.5. Namespace . . . . . . . . . . . . . . . . . . . . . . . . 8
75 A.6. Information Loss . . . . . . . . . . . . . . . . . . . . . 8
76 A.7. Examples . . . . . . . . . . . . . . . . . . . . . . . . . 8
77 Appendix B. General Form Encoding Rules . . . . . . . . . . . . . 10
78 B.1. Objects and Members . . . . . . . . . . . . . . . . . . . 10
79 B.2. Strings and Numbers . . . . . . . . . . . . . . . . . . . 11
80 B.3. Arrays . . . . . . . . . . . . . . . . . . . . . . . . . . 11
81 B.4. Information Loss . . . . . . . . . . . . . . . . . . . . . 11
82 B.5. Examples . . . . . . . . . . . . . . . . . . . . . . . . . 12
83 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 12
85 1. Introduction
87 The OAuth 2 Protocol [I-D.ietf-oauth-v2] defines a standard JSON
88 [RFC4627] encoding for structured return values from the Token
89 Endpoint in section 5.1 of the specification when used with most
90 flows. Additionally, the OAuth 2 specification defines a URI
91 fragment encoding for tokens issued from the Authorization Endpoint
92 in the Implicit Grant flow using "application/x-www-form-url-encoded"
93 encoding in section 4.2.2.
95 When OAuth is being used as part of an API that is built around
96 different encoding technologies, such as XML [W3C.CR-xml11-20021015],
97 it is not desirable for application developers to have to parse JSON
98 encoded objects just to handle authorization step. This extension
99 describes a means for the client to request an alternative format for
100 respones from the Token Endpoint and methods for the Token Endpoint
101 to encode its responses as XML documents and form-encoded parameters.
102 This extension makes no claim on responses from the Authorization
103 Endpoint or other endpoints defined in OAuth2, its extensions, or
104 profiles.
106 2. Content Negotiation
108 To request an alternate encoding from the OAuth 2 Token Endpoint, the
109 client indicates the desired encoding through one of the following
110 methods. Authorization Servers SHOULD support all methods but MUST
111 support at least one so that supporting clients can be configured to
112 request the right format. Particular formats available from a given
113 Authorization Server MUST be documented and MAY be discoverable
114 through some other means.
116 2.1. Form Parameter
118 In this method, the client sends the following OPTIONAL form
119 parameter in any request to the Token Endpoint to indicate its
120 encoding preference.
122 format
123 OPTIONAL. The format parameter specifies the client's desired
124 format for responses from the token endpoint. Valid values are
125 "json", "xml", and "form", though other extensions MAY define
126 other valid values.
128 If the value of the parameter is set to "xml" and the authorization
129 server supports XML encoding, the authorization server MUST respond
130 to a valid token request with an HTTP 200 response, a content type of
131 "application/xml", and HTTP body content as described in Section 3.1.
133 If the value of the parameter is set to "form" and the authorization
134 server supports form encoding, the authorization server MUST respond
135 to a valid token request with an HTTP 200 response, a content type of
136 "application/x-www-form-encoded", and an HTTP body content as
137 described in Section 3.2.
139 If the value of this parameter is "json" or the parameter is omitted
140 entirely, the authorization server MUST respond to a valid token
141 reqeust as defined in OAuth 2 [I-D.ietf-oauth-v2].
143 2.2. Accept Header
145 In this method, the client sends an HTTP "Accept" header to indicate
146 to the Authorization Server what encodings it prefers as described in
147 the HTTP specification [REF].
149 If the value of the header includes "application/xml" and the
150 authorization server supports XML encoding, the authorization server
151 MUST respond to a valid token request with an HTTP 200 response, a
152 content type of "application/xml", and HTTP body content as described
153 in Section 3.1.
155 If the value of the header includes "application/x-www-form-encoded"
156 and the authorization server supports form encoding, the
157 authorization server MUST respond to a valid token request with an
158 HTTP 200 response, a content type of
159 "application/x-www-form-url-encoded", and an HTTP body content as
160 described in Section 3.2.
162 If the value of the header is "application/json" or no accept
163 preference is otherwise given, the authorization server MUST respond
164 to a valid token reqeust as defined in OAuth 2 [I-D.ietf-oauth-v2].
166 3. Encoding
168 All alternate forms of encoding MUST account for all elements of a
169 token as specified in OAuth2.
171 3.1. XML
173 For a full description of the transformation rules, see Appendix A
174 (Appendix A).
176 The response MUST use a single XML root element with a node name of
177 "oauth" to represent the anonymous root JSON object specified in the
178 OAuth JSON response.
180 The response SHOULD NOT include a default namespace.
182 All elements of the JSON object MUST be encoded as XML elements, with
183 values encoded as CDATA within each element.
185 3.2. Form Encoding
187 For a full description of the transformation rules, see Appendix B
188 (Appendix B).
190 The form encoding MUST follow the same encoding rules as defined in
191 Section 4.2.2 of OAuth2.
193 All values of the JSON response MUST be encoded as key-value pairs.
195 4. Examples
197 Below are examples of encoding different OAuth JSON objects with XML.
198 All line breaks are for display purposes only.
200 4.1. Standard OAuth Token
202 A standard OAuth JSON-encoded token response (example from OAuth2
203 Core):
205 HTTP/1.1 200 OK
206 Content-Type: application/json;charset=UTF-8
207 Cache-Control: no-store
208 Pragma: no-cache
210 {
211 "access_token":"2YotnFZFEjr1zCsicMWpAA",
212 "token_type":"example",
213 "expires_in":3600,
214 "refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA",
215 "example_parameter":"example_value"
216 }
218 Can be encoded in as the following XML response document:
220 HTTP/1.1 200 OK
221 Content-Type: application/xml
222 Cache-Control: no-store
224
225 2YotnFZFEjr1zCsicMWpAA
226 example
227 3600
228 tGzv3JOkF0XG5Qx2TlKWIA
229 example_value
230
232 The same response can be encoded in form encoding a follows:
234 HTTP/1.2 200 OK
235 Content-Type: application/x-www-form-encoded
236 Cache-Control: no-store
238 access_token=2YotnFZFEjr1zCsicMWpAA&token_type=example&
239 expires_in=3600&refresh_token=tGzv3JOkF0XG5Qx2TlKWIA&
240 example_parameter=example_value
242 5. IANA Considerations
244 This document makes no request of IANA.
246 6. Security Considerations
248 There are no additional security considerations.
250 7. Acknowledgements
252 Thanks to Eve Maler, Joseph Holsten, Tim Brody, and the OAuth Working
253 Group for feedback.
255 8. Normative References
257 [I-D.ietf-oauth-v2]
258 Hammer-Lahav, E., Recordon, D., and D. Hardt, "The OAuth
259 2.0 Authorization Protocol", draft-ietf-oauth-v2-23 (work
260 in progress), January 2012.
262 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
263 Requirement Levels", BCP 14, RFC 2119, March 1997.
265 [RFC4627] Crockford, D., "The application/json Media Type for
266 JavaScript Object Notation (JSON)", RFC 4627, July 2006.
268 [W3C.CR-xml11-20021015]
269 Cowan, J., "Extensible Markup Language (XML) 1.1", W3C
270 CR CR-xml11-20021015, October 2002.
272 Appendix A. General XML Encoding Rules
274 This Appendix defines encodings for different parts of the JSON data
275 model in XML equivalents to facilitate structured extensions to the
276 OAuth2 JSON token response. Since this JSON response MAY include
277 elements such as JSON objects or arrays, a server wishing to support
278 such extended responses and XML encoding MUST use these encoding
279 rules to translate them.
281 A.1. Objects and Members
283 JSON objects SHALL be encoded by using XML Elements. The object
284 itself SHALL be represented by the root elment of an XML subtree.
285 All members of the object SHALL be represented by sub-elements of the
286 root element. The key of the member pair SHALL be the node name of
287 the XML Element, and the value of the member pair SHALL be encoded as
288 the content of the XML Element.
290 A.2. Type Identifiers
292 All elements MAY have an OPTIONAL "type" attribute, which has a valid
293 value of "object", "string", "number", or "array". These attributes
294 can be used to differentiate between otherwise potentially ambiguous
295 encodings (Appendix A.6), though the most common cases will not need
296 them.
298 A.3. Strings and Numbers
300 Strings and numbers SHALL be encoded as CDATA within their enclosing
301 element. These values MUST be properly escaped XML CDATA, and MAY be
302 represented using <[CDATA[ ... ]]> encoding.
304 A.4. Arrays
306 Arrays SHALL be represented using repeated, sibling XML Element nodes
307 (nodes with the same node name). The order of the array is encoded
308 using document order of the array elements.
310 A.5. Namespace
312 This extension does not define a required namespace for the OAuth XML
313 encoding, and a supporting server SHOULD not use a namespace.
315 A.6. Information Loss
317 This encoding scheme is intended to give a clear an intuitive mapping
318 between JSON and XML data structures. However, the mapping between
319 the two formats is not exact and some information loss may occur, and
320 round-trip translation between the two formats MUST NOT be depended
321 upon.
323 1. Both strings and numbers (Appendix A.3) in JSON are represented
324 as CDATA in XML. Without type identifiers (Appendix A.2) there
325 is no clear way to differentiate between the two in the XML
326 encoding.
328 2. Arrays (Appendix A.4) in JSON are represented by repeated
329 elements in XML. There is therefore no reliable way to
330 distinguish between a single-element array and a standalone
331 string or number value in the XML encoding, as both would be
332 encoded the same way.
334 A.7. Examples
336 Line breaks are for display purposes only.
338 The example above, with type attributes (Appendix A.2) in place:
340 HTTP/1.1 200 OK
341 Content-Type: application/xml
342 Cache-Control: no-store
344
345 2YotnFZFEjr1zCsicMWpAA
346 example
347 3600
348 tGzv3JOkF0XG5Qx2TlKWIA
349 example_value
350
351 This example uses both objects and arrays to support a complicated,
352 fictional example extension to the OAuth protocol:
354 HTTP/1.1 200 OK
355 Content-Type: application/json
356 Cache-Control: no-store
358 {
359 "access_token":"2YotnFZFEjr1zCsicMWpAA",
360 "token_type":"example",
361 "expires_in":3600,
362 "refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA",
363 "ext_value": "extension",
364 "ext_list": [ 1, 2, "three" ],
365 "ext_object": {
366 "member1": "value1",
367 "memberlist": [ "A", "B", "C"],
368 "member3": 3,
369 "memberobj": {
370 "a": "first",
371 "b": "second",
372 "c": "third"
373 }
374 }
375 }
377 The above is encoded into XML as follows (without using type
378 attributes):
380 HTTP/1.1 200 OK
381 Content-Type: application/xml
382 Cache-Control: no-store
384
385 2YotnFZFEjr1zCsicMWpAA
386 example
387 3600
388 tGzv3JOkF0XG5Qx2TlKWIA
389 extension
390 1
391 2
392 three
393
394 value1
395 A
396 B
397 C
398 3
399
400 first
401 second
402 third
403
404
405
407 Appendix B. General Form Encoding Rules
409 This Appendix defines encodings for different parts of the JSON data
410 model in form encoded equivalents to facilitate structured extensions
411 to the OAuth2 JSON token response. Since this JSON response MAY
412 include elements such as JSON objects or arrays, a server wishing to
413 support such extended responses and form encoding MUST use these
414 encoding rules to translate them. These encoding rules MAY be used
415 to extend the response of the Authorization Endpoint in the Implicit
416 flow.
418 B.1. Objects and Members
420 JSON objects SHALL be represented by encoding all members as separate
421 form parameters. Sub-objects SHALL be encoded by a dot-notation
422 syntax, with the member name of a sub-object being appended to the
423 name of its containing object member, separated by a single period.
425 B.2. Strings and Numbers
427 All String and Number values SHALL be encoded as simple string
428 values.
430 B.3. Arrays
432 Arrays SHALL be encoded by repeating the member name for each value
433 in the array. The order of the array is encoded by the presentation
434 order of the values in the response.
436 B.4. Information Loss
438 This encoding scheme is intended to give a clear an intuitive mapping
439 between JSON and form encoded data structures. However, the mapping
440 between the two formats is not exact and some information loss may
441 occur, and round-trip translation between the two formats MUST NOT be
442 depended upon.
444 1. Both strings and numbers (Appendix B.2) in JSON are represented
445 as strings in the form encoding, and there is no clear way to
446 differentiate between the two in the form encoding.
448 2. Arrays (Appendix B.3) in JSON are represented by repeated
449 elements in the form encoding. There is therefore no reliable
450 way to distinguish between a single-element array and a
451 standalone string or number value in the form encoding, as both
452 would be encoded the same way.
454 B.5. Examples
456 This example encodes the fictionally extended OAuth token response
457 above. Line breaks are for display purposes only.
459 HTTP/1.1 200 OK
460 Content-Type: application/x-www-form-encoded
461 Cache-Control: no-store
463 access_token=2YotnFZFEjr1zCsicMWpAA&token_type=example&
464 expires_in=3600&refresh_token=tGzv3JOkF0XG5Qx2TlKWIA&
465 ext_value=extension&ext_list=1&ext_list=2&ext_list=three&
466 ext_object.member1=value1&ext_object.memberlist=A&
467 ext_object.memberlist=B&ext_object.memberlist=C&
468 ext_object.member3=3&ext_object.memberobj.a=first&
469 ext_object.memberobj.b=second&ext_object.memberobj.c=third
471 Author's Address
473 Justin Richer (editor)
474 The MITRE Corporation
476 Email: jricher@mitre.org