Subject: [OAUTH-WG] Adam Roach's Discuss on draft-ietf-oauth-token-exchange-16: (with DISCUSS and COMMENT)

From: Adam Roach <[email-masked]>
Date: Tue, 20 Nov 2018 15:39:33 -0800

Adam Roach has entered the following ballot position for
draft-ietf-oauth-token-exchange-16: Discuss

When responding, please keep the subject line intact and reply to all
email addresses included in the To and CC lines. (Feel free to cut this
introductory paragraph, however.)

Please refer to https://www.ietf.org/iesg/statement/discuss-criteria.html
for more information about IESG DISCUSS and COMMENT positions.

The document, along with other ballot positions, can be found here:
https://datatracker.ietf.org/doc/draft-ietf-oauth-token-exchange/

----------------------------------------------------------------------
DISCUSS:
----------------------------------------------------------------------

Thanks to everyone who worked on this document. I have a blocking issue that
should be easy to resolve, and a handful of more minor issues.

§2.1:

>  The client makes a token exchange request to the token endpoint with
>  an extension grant type by including the following parameters using
>  the "application/x-www-form-urlencoded" format

This document needs a normative citation for this media type.

My suggestion would be to cite REC-html5-20141028 section 4.10.22.6, as this
appears to be the most recent stable description of how to encode this media
type. I'd love to hear rationale behind other citations being more appropriate,
since I'm not entirely happy with the one I suggest above (given that it's been
superseded by HTML 5.2); but every other plausible citation I can find is even
less palatable (with HTML 5.2 itself having the drawback of not actually
defining how to encode the media type, instead pointing to an unstable,
unversioned document).

----------------------------------------------------------------------
COMMENT:
----------------------------------------------------------------------

Abstract:

>  This specification defines a protocol for an HTTP- and JSON- based

Nit: "...JSON-based..."

---------------------------------------------------------------------------

§1.1:

>  impersonates principal B, then in so far as any entity receiving such

Nit: "insofar"

---------------------------------------------------------------------------

§2.1:

>  The client makes a token exchange request to the token endpoint with
>  an extension grant type by including the following parameters using
>  the "application/x-www-form-urlencoded" format with a character
>  encoding of UTF-8 in the HTTP request entity-body:

I think there's an implication here that POST is used, but that probably needs
to be made explicit.

---------------------------------------------------------------------------

§2.2.1:

>  response using the "application/json" media type, as specified by
>  [RFC7159], and an HTTP 200 status code.  The parameters are

RFC 7159 has been replaced by RFC 8259.

---------------------------------------------------------------------------

§3:

>  urn:ietf:params:oauth:token-type:refresh_token
>     Indicates that the token is an OAuth 2.0 refreshe token issued by

nit: "refresh"

---

From: Brian Campbell <[email-masked]>
Date: Wed, 28 Nov 2018 06:19:47 -0700

Thank you for the review, Adam. I do sincerely hope that your time with the
document didn't drive you to drink (too much anyway). Please see below for
inline comments/responses.

> https://datatracker.ietf.org/doc/draft-ietf-oauth-token-exchange/

What about a pointer to RFC6749's Appendix B. on the "Use of
application/x-www-form-urlencoded Media Type"
<https://tools.ietf.org/html/rfc6749?#appendix-B>? I had admittedly forgot
about it until looking back at the original OAuth 2.0 document as a result
of you raising this DISCUSS to see what citation was used there.

Despite citing an older HTML document I think the few paragraphs there do a
nice job of explaining the situation in a pragmatic and actionable way.
And as the original OAuth 2.0 Authorization Framework is responsible for
the use of "application/x-www-form-urlencoded" in extensions like this
token exchange, it seems fitting to point back to it.

I'm happy to cite REC-html5-20141028 section 4.10.22.6, if you feel that's
more appropriate. But wanted to throw that other idea out there to see if
you find that any more palatable.

Will fix.

This will be fixed insofar as you are right.

> I think there's an implication here that POST is used, but that probably

The use of POST is effectively inherited by token exchange utilizing
an extension
grant <https://tools.ietf.org/html/rfc6749#section-4.5> via the token
endpoint <https://tools.ietf.org/html/rfc6749#section-3.2> where the
'client MUST use the HTTP "POST" method when making access token requests'.

But there's no harm in this document restating that its POST. So I'll
change it to make that explicit.

I remember feeling rather cutting edge 3ish years ago when using the RFC
7159 citation rather than 4627. But times change. I'll update the document
to cite 8259.

I seem to have had a bit of a Freudian slip there revealing my affection
for (or addiction to) the cheap Safeway store brand of sparkling water.
I'll fix that in the document.

-- 
_CONFIDENTIALITY NOTICE: This email may contain confidential and privileged 
material for the sole use of the intended recipient(s). Any review, use, 
distribution or disclosure by others is strictly prohibited.  If you have 
received this communication in error, please notify the sender immediately 
by e-mail and delete the message and any file attachments from your 
computer. Thank you._