OAuth 2.0 Device Authorization Grant
draft-ietf-oauth-device-flow-15

[Ballot comment]
Thank you for addressing my Discuss points.  I would still prefer to see a
normative requirement for explicit user approval (as opposed to  just the
descriptive statement that the chance to approve/deny should be offered),
but I can understand the sentiment that such a requirement  on  the UI is
not a matter for interoperability and could not be reliably enforced anyway.

Original COMMENT  section preserved below.

Please use the RFC 8174 boilerplate instead of the RFC 2119 one.

Section 3.2

The example expires in 30 minutes?  That seems longer than needed; wouldn't
5 minutes do?

Section 3.3

I agree with directorate reviewer that the MUST NOT requirement for
displaying the device_code should justify that requirement by discussing
the consequences of exposure.

Section 3.5

  authorization_pending
      The authorization request is still pending as the end-user hasn't
      yet completed the user interaction steps (Section 3.3).  The
      client should repeat the Access Token Request to the token
      endpoint.

I feel like we want to mention the 'interval' here or some other discussion
of an inter-request delay.

Also, please clarify "reasonable default polling interval", per multiple
directorate reviews.

Section 5.2

Please clarify the entities involved in "the backchannel flow" that can be
MITM'd.

Section 5.6

The "short-range" part of a "short-range wireless signal" partially depends
on how big the receiver's antenna is.  So perhaps we should be careful
about indicating that this has more security value than it does.

Section 6.1

I'm not sure I understand the usage of "case-insensitive", here -- how
would the user have an expectation of case-insensitivity?  Perhaps it is
better to just say "majuscule" or "upper case" or whatever.

[Ballot discuss]
[Updating to remove Discuss point addressed in the -12; no change to
the ballot position text otherwise, even when non-Discuss comments
are addressed]

Let me preface this by noting that I'm not sure that all of these points
are actionable; I would, however, like to discuss them.

I'm really unhappy to not see any hard numbers on the entropy needed
in a user code to provide a reasonable security margin with given
parameters, and how it compares to the guessability bounds considered best
practices in general (across protocols).  For example, we think 128-bit
symmetric keys are okay because an attacker has to put in 2**96 work to
have a 2**-32 chance of guessing correctly via brute force; the rate
limiting and finite lifetime on the user code places an artificial limit on
the amount of work an attacker can "do", so if one uses a 8-character
base-20 user code (with roughly 34.5 bits of entropy), the rate-limiting
interval and validity period would need to only allow 5 attempts in order
to get the same 2**-32 probability of success by random guessing.
Section 5.1 would be a great place for such text, near the preexisting:
  The user code SHOULD have enough entropy that when combined with rate
  limiting and other mitigations makes a brute-force attack infeasible.

We talk about "the authorization server", but any given *user* may have a
relationship with multiple such ASes.  Can the Introduction make it more
clear that the AS is associated with the device/client, and as such the
it may not be the user's most-trusted AS?

