Subject: Re: [OAUTH-WG] Alissa Cooper's No Objection on draft-ietf-oauth-device-flow-11: (with COMMENT)

From: William Denniss <[email-masked]>
Date: Fri, 28 Dec 2018 17:34:37 +1000

Hi Alissa,

Version -13 contains both these improvements, thank you for your feedback!

Detailed response inline below:

Best,
William

On Fri, Aug 3, 2018 at 6:22 AM, Alissa Cooper <[email-masked]> wrote:

> Hi William,
>
> On Aug 2, 2018, at 2:41 PM, William Denniss <[email-masked]> wrote:
>
> Alissa,
>
> Thank you for your review. Replies inline:
>
> On Tue, Jul 31, 2018 at 8:58 AM, Alissa Cooper <[email-masked]> wrote:
>
>>
>> ----------------------------------------------------------------------
>> COMMENT:
>> ----------------------------------------------------------------------
>>
>> I support Mirja's DISCUSS point #3 which was also raised by the Gen-ART
>> reviewer. The Gen-ART review also included a number of other useful
>> comments.
>> Please address them.
>>
>
> We're working through the comments, some were addressed in -12, and the
> work continues.
>
>
>>
>> Perhaps this is implicit, but I found it a little odd that there is no
>> mention
>> of whether the device codes and user codes are expected to be unique to
>> individual devices.
>>
>
> The are definitely expected to be unique.
>
> Section 3.2 currently states "the authorization server generates a device
> verification code and an end-user code that are valid for a limited time"
>
> The assumption was that the "generated" codes would be unique. I will add
> the word unique in future version (13), so it will read "generates a unique
> device verification code…”
>
>
> Great.
>

Section 3.2 of version 13 reads in part:

the authorization server generates a *unique* device
   verification code and an end-user code that are valid for a limited
   time

>
>
>
>
>> Section 3.3:
>>
>> "It is NOT RECOMMENDED for authorization servers to include the user
>>    code in the verification URI ("verification_uri"), as this increases
>>    the length and complexity of the URI that the user must type."
>>
>> I don't fully understand the justification for the normative requirement
>> here.
>> The user ultimately ends up typing in both strings, right? Is it so much
>> more
>> complex to type them both into a browser bar contiguously than to type
>> the uri
>> into the browser bar and the code into some form field on the page such
>> that
>> the normative requirement is warranted?
>>
>
> Yes, the user will need to type both strings regardless.
>
> The main reason for the recommended separation is that the URI can't be
> validated/corrected – either they type it correctly and they get to the
> page, or they don't. But for the user-code, the page can display an error
> if the user types it wrong. The belief is that it's a better user
> experience that they get to the page, and then continue the input from
> there rather than get browser errors if they typed the user-code part of
> the URI wrong.
>
>
> Got it. I think it would help to add this explanation to the document.
>
>
Added an explanation to Section 3.3 in version 13:

   It is NOT RECOMMENDED for authorization servers to include the user
   code in the verification URI ("verification_uri"), as this increases
   the length and complexity of the URI that the user must type.  *While
   the user must still type the same number of characters with the
   user_code separated, once they successfully navigate to the
   verification_uri, any errors in entering the code can be highlighted
   by the authorization server to improve the user experience.*  The next
   section documents user interaction with "verification_uri_complete",
   which is designed to carry *both pieces of* information.

> Thanks,
> Alissa
>
>
> This is also how every implementation I've seen has actually implemented
> it.
>
> As written, if the authorization server were to include the code in the
> URI, this would then raise the question of what should be in the user_code
> (e.g. would it be the empty string?) and how the device client should
> render the instructions in that case. I think the spec is simpler if we
> recommend one preferred approach based on the usability best-practices
> derived from the implementation experience of earlier drafts.
>
> Section 3.3.1:
>>
>> Wouldn't there be textual instructions about how to use the QR code also
>> included here? If the point is to illustrate the UI it seems like those
>> should
>> be included too.
>>
>
> Good point! Figure 3 was updated to include QR scanning instructions.
>
> Best,
> William
>
>
>

---

From: William Denniss <[email-masked]>
Date: Fri, 28 Dec 2018 17:44:29 +1000

Benjamin,

On Fri, Aug 3, 2018 at 4:37 PM, Benjamin Kaduk <[email-masked]> wrote:
>
>
> I am hardly a URI expert, so salt as appropriate, but if the user code was
> in the query string, would the server still be able to generate a useful
> error page if the user code was typed incorrectly?

It might be possible for the server to catch certain types of errors, I
agree, but not all possible errors. For example mis-entering path separator
wouldn't be catchable on the server, such as for the user input:
"device.example.comWDJB-MJHT" or "device.example.com;WDJB-MJHT"

It's also more challenging to implement the error handling, as the URI
could resolve to another valid URI, e.g. "device.example.com/abc" might be
used for something else.

Our opinion on usability is that it's better to break it down into two
steps: get the URI correct, then type the code correctly. In the latter
section, the AS can render helpful instructions, and perform JS validation
during the input without needing a page reload.

Another advantage of having the code separate is that when the QR code
with verification_uri_complete
is used, the code could be re-purposed as pairing code. E.g. after scanning
the QR Code: (e.g. "is your device displaying WDJB-MJHT ?"). That would be
harder to describe with a combined URI + code.  This is something we
explicitly recommend in Section 3.3.1 (third paragraph).

One final point, earlier I said that the user would type the same number of
characters regardless, but that was wrong: in the case of the URI, the user
would need to type an additional character being the path or query
separator. That extra character may not seem like much but it does impact
usability (even with no errors), as they would need to navigate to the
special characters section on the keyboard. I will tweak the text to
reflect this.