Subject: [OAUTH-WG] Adam Roach's Discuss on draft-ietf-oauth-device-flow-11: (with DISCUSS and COMMENT)

From: Adam Roach <[email-masked]>
Date: Mon, 30 Jul 2018 22:30:24 -0700

Adam Roach has entered the following ballot position for
draft-ietf-oauth-device-flow-11: 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-device-flow/

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

Thanks to everyone who worked on this document. I have a couple of related
issues that need to be cleared up before publication, but I expect that these
should be easy to resolve.

§3.1:

>  The client initiates the flow by requesting a set of verification
>  codes from the authorization server by making an HTTP "POST" request
>  to the device authorization endpoint.  The client constructs the
>  request with the following parameters, encoded with the "application/
>  x-www-form-urlencoded" content type:

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).

(Non-discuss comment: this passage could be made clearer by saying something
like "...parameters, sent as the body of the request, encoded with the...")

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

§3.2:

>  In response, the authorization server generates a device verification
>  code and an end-user code that are valid for a limited time and
>  includes them in the HTTP response body using the "application/json"
>  format with a 200 (OK) status code.

This needs to normatively cite RFC 7159.

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

§3.5:

>  slow_down
>     The client is polling too quickly and should back off at a
>     reasonable rate.

I'm surprised the document doesn't define what is meant by "reasonable rate"
here. I would expect to see something concrete like "the client should double
the interval between polling requests" or some similarly concrete advice.

>  If no interval was provided, the client
>  MUST use a reasonable default polling interval.

Similarly, I'm really sad that this does not give concrete guidance for what
"reasonable" might be. Implementations may well decide 100ms is "reasonable" for
the purpose of application responsiveness -- but I suspect average OAuth servers
wouldn't be happy with that.

This would be a DISCUSS, but I see that Mirja has already registered a DISCUSS
on this topic. I support her DISCUSS.

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

§6.1:

This section discusses code input by the user. I'm surprised that it doesn't
also discuss confusability considerations (e.g., I, l, and 1; 0 and O)

===========================================================================

All of my remaining comments are minor editorial nits.

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

Abstract:

>  This OAuth 2.0 authorization flow for browserless and input
>  constrained devices

Nit: "...input-constrained..."

>  This OAuth 2.0 authorization flow for browserless and input
>  constrained devices, often referred to as the device flow, enables
>  OAuth clients to request user authorization from devices that have an
>  Internet connection, but don't have an easy input method (such as a
>  smart TV, media console, picture frame, or printer), or lack a
>  suitable browser for a more traditional OAuth flow.

This is a very long and winding sentence. Consider breaking up into multiple
sentences.

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

§1:

>  This OAuth 2.0 protocol flow for browserless and input constrained

Nit: "...input-constrained..."

Please cite RFC 6749 here.

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

§1:

>  The only requirements to use this flow are that the device is
>  connected to the Internet, and able to make outbound HTTPS requests,
>  be able to display or otherwise communicate a URI and code sequence
>  to the user, and that the user has a secondary device (e.g., personal
>  computer or smartphone) from which to process the request.

This is hard to read, and difficult to pack into one sentence (due to the
requirements being on both the device and its user). Consider reworking into a
bulleted list; e.g.:

   The only requirements to use this flow are:

     * The device is connected to the Internet
     * The device is able to make outbound HTTPS requests
     * The device is able to display or otherwise communicate a URI and code
       sequence to the user
     * The user has a secondary device (e.g., personal computer or smartphone)
       from which they can process the request

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

§1:

>  Instead of interacting with the end-user's user-agent, the client

Nit: "...end user's user agent..."

>  instructs the end-user to use another computer or device and connect

Nit: "...end user..."

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

§1:

>     (C) The client instructs the end-user to use its user-agent

Nit: "...end user..."

Nit: "...user agent..."

>     client provides the end-user with the end-user code to enter in

Nit: "...provides the end user with the end-user code..."

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

§1:

>     (D) The authorization server authenticates the end-user (via the

"...the end user..."

>     user-agent) and prompts the end-user to grant the client's access

"...user agent... end user..."

>     request.  If the end-user agrees to the client's access request,

"...the end user..."

>     the end-user enters the end-user code provided by the client.  The

"...the end user enters the end-user code..."

>     authorization server validates the end-user code provided by the
>     end-user.

"...by the end user."

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

§1:

>     (E) While the end-user authorizes (or denies) the client's request

"...the end user..."

>     (step D), the client repeatedly polls the authorization server to
>     find out if the end-user completed the end-user authorization

"...the end user completed the end-user authorization..."

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

§1:

>     (F) Assuming the end-user granted access, the authorization server

"...the end user..."

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

§2:

>  The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
>  "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
>  "OPTIONAL" in this document are to be interpreted as described in
>  [RFC2119].

Consider updating to use the boilerplate specified in RFC 8174.

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

§2:

>  End-User Verification Code:
>     A short-lived token which the device displays to the end user, is
>     entered by the end-user on the authorization server, and is thus

"...end user..."

>     used to bind the device to the end-user.

"...end user..."

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

§3.3:

>  session.  The authorization server prompts the end-user to identify

"...end user..."

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

§5.1:

>  In some applications this
>  attack may not make much economic sense, for example for a video app,
>  the owner of the device may then be able to purchase movies with the
>  attacker's account, however there are still privacy considerations in
>  that case as well as other uses of the device flow whereby the
>  granting account may be able to perform sensitive actions such as
>  controlling the victim's device.

This is a run-on sentence. Restructure by replacing the commas after "sense" and
"account" with either semicolons or periods.

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

§5.2:

>  malicious, then it could man-in-the middle the backchannel flow to

"...man-in-the-middle..."

>  middle is not completely hidden from sight, as the end-user would end

"...end user..."

---

From: Adam Roach <[email-masked]>
Date: Tue, 31 Jul 2018 01:17:09 -0500

> This needs to normatively cite RFC 7159.

Thanks to Carsten for reminding me that this has been replaced by RFC 
8259. Sorry for confusing things.

/a