It also seems like a large latent risk with this flow is when the
verification_uri_complete response is used along with an AS that assumes an
authenticated user making such a verification request has approved the
authorization (i.e., without an explicit user interaction to confirm), when
that AS uses cookies or other persistent state to keep the user
authenticated across multiple requests.  I could not find any MUST-level
requirement for user interaction to confirm the device being authorized
(even in Section 3.3, which covers the regular verificat_uri workflow!);
please let me know if I missed something.  I would like to see some
explicit text that (matching the flow described in Section 3.1 that
requires the user to input the code) explicit user approval of the
authorization is required.  (I do note that Section 5.3 has text about
"SHOULD display information about the device.)

[Ballot discuss]
Thanks to the authors for addressing my comments and half of my DISCUSS.
This final issue appears to remain unaddressed:

§3.1:

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

[Ballot discuss]
Thanks to the authors for addressing my comments and half of my DISCUSS.
This final issue appears to remain unaddressed:

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

[Ballot comment]
Major Comment:

I support Mirja's DISCUSS. (Otherwise, this would be a DISCUSS), but I have a slightly different spin on it. The device polls the server while waiting on the user to take action. Users are notoriously slow about that sort of thing. They might plug in a device then walk away for hours, days, or forever.  Now, consider that we are talking about IoT devices, so there may be millions of them. If they are fate shared in some way (imagine shipping day for a new popular product, or a software update that forces reauthorization, or a server coming back online after getting whacked the last time around), there could be millions of them trying this at the roughly the same time.

Given all that, I think the draft really needs to give more detailed guidance on what sort of refresh rates, maximum attempts, expirations, back off patterns, etc might be reasonable from both network congestion and server overload perspectives.

Other Substantive Comments:

§3.1: What sort of events are expected to trigger the flow? In particular, I wonder if there should be guidance to make it unlikely to start the process by accident. For example, if the authorization process is kicked off by a device simply being plugged into power, a user might plug it in then walk away before realizing they had more to do. (See my major comment).

§3.3: What sort of bad thing could happen if the device_code is communicated to a user? Do implementers need to worry about people  guessing device-codes?

§3.3, last paragraph: The "NOT RECOMMENDED" seems overly strong, given that the next section describes a perfectly good way to do exactly that. Maybe something like "NOT RECOMMENDED unless the device uses a non-textual mechanism for conveying the URL and code, such as that described in ..." would make sense?

§5.4: Are devices expected to know the operating environment in advance of deployment?

Editorial Comments:

§1, 3rd paragraph: The first sentence is hard to parse due the list of long, complex phrases. Please consider breaking into simpler sentences.

§2: There are lower case instances of normative keywords.  Please consider using the updated boilerplate from RFC8174.

[Ballot 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 8259.

[Ballot 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.

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.

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?

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.

[Ballot 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.

[Ballot 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..."

[Ballot comment]
This is generally a fine document and it was easy to follow.

I am agreeing with Benjamin's DISCUSS about amount of entropy in codes.

In addition, the last para in Section 6.1 reads:

  The server should ignore any characters like punctuation that are not
  in the user-code character set.  Provided that the character set
  doesn't include characters of different case, the comparison should
  be case insensitive.

This makes me uncomfortable, because you are talking of case-insensitivity,
without fully specifying what it is. I assume that your advice only
applies to user-code character sets which only use subset of ASCII?
Because if you mean to extend your advice to full Unicode, you need more text
and references here. Can you please clarify.

[Ballot comment]
Props on the ASCII art QR code :-)

I believe the acknowledgement section should be in the body of the document, not as an appendix.


Also, please see the OpsDir review at: https://mailarchive.ietf.org/arch/msg/ops-dir/W8nzC89juHe32K3VXLQyVcPC_og

[Ballot discuss]
Please specify more clearly the (default) polling behavior to ensure that the polling does neither overload the network, nor the server, or is never terminated. Ideally provide default values and an upper bound for the polling frequency, as well as a timer to terminate polling if no reply is received (and no expiration time is given). See further details below.

1) Sec 3.3: "until the user completes the interaction, the code expires, or another
  error occurs."
What if not expiration time is given (as this optional) and no reply is ever received?

2) Sec 3.5: "the client should stop polling and react accordingly, for
  example, by displaying an error to the user."
Maybe:
"the client MUST stop polling and SHOULD react accordingly, for
  example, by displaying an error to the user."

3) sec 3.5 "If no interval was provided, the client
  MUST use a reasonable default polling interval."
Can you please provide a default number for a "reasonable" polling interval! And in best case an upper bound!

4) sec 3.5: "...increasing the time between polls if a
  "slow_down" error is received. "
Maybe use a separate normative sentence instead:
"The client SHOUD increase the time between polls if a
  "slow_down" error is received."
Or MUST? If so how much? Can you given further (default) guidance.

5) sec 3.5: "Clients MAY then choose to
  start a new device authorization session."
Maybe make it clear that polling is stopped
"Clients MUST stop polling but MAY then choose to
  start a new device authorization session."

6) sec 3.5: "then the
  device MAY wait until notified on that channel that the user has
  completed the action before initiating the token request."
Why not SHOULD (or MUST) here?

