[OAUTH-WG] Review of Device Flow Draft

[Justin Richer]

Finally had a chance to review the device flow draft in earnest. Overall it’s really great, and we’ve implemented it in a few places (see my recent post on one interesting use case). Just a few notes:

- use of “flow” has largely been replaced by “authorization grant” in other documents and we should be consistent here
- use of “end-user” has been replaced by “resource owner” in other documents and we should be consistent here
- “input constrained” should be “input-constrained” as used in the title, abstract, and introduction.
- §1¶3 could be rewritten to a bulleted list of requirements instead for readability
- §1¶4 could add something to address recent discussion on the list: “While this polling is usually automatic and repeated on a regularly timed basis, the client could poll based on user action with the device such as a button press.”
- §1 diagram (D) should state that the user is prompted to enter the user code given in (C) and that the user does so — leaving it out is an optimization (see below) and the likely exception
- §2 should probably be §1.1, or move the protocol flow to §1.1 and make §2 into §1.2
- §2 should import all terms used from 6749/6750 explicitly
- §2 should we define “secondary device” once at the top instead of the parenthetical definition used throughout?
- §3.1¶1 Wording is awkward with double “by” phrases, suggest: “The client initiates the authorization grant request by making an HTTP POST request to the device authorization endpoint.”
- §3.2 add xref to JSON (7159), response is a JSON object with the following members (not parameters)
- §3.2 is there any requirement for the verification_uri to be over HTTPS? I can’t see any discussion of this anywhere and it should probably at least be in the security considerations, if not an outright requirement. We say that authentication is done in a tls-protected session in §3.3 but we don’t say anything about the actual URL or the page in which the user enters the code.
- §3.3¶3 as mentioned above, the polling could be continuous (timer-based) or in reaction to a user action at the device. There are no protocol differences and the AS shouldn’t do try and inform the user, but we can at least mention that in our description of polling.
- §3.3.1 I still think this optimized all-in-one URI should be a separate parameter from the AS so as not to conflate it with the “plain” verification URI.
- §3.4¶3 instead of “based on the error code in the response” perhaps “until the authorization server indicates the device code has expired or was cancelled.” — I’m less sure about the wording here but as written it feels awkward.
- §3.5 I agree with the point made on the list about the error code, “access_denied” would fit this bill but right now it’s only specified on authorization endpoint response, so let’s add its use to the token response here
- §3.5¶4 says to return “invalid_grant” if the codes are expired, but in the same section it says to use “expired_code”.
- §3.5¶5 the interval between polls SHOULD be at least the “interval” value. Also, it MUST be greater than zero … William …
- §5.2 “user’s session and device”, use of “device” here is confusing since this is the “device” flow. Maybe explicitly call out this as the “secondary device”
- §5.5 extra “or” in list in final sentence


— Justin

[William Denniss]

Thank you for the review Justin.

- §3.3¶3 as mentioned above, the polling could be continuous (timer-based)

Post by Justin Richer
or in reaction to a user action at the device. There are no protocol
differences and the AS shouldn’t do try and inform the user, but we can at
least mention that in our description of polling.

+1 and I will highlight this in the IETF99 review.

- §3.3.1 I still think this optimized all-in-one URI should be a separate

Post by Justin Richer
parameter from the AS so as not to conflate it with the “plain”
verification URI.

This would allow for all-in-one URLs that differ significantly from the
current composite ones, is that why you're suggesting this? (if so: to
solve what use-case?)

What benefits do you see in this alternative approach?

I think generally it's seen as bad form to repeat information, so keen to
here why you think this is the case.

Are you dialing in to the WG meeting tomorrow?

Other than those two topics, the rest seem pretty uncontentious, I will
review and action as appropriate before the next draft. Please call out any
other items in this list that you feel warrant group discussion at IETF99.

William