[Ballot discuss]
Let me preface this by noting that I'm not sure that all of these points
are actionable; I would, however, like to discuss them.

I'm really unhappy to not see any hard numbers on the entropy needed
in a user code to provide a reasonable security margin with given
parameters, and how it compares to the guessability bounds considered best
practices in general (across protocols).  For example, we think 128-bit
symmetric keys are okay because an attacker has to put in 2**96 work to
have a 2**-32 chance of guessing correctly via brute force; the rate
limiting and finite lifetime on the user code places an artificial limit on
the amount of work an attacker can "do", so if one uses a 8-character
base-20 user code (with roughly 34.5 bits of entropy), the rate-limiting
interval and validity period would need to only allow 5 attempts in order
to get the same 2**-32 probability of success by random guessing.
Section 5.1 would be a great place for such text, near the preexisting:
  The user code SHOULD have enough entropy that when combined with rate
  limiting and other mitigations makes a brute-force attack infeasible.

We talk about "the authorization server", but any given *user* may have a
relationship with multiple such ASes.  Can the Introduction make it more
clear that the AS is associated with the device/client, and as such the
it may not be the user's most-trusted AS?

It also seems like a large latent risk with this flow is when the
verification_uri_complete response is used along with an AS that assumes an
authenticated user making such a verification request has approved the
authorization (i.e., without an explicit user interaction to confirm), when
that AS uses cookies or other persistent state to keep the user
authenticated across multiple requests.  I could not find any MUST-level
requirement for user interaction to confirm the device being authorized
(even in Section 3.3, which covers the regular verificat_uri workflow!);
please let me know if I missed something.  I would like to see some
explicit text that (matching the flow described in Section 3.1 that
requires the user to input the code) explicit user approval of the
authorization is required.  (I do note that Section 5.3 has text about
"SHOULD display information about the device.)

I'm also unhappy about the text in Section 1 that merely requires of the
device the ability to "make outbound HTTPS requests", which leaves room for
an awful lot of sins in certificate validation (and, potentially,
ciphersuite selection).  Can we get a MUST-level requirement for
authenticating the server and a cite to RFC 7525?

[Ballot comment]
Please use the RFC 8174 boilerplate instead of the RFC 2119 one.

Section 3.2

The example expires in 30 minutes?  That seems longer than needed; wouldn't
5 minutes do?

Section 3.3

I agree with directorate reviewer that the MUST NOT requirement for
displaying the device_code should justify that requirement by discussing
the consequences of exposure.

Section 3.5

  authorization_pending
      The authorization request is still pending as the end-user hasn't
      yet completed the user interaction steps (Section 3.3).  The
      client should repeat the Access Token Request to the token
      endpoint.

I feel like we want to mention the 'interval' here or some other discussion
of an inter-request delay.

Also, please clarify "reasonable default polling interval", per multiple
directorate reviews.

Section 5.2

Please clarify the entities involved in "the backchannel flow" that can be
MITM'd.

Section 5.6

The "short-range" part of a "short-range wireless signal" partially depends
on how big the receiver's antenna is.  So perhaps we should be careful
about indicating that this has more security value than it does.

Section 6.1

I'm not sure I understand the usage of "case-insensitive", here -- how
would the user have an expectation of case-insensitivity?  Perhaps it is
better to just say "majuscule" or "upper case" or whatever.

(Via drafts-lastcall@iana.org): IESG/Authors/WG Chairs:

The IANA Functions Operator has completed its review of draft-ietf-oauth-device-flow-09. If any part of this review is inaccurate, please let us know.

The IANA Services Operator understands that, upon approval of this document, there are three actions which we must complete.

First, in the OAuth URI registry on the OAuth Parameters registry page located at:

https://www.iana.org/assignments/oauth-parameters/

a single, new registration will be made as follows:

URN: urn:ietf:params:oauth:grant-type:device_code
Common Name: Device flow grant type for OAuth 2.0
Change controller: IESG
Reference: Section 3.1 of [ RFC-to-be ]

As this document requests registrations in a Specification Required (see RFC 8126) registry, we will initiate the required Expert Review via a separate request. Expert review will need to be completed before your document can be approved for publication as an RFC.

Second, in the OAuth Extensions Error Registry also on the OAuth Parameters registry page located at:

https://www.iana.org/assignments/oauth-parameters/

a four, new registrations will be made as follows:

Name: authorization_pending
Usage Location Token endpoint response
Protocol Extension: [ RFC-to-be ]
Change controller: IETF
Reference: Section 3.5 of [ RFC-to-be ]

Name: access_denied
Usage Location: Token endpoint response
Protocol Extension: [ RFC-to-be ]
Change controller: IETF
Reference: Section 3.5 of [ RFC-to-be ]

Name: slow_down
Usage Location Token endpoint response
Protocol Extension: [ RFC-to-be ]
Change controller: IETF
Reference: Section 3.5 of [ RFC-to-be ]

Name: expired_token
Usage Location Token endpoint response
Protocol Extension: [ RFC-to-be ]
Change controller: IETF
Reference: Section 3.5 of [ RFC-to-be ]

As this document also requests further registrations in a Specification Required (see RFC 8126) registry, we will initiate the required Expert Review via a separate request. Expert review will need to be completed before your document can be approved for publication as an RFC.

Third, in the OAuth Authorization Server Metadata registry also on the OAuth Parameters registry page located at:

https://www.iana.org/assignments/oauth-parameters/

a single, new registration will be made as follows:

Metadata Name: device_authorization_endpoint
Metadata Description: The Device Authorization Endpoint
Change Controller: IESG
Refernce: Section 4 of [ RFC-to-be ]

As this document requests further registrations in a Specification Required (see RFC 8126) registry, we will initiate the required Expert Review via a separate request. Expert review will need to be completed before your document can be approved for publication as an RFC.

The IANA Services Operator understands that these are the only actions required to be completed upon approval of this document.

Note:  The actions requested in this document will not be completed until the document has been approved for publication as an RFC. This message is meant only to confirm the list of actions that will be performed.


Thank you,

Sabrina Tanamal
Senior IANA Services Specialist

The following Last Call announcement was sent out (ends 2018-06-12):

From: The IESG
To: IETF-Announce
CC: ekr@rtfm.com, Rifaat Shekh-Yusef , rifaat.ietf@gmail.com, draft-ietf-oauth-device-flow@ietf.org, oauth-chairs@ietf.org, oauth@ietf.org
Reply-To: ietf@ietf.org
Sender:
Subject: Last Call:  (OAuth 2.0 Device Flow for Browserless and Input Constrained Devices) to Proposed Standard


The IESG has received a request from the Web Authorization Protocol WG
(oauth) to consider the following document: - 'OAuth 2.0 Device Flow for
Browserless and Input Constrained Devices'
  as Proposed Standard

The IESG plans to make a decision in the next few weeks, and solicits final
comments on this action. Please send substantive comments to the
ietf@ietf.org mailing lists by 2018-06-12. Exceptionally, comments may be
sent to iesg@ietf.org instead. In either case, please retain the beginning of
the Subject line to allow automated sorting.

Abstract


  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
  authorization flow instructs the user to perform the authorization
  request on a secondary device, such as a smartphone.  There is no
  requirement for communication between the constrained device and the
  user's secondary device.




The file can be obtained via
https://datatracker.ietf.org/doc/draft-ietf-oauth-device-flow/

IESG discussion can be tracked via
https://datatracker.ietf.org/doc/draft-ietf-oauth-device-flow/ballot/


No IPR declarations have been submitted directly on this I-D.


The document contains these normative downward references.
See RFC 3967 for additional information:
    rfc6819: OAuth 2.0 Threat Model and Security Considerations (Informational - IETF stream)
    draft-recordon-oauth-v2-device: OAuth 2.0 Device Profile
(None - )
    rfc6755: An IETF URN Sub-Namespace for OAuth (Informational - IETF stream)

(1) What type of RFC is being requested (BCP, Proposed Standard, Internet Standard, Informational, Experimental, or Historic)? Why is this the proper type of RFC? Is this type of RFC indicated in the title page header?

The draft-ietf-oauth-device-flow-07 is a Standards Track document that defines a mechanism to allow users to request authorization for devices with Internet access but with limited UI capabilities (e.g. smart TV, media console, etc).
Standards Track is needed because the new mechanism defines a new flow that is not defined in the existing OAuth 2.0 specifications.


(2) The IESG approval announcement includes a Document Announcement Write-Up. Please provide such a Document Announcement Write-Up. Recent examples can be found in the "Action" announcements for approved documents. The approval announcement contains the following sections:

Technical Summary:

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 authorization flow instructs the user to perform the authorization request on a secondary device, such as a smartphone.  There is no requirement for communication between the constrained device and the user's secondary device.


Working Group Summary:

The device flow used to be part of the OAuth 2.0 specification, but it was later moved to its own separate document based on the WG feedback and support:
https://mailarchive.ietf.org/arch/msg/oauth/pQafddqfV3W3U_skHuR7E6ZQ44I
https://mailarchive.ietf.org/arch/msg/oauth/U7FsPASLxhNz4eB2FNypw4n952c

The WG document received many reviews and feedbacks from multiple WG members on the mailing list and during the WG meetings.


Document Quality:

The document has been implemented by Google, Facebook, Microsoft, ForgeRock, Salesforce, Curity Identity Server, and MITREid Connect.
https://developers.google.com/youtube/v3/guides/auth/devices
https://developers.facebook.com/docs/facebook-login/for-devices
https://github.com/Azure-Samples/active-directory-dotnet-deviceprofile
https://backstage.forgerock.com/docs/am/5.5/oauth2-guide/#rest-api-oauth2-device-flow
https://releasenotes.docs.salesforce.com/en-us/spring17/release-notes/rn_security_auth_device_flow.htm
https://www.curity.io/product/
https://github.com/mitreid-connect/OpenID-Connect-Java-Spring-Server

Also, it seems that ETSI has a specification based on this document:
https://www.ietf.org/mail-archive/web/oauth/current/msg15969.html
https://mailarchive.ietf.org/arch/msg/oauth/23ARrozt4RUUHA_NRiet7c38oIA
http://www.etsi.org/deliver/etsi_ts/103400_103499/103407/01.01.01_60/ts_103407v010101p.pdf
https://tech.ebu.ch/groups/CPA

There is also a different use for this mechanism as stated here:
https://mailarchive.ietf.org/arch/msg/oauth/VzEo9rqC3kmqCuLFR-JcYQvIM3Q

Personnel:

The document shepherd is Rifaat Shekh-Yusef.
The responsible Area Director is Eric Rescorla.


(3) Briefly describe the review of this document that was performed by the Document Shepherd. If this version of the document is not ready for publication, please explain why the document is being forwarded to the IESG.

The document shepherd has reviewed several versions of this document, including the last one, feels the document is ready.


(4) Does the document Shepherd have any concerns about the depth or breadth of the reviews that have been performed?

The document shepherd has no concerns with the level of reviews, as the document was discussed and reviewed by many participants.


(5) Do portions of the document need review from a particular or from broader perspective, e.g., security, operational complexity, AAA, DNS, DHCP, XML, or internationalization? If so, describe the review that took place.

Security review is always needed and appreciated.


(6) Describe any specific concerns or issues that the Document Shepherd has with this document that the Responsible Area Director and/or the IESG should be aware of? For example, perhaps he or she is uncomfortable with certain parts of the document, or has concerns whether there really is a need for it. In any event, if the WG has discussed those issues and has indicated that it still wishes to advance the document, detail those concerns here.

The document shepherd has no such concerns.


(7) Has each author confirmed that any and all appropriate IPR disclosures required for full conformance with the provisions of BCP 78 and BCP 79 have already been filed. If not, explain why?

Yes.
John: https://www.ietf.org/mail-archive/web/oauth/current/msg17698.html
Mike: https://www.ietf.org/mail-archive/web/oauth/current/msg17704.html
William: https://www.ietf.org/mail-archive/web/oauth/current/msg17705.html
Hannes: https://www.ietf.org/mail-archive/web/oauth/current/msg17706.html


(8) Has an IPR disclosure been filed that references this document? If so, summarize any WG discussion and conclusion regarding the IPR disclosures.

No such IPR disclosures.


(9) How solid is the WG consensus behind this document? Does it represent the strong concurrence of a few individuals, with others being silent, or does the WG as a whole understand and agree with it?

There is a solid support for this document from the WG.


(10) Has anyone threatened an appeal or otherwise indicated extreme discontent? If so, please summarise the areas of conflict in separate email messages to the Responsible Area Director. (It should be in a separate email because this questionnaire is publicly available.)

No such threat or discontent.


(11) Identify any ID nits the Document Shepherd has found in this document. (See http://www.ietf.org/tools/idnits/ and the Internet-Drafts Checklist). Boilerplate checks are not enough; this check needs to be thorough.

Section 7.1.1, last bullet, should point to section 3.2 instead of 3.1

The following is the IETF tools nits reports:

idnits 2.15.00

/tmp/draft-ietf-oauth-device-flow-07.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 :
  ----------------------------------------------------------------------------

  ** There is 1 instance of too long lines in the document, the longest one
    being 14 characters in excess of 72.


  Miscellaneous warnings:
  ----------------------------------------------------------------------------

  == The copyright year in the IETF Trust and authors Copyright Line does not
    match the current year

  -- The document date (October 30, 2017) is 66 days in the past.  Is this
    intentional?


  Checking references for intended status: Proposed Standard
  ----------------------------------------------------------------------------

    (See RFCs 3967 and 4897 for information about using normative references
    to lower-maturity documents in RFCs)

  == Outdated reference: A later version (-08) exists of
    draft-ietf-oauth-discovery-05

  ** Downref: Normative reference to an Informational RFC: RFC 6755

  ** Downref: Normative reference to an Informational RFC: RFC 6819


    Summary: 3 errors (**), 0 flaws (~~), 2 warnings (==), 1 comment (--).

    Run idnits with the --verbose option for more detailed information about
    the items above.


(12) Describe how the document meets any required formal review criteria, such as the MIB Doctor, media type, and URI type reviews.

No such reviews are necessary.


(13) Have all references within this document been identified as either normative or informative?

Yes.


(14) Are there normative references to documents that are not ready for advancement or are otherwise in an unclear state? If such normative references exist, what is the plan for their completion?

The document references the OAuth 2.0 Authorization Server Metadata document, which is under IESG Evaluation at this stage.
https://datatracker.ietf.org/doc/draft-ietf-oauth-discovery/


(15) Are there downward normative references (see RFC 3967)? If so, list these downward references to support the Area Director in the Last Call procedure.

From the nits:
  ** Downref: Normative reference to an Informational RFC: RFC 6755

  ** Downref: Normative reference to an Informational RFC: RFC 6819


(16) Will publication of this document change the status of any existing RFCs? Are those RFCs listed on the title page header, listed in the abstract, and discussed in the introduction? If the RFCs are not listed in the Abstract and Introduction, explain why, and point to the part of the document where the relationship of this document to the other RFCs is discussed. If this information is not in the document, explain why the WG considers it unnecessary.

No status change of any existing RFCs.


(17) Describe the Document Shepherd's review of the IANA considerations section, especially with regard to its consistency with the body of the document. Confirm that all protocol extensions that the document makes are associated with the appropriate reservations in IANA registries. Confirm that any referenced IANA registries have been clearly identified. Confirm that newly created IANA registries include a detailed specification of the initial contents for the registry, that allocations procedures for future registrations are defined, and a reasonable name for the new registry has been suggested (see RFC 5226).

The IANA section is complete and correct.


(18) List any new IANA registries that require Expert Review for future allocations. Provide any public guidance that the IESG would find useful in selecting the IANA Experts for these new registries.

No new IANA registries.


(19) Describe reviews and automated checks performed by the Document Shepherd to validate sections of the document written in a formal language, such as XML code, BNF rules, MIB definitions, etc.

The document contains JSON-based examples, and these were validated using JSONLint.

(1) What type of RFC is being requested (BCP, Proposed Standard, Internet Standard, Informational, Experimental, or Historic)? Why is this the proper type of RFC? Is this type of RFC indicated in the title page header?

The draft-ietf-oauth-device-flow-07 is a Standards Track document that defines a mechanism to allow users to request authorization for devices with Internet access but with limited UI capabilities (e.g. smart TV, media console, etc).
Standards Track is needed because the new mechanism defines a new flow that is not defined in the existing OAuth 2.0 specifications.


(2) The IESG approval announcement includes a Document Announcement Write-Up. Please provide such a Document Announcement Write-Up. Recent examples can be found in the "Action" announcements for approved documents. The approval announcement contains the following sections:

Technical Summary:

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 authorization flow instructs the user to perform the authorization request on a secondary device, such as a smartphone.  There is no requirement for communication between the constrained device and the user's secondary device.


Working Group Summary:

The device flow used to be part of the OAuth 2.0 specification, but it was later moved to its own separate document based on the WG feedback and support:
https://mailarchive.ietf.org/arch/msg/oauth/pQafddqfV3W3U_skHuR7E6ZQ44I
https://mailarchive.ietf.org/arch/msg/oauth/U7FsPASLxhNz4eB2FNypw4n952c

The WG document received many reviews and feedbacks from multiple WG members on the mailing list and during the WG meetings.


Document Quality:

The document has been implemented by Google, Facebook, Microsoft, ForgeRock, Salesforce, and Curity Identity Server.
https://developers.google.com/youtube/v3/guides/auth/devices
https://developers.facebook.com/docs/facebook-login/for-devices
https://backstage.forgerock.com/docs/am/5.5/oauth2-guide/#rest-api-oauth2-device-flow
https://releasenotes.docs.salesforce.com/en-us/spring17/release-notes/rn_security_auth_device_flow.htm
https://www.curity.io/product/

Also, it seems that ETSI has a specification based on this document:
https://www.ietf.org/mail-archive/web/oauth/current/msg15969.html
https://mailarchive.ietf.org/arch/msg/oauth/23ARrozt4RUUHA_NRiet7c38oIA
http://www.etsi.org/deliver/etsi_ts/103400_103499/103407/01.01.01_60/ts_103407v010101p.pdf

There is also a different use for this mechanism as stated here:
https://mailarchive.ietf.org/arch/msg/oauth/VzEo9rqC3kmqCuLFR-JcYQvIM3Q

Personnel:

The document shepherd is Rifaat Shekh-Yusef.
The responsible Area Director is Eric Rescorla.


(3) Briefly describe the review of this document that was performed by the Document Shepherd. If this version of the document is not ready for publication, please explain why the document is being forwarded to the IESG.

The document shepherd has reviewed several versions of this document, including the last one, feels the document is ready.


(4) Does the document Shepherd have any concerns about the depth or breadth of the reviews that have been performed?

The document shepherd has no concerns with the level of reviews, as the document was discussed and reviewed by many participants.


(5) Do portions of the document need review from a particular or from broader perspective, e.g., security, operational complexity, AAA, DNS, DHCP, XML, or internationalization? If so, describe the review that took place.

Security review is always needed and appreciated.


(6) Describe any specific concerns or issues that the Document Shepherd has with this document that the Responsible Area Director and/or the IESG should be aware of? For example, perhaps he or she is uncomfortable with certain parts of the document, or has concerns whether there really is a need for it. In any event, if the WG has discussed those issues and has indicated that it still wishes to advance the document, detail those concerns here.

The document shepherd has no such concerns.


(7) Has each author confirmed that any and all appropriate IPR disclosures required for full conformance with the provisions of BCP 78 and BCP 79 have already been filed. If not, explain why?

Yes.
John: https://www.ietf.org/mail-archive/web/oauth/current/msg17698.html
Mike: https://www.ietf.org/mail-archive/web/oauth/current/msg17704.html
William: https://www.ietf.org/mail-archive/web/oauth/current/msg17705.html
Hannes: https://www.ietf.org/mail-archive/web/oauth/current/msg17706.html


(8) Has an IPR disclosure been filed that references this document? If so, summarize any WG discussion and conclusion regarding the IPR disclosures.

No such IPR disclosures.


(9) How solid is the WG consensus behind this document? Does it represent the strong concurrence of a few individuals, with others being silent, or does the WG as a whole understand and agree with it?

There is a solid support for this document from the WG.


(10) Has anyone threatened an appeal or otherwise indicated extreme discontent? If so, please summarise the areas of conflict in separate email messages to the Responsible Area Director. (It should be in a separate email because this questionnaire is publicly available.)

No such threat or discontent.


(11) Identify any ID nits the Document Shepherd has found in this document. (See http://www.ietf.org/tools/idnits/ and the Internet-Drafts Checklist). Boilerplate checks are not enough; this check needs to be thorough.

Section 7.1.1, last bullet, should point to section 3.2 instead of 3.1

The following is the IETF tools nits reports:

idnits 2.15.00

/tmp/draft-ietf-oauth-device-flow-07.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 :
  ----------------------------------------------------------------------------

  ** There is 1 instance of too long lines in the document, the longest one
    being 14 characters in excess of 72.


  Miscellaneous warnings:
  ----------------------------------------------------------------------------

  == The copyright year in the IETF Trust and authors Copyright Line does not
    match the current year

  -- The document date (October 30, 2017) is 66 days in the past.  Is this
    intentional?


  Checking references for intended status: Proposed Standard
  ----------------------------------------------------------------------------

    (See RFCs 3967 and 4897 for information about using normative references
    to lower-maturity documents in RFCs)

  == Outdated reference: A later version (-08) exists of
    draft-ietf-oauth-discovery-05

  ** Downref: Normative reference to an Informational RFC: RFC 6755

  ** Downref: Normative reference to an Informational RFC: RFC 6819


    Summary: 3 errors (**), 0 flaws (~~), 2 warnings (==), 1 comment (--).

    Run idnits with the --verbose option for more detailed information about
    the items above.


(12) Describe how the document meets any required formal review criteria, such as the MIB Doctor, media type, and URI type reviews.

No such reviews are necessary.


(13) Have all references within this document been identified as either normative or informative?

Yes.


(14) Are there normative references to documents that are not ready for advancement or are otherwise in an unclear state? If such normative references exist, what is the plan for their completion?

The document references the OAuth 2.0 Authorization Server Metadata document, which is under IESG Evaluation at this stage.
https://datatracker.ietf.org/doc/draft-ietf-oauth-discovery/


(15) Are there downward normative references (see RFC 3967)? If so, list these downward references to support the Area Director in the Last Call procedure.

From the nits:
  ** Downref: Normative reference to an Informational RFC: RFC 6755

  ** Downref: Normative reference to an Informational RFC: RFC 6819


(16) Will publication of this document change the status of any existing RFCs? Are those RFCs listed on the title page header, listed in the abstract, and discussed in the introduction? If the RFCs are not listed in the Abstract and Introduction, explain why, and point to the part of the document where the relationship of this document to the other RFCs is discussed. If this information is not in the document, explain why the WG considers it unnecessary.

No status change of any existing RFCs.


(17) Describe the Document Shepherd's review of the IANA considerations section, especially with regard to its consistency with the body of the document. Confirm that all protocol extensions that the document makes are associated with the appropriate reservations in IANA registries. Confirm that any referenced IANA registries have been clearly identified. Confirm that newly created IANA registries include a detailed specification of the initial contents for the registry, that allocations procedures for future registrations are defined, and a reasonable name for the new registry has been suggested (see RFC 5226).

The IANA section is complete and correct.


(18) List any new IANA registries that require Expert Review for future allocations. Provide any public guidance that the IESG would find useful in selecting the IANA Experts for these new registries.

No new IANA registries.


(19) Describe reviews and automated checks performed by the Document Shepherd to validate sections of the document written in a formal language, such as XML code, BNF rules, MIB definitions, etc.

The document contains JSON-based examples, and these were validated using JSONLint.