Post by Justin Richer
Finally had a chance to review the device flow draft in earnest. Overall
it’s really great, and we’ve implemented it in a few places (see my recent
- use of “flow” has largely been replaced by “authorization grant” in
other documents and we should be consistent here
- use of “end-user” has been replaced by “resource owner” in other
documents and we should be consistent here
- “input constrained” should be “input-constrained” as used in the title,
abstract, and introduction.
- §1¶3 could be rewritten to a bulleted list of requirements instead for
readability
“While this polling is usually automatic and repeated on a regularly timed
basis, the client could poll based on user action with the device such as a
button press.”
- §1 diagram (D) should state that the user is prompted to enter the user
code given in (C) and that the user does so — leaving it out is an
optimization (see below) and the likely exception
- §2 should probably be §1.1, or move the protocol flow to §1.1 and make
§2 into §1.2
- §2 should import all terms used from 6749/6750 explicitly
- §2 should we define “secondary device” once at the top instead of the
parenthetical definition used throughout?
- §3.1¶1 Wording is awkward with double “by” phrases, suggest: “The client
initiates the authorization grant request by making an HTTP POST request to
the device authorization endpoint.”
- §3.2 add xref to JSON (7159), response is a JSON object with the
following members (not parameters)
- §3.2 is there any requirement for the verification_uri to be over HTTPS?
I can’t see any discussion of this anywhere and it should probably at least
be in the security considerations, if not an outright requirement. We say
that authentication is done in a tls-protected session in §3.3 but we don’t
say anything about the actual URL or the page in which the user enters the
code.
- §3.3¶3 as mentioned above, the polling could be continuous (timer-based)
or in reaction to a user action at the device. There are no protocol
differences and the AS shouldn’t do try and inform the user, but we can at
least mention that in our description of polling.
- §3.3.1 I still think this optimized all-in-one URI should be a separate
parameter from the AS so as not to conflate it with the “plain”
verification URI.
- §3.4¶3 instead of “based on the error code in the response” perhaps
“until the authorization server indicates the device code has expired or
was cancelled.” — I’m less sure about the wording here but as written it
feels awkward.
- §3.5 I agree with the point made on the list about the error code,
“access_denied” would fit this bill but right now it’s only specified on
authorization endpoint response, so let’s add its use to the token response
here
- §3.5¶4 says to return “invalid_grant” if the codes are expired, but in
the same section it says to use “expired_code”.
- §3.5¶5 the interval between polls SHOULD be at least the “interval”
value. Also, it MUST be greater than zero 
 William 

- §5.2 “user’s session and device”, use of “device” here is confusing
since this is the “device” flow. Maybe explicitly call out this as the
“secondary device”
- §5.5 extra “or” in list in final sentence
— Justin
_______________________________________________
OAuth mailing list
https://www.ietf.org/mailman/listinfo/oauth

[Justin Richer]

Inline.

Post by William Denniss
Thank you for the review Justin.
- §3.3¶3 as mentioned above, the polling could be continuous (timer-based) or in reaction to a user action at the device. There are no protocol differences and the AS shouldn’t do try and inform the user, but we can at least mention that in our description of polling.
+1 and I will highlight this in the IETF99 review.

Sounds good!

Post by William Denniss
- §3.3.1 I still think this optimized all-in-one URI should be a separate parameter from the AS so as not to conflate it with the “plain” verification URI.
This would allow for all-in-one URLs that differ significantly from the current composite ones, is that why you're suggesting this? (if so: to solve what use-case?)
What benefits do you see in this alternative approach?
I think generally it's seen as bad form to repeat information, so keen to here why you think this is the case.

The benefit is that each item of data is good for exactly one thing. One is something the user needs to go and interact with and type the code, one is where the user doesn’t need to type the code. Right now there’s no way to tell them apart. Imagine if you’ve got a simple device that displays the URI and code to the user, like the set-top-box case. It tells the user: “Go to https://foo.bar/device/CODE-HERE <https://foo.bar/device/CODE-HERE> and type in CODE-HERE”. So the user types in the longer URL and isn’t prompted to enter the code that they were told they’d have to enter. Did it work like it was supposed to even though the instructions didn’t line up with how the AS (correctly) processed things? I just see it leading to confusion where you’ve got one client that assumes it’s baked in and one server that assumes it’s not, or vice versa, leading to interop issues that could be easily avoided.

Post by William Denniss
Are you dialing in to the WG meeting tomorrow?

Yes, I’ll be dialing in. 3:30am my time so I can’t guarantee how chatty I’ll be, but I’ll be on. :)

Post by William Denniss
Other than those two topics, the rest seem pretty uncontentious, I will review and action as appropriate before the next draft. Please call out any other items in this list that you feel warrant group discussion at IETF99.

Sounds good — overall it’s a very solid draft.

— Justin

Post by William Denniss
- use of “flow” has largely been replaced by “authorization grant” in other documents and we should be consistent here
- use of “end-user” has been replaced by “resource owner” in other documents and we should be consistent here
- “input constrained” should be “input-constrained” as used in the title, abstract, and introduction.
- §1¶3 could be rewritten to a bulleted list of requirements instead for readability
- §1¶4 could add something to address recent discussion on the list: “While this polling is usually automatic and repeated on a regularly timed basis, the client could poll based on user action with the device such as a button press.”
- §1 diagram (D) should state that the user is prompted to enter the user code given in (C) and that the user does so — leaving it out is an optimization (see below) and the likely exception
- §2 should probably be §1.1, or move the protocol flow to §1.1 and make §2 into §1.2
- §2 should import all terms used from 6749/6750 explicitly
- §2 should we define “secondary device” once at the top instead of the parenthetical definition used throughout?
- §3.1¶1 Wording is awkward with double “by” phrases, suggest: “The client initiates the authorization grant request by making an HTTP POST request to the device authorization endpoint.”
- §3.2 add xref to JSON (7159), response is a JSON object with the following members (not parameters)
- §3.2 is there any requirement for the verification_uri to be over HTTPS? I can’t see any discussion of this anywhere and it should probably at least be in the security considerations, if not an outright requirement. We say that authentication is done in a tls-protected session in §3.3 but we don’t say anything about the actual URL or the page in which the user enters the code.
- §3.3¶3 as mentioned above, the polling could be continuous (timer-based) or in reaction to a user action at the device. There are no protocol differences and the AS shouldn’t do try and inform the user, but we can at least mention that in our description of polling.
- §3.3.1 I still think this optimized all-in-one URI should be a separate parameter from the AS so as not to conflate it with the “plain” verification URI.
- §3.4¶3 instead of “based on the error code in the response” perhaps “until the authorization server indicates the device code has expired or was cancelled.” — I’m less sure about the wording here but as written it feels awkward.
- §3.5 I agree with the point made on the list about the error code, “access_denied” would fit this bill but right now it’s only specified on authorization endpoint response, so let’s add its use to the token response here
- §3.5¶4 says to return “invalid_grant” if the codes are expired, but in the same section it says to use “expired_code”.
- §3.5¶5 the interval between polls SHOULD be at least the “interval” value. Also, it MUST be greater than zero 
 William 

- §5.2 “user’s session and device”, use of “device” here is confusing since this is the “device” flow. Maybe explicitly call out this as the “secondary device”
- §5.5 extra “or” in list in final sentence
— Justin
_______________________________________________
OAuth mailing list
https://www.ietf.org/mailman/listinfo/oauth <https://www.ietf.org/mailman/listinfo/oauth>