draft-ietf-oauth-device-flow-13.txt   draft-ietf-oauth-device-flow-14.txt 
OAuth W. Denniss OAuth W. Denniss
Internet-Draft Google Internet-Draft Google
Intended status: Standards Track J. Bradley Intended status: Standards Track J. Bradley
Expires: April 22, 2019 Ping Identity Expires: July 20, 2019 Ping Identity
M. Jones M. Jones
Microsoft Microsoft
H. Tschofenig H. Tschofenig
ARM Limited ARM Limited
October 19, 2018 January 16, 2019
OAuth 2.0 Device Flow for Browserless and Input Constrained Devices OAuth 2.0 Device Flow for Browserless and Input Constrained Devices
draft-ietf-oauth-device-flow-13 draft-ietf-oauth-device-flow-14
Abstract Abstract
This OAuth 2.0 authorization flow is designed for devices that either This OAuth 2.0 authorization flow is designed for devices that either
lack a browser to perform a user-agent based OAuth flow, or are lack a browser to perform a user-agent based OAuth flow, or are
input-constrained to the extent that requiring the user to input a input-constrained to the extent that requiring the user to input a
lot of text (like their credentials to authenticate with the lot of text (like their credentials to authenticate with the
authorization server) is impractical. It enables OAuth clients on authorization server) is impractical. It enables OAuth clients on
such devices (like smart TVs, media consoles, digital picture frames, such devices (like smart TVs, media consoles, digital picture frames,
and printers) to obtain user authorization to access protected and printers) to obtain user authorization to access protected
skipping to change at page 1, line 43 skipping to change at page 1, line 43
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet- working documents as Internet-Drafts. The list of current Internet-
Drafts is at https://datatracker.ietf.org/drafts/current/. Drafts is at https://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
This Internet-Draft will expire on April 22, 2019. This Internet-Draft will expire on July 20, 2019.
Copyright Notice Copyright Notice
Copyright (c) 2018 IETF Trust and the persons identified as the Copyright (c) 2019 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents Provisions Relating to IETF Documents
(https://trustee.ietf.org/license-info) in effect on the date of (https://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents publication of this document. Please review these documents
carefully, as they describe your rights and restrictions with respect carefully, as they describe your rights and restrictions with respect
to this document. Code Components extracted from this document must to this document. Code Components extracted from this document must
include Simplified BSD License text as described in Section 4.e of include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as the Trust Legal Provisions and are provided without warranty as
skipping to change at page 2, line 34 skipping to change at page 2, line 34
3.4. Device Access Token Request . . . . . . . . . . . . . . . 9 3.4. Device Access Token Request . . . . . . . . . . . . . . . 9
3.5. Device Access Token Response . . . . . . . . . . . . . . 10 3.5. Device Access Token Response . . . . . . . . . . . . . . 10
4. Discovery Metadata . . . . . . . . . . . . . . . . . . . . . 12 4. Discovery Metadata . . . . . . . . . . . . . . . . . . . . . 12
5. Security Considerations . . . . . . . . . . . . . . . . . . . 12 5. Security Considerations . . . . . . . . . . . . . . . . . . . 12
5.1. User Code Brute Forcing . . . . . . . . . . . . . . . . . 12 5.1. User Code Brute Forcing . . . . . . . . . . . . . . . . . 12
5.2. Device Code Brute Forcing . . . . . . . . . . . . . . . . 13 5.2. Device Code Brute Forcing . . . . . . . . . . . . . . . . 13
5.3. Device Trustworthiness . . . . . . . . . . . . . . . . . 13 5.3. Device Trustworthiness . . . . . . . . . . . . . . . . . 13
5.4. Remote Phishing . . . . . . . . . . . . . . . . . . . . . 13 5.4. Remote Phishing . . . . . . . . . . . . . . . . . . . . . 13
5.5. Session Spying . . . . . . . . . . . . . . . . . . . . . 14 5.5. Session Spying . . . . . . . . . . . . . . . . . . . . . 14
5.6. Non-confidential Clients . . . . . . . . . . . . . . . . 14 5.6. Non-confidential Clients . . . . . . . . . . . . . . . . 14
5.7. Non-Visual Code Transmission . . . . . . . . . . . . . . 14 5.7. Non-Visual Code Transmission . . . . . . . . . . . . . . 15
6. Usability Considerations . . . . . . . . . . . . . . . . . . 14 6. Usability Considerations . . . . . . . . . . . . . . . . . . 15
6.1. User Code Recommendations . . . . . . . . . . . . . . . . 15 6.1. User Code Recommendations . . . . . . . . . . . . . . . . 15
6.2. Non-Browser User Interaction . . . . . . . . . . . . . . 16 6.2. Non-Browser User Interaction . . . . . . . . . . . . . . 16
7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 16 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 16
7.1. OAuth Parameters Registration . . . . . . . . . . . . . . 16 7.1. OAuth Parameters Registration . . . . . . . . . . . . . . 16
7.1.1. Registry Contents . . . . . . . . . . . . . . . . . . 16 7.1.1. Registry Contents . . . . . . . . . . . . . . . . . . 16
7.2. OAuth URI Registration . . . . . . . . . . . . . . . . . 16 7.2. OAuth URI Registration . . . . . . . . . . . . . . . . . 17
7.2.1. Registry Contents . . . . . . . . . . . . . . . . . . 16 7.2.1. Registry Contents . . . . . . . . . . . . . . . . . . 17
7.3. OAuth Extensions Error Registration . . . . . . . . . . . 16 7.3. OAuth Extensions Error Registration . . . . . . . . . . . 17
7.3.1. Registry Contents . . . . . . . . . . . . . . . . . . 17 7.3.1. Registry Contents . . . . . . . . . . . . . . . . . . 17
7.4. OAuth 2.0 Authorization Server Metadata . . . . . . . . . 17 7.4. OAuth 2.0 Authorization Server Metadata . . . . . . . . . 18
7.4.1. Registry Contents . . . . . . . . . . . . . . . . . . 17 7.4.1. Registry Contents . . . . . . . . . . . . . . . . . . 18
8. Normative References . . . . . . . . . . . . . . . . . . . . 17 8. Normative References . . . . . . . . . . . . . . . . . . . . 18
Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 18 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 19
Appendix B. Document History . . . . . . . . . . . . . . . . . . 19 Appendix B. Document History . . . . . . . . . . . . . . . . . . 19
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 21 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 21
1. Introduction 1. Introduction
This OAuth 2.0 [RFC6749] protocol flow for browserless and input- This OAuth 2.0 [RFC6749] protocol extension known as the "device
constrained devices, often referred to as the device flow, enables flow" enables OAuth clients to request user authorization from
OAuth clients to request user authorization from applications on applications on devices that have limited input capabilities or lack
devices that have an Internet connection, but don't have an easy a suitable browser. Such devices include those smart TVs, media
input method (such as a smart TV, media console, picture frame, or console, picture frames and printers which lack an easy input method
printer), or lack a suitable browser for a more traditional OAuth or suitable browser required for a more traditional OAuth flow. This
flow. This authorization flow instructs the user to perform the authorization flow instructs the user to perform the authorization
authorization request on a secondary device, such as a smartphone. request on a secondary device, such as a smartphone which does have
the requisite input and browser capabilities for an OAuth flow.
The device flow is not intended to replace browser-based OAuth in The device flow is not intended to replace browser-based OAuth in
native apps on capable devices (like smartphones). Those apps should native apps on capable devices (like smartphones). Those apps should
follow the practices specified in OAuth 2.0 for Native Apps follow the practices specified in OAuth 2.0 for Native Apps
[RFC8252]. [RFC8252].
The operating requirements to be able to use this authorization flow The operating requirements to be able to use this authorization flow
are: are:
(1) The device is already connected to the Internet. (1) The device is already connected to the Internet.
skipping to change at page 6, line 35 skipping to change at page 6, line 35
All requests from the device MUST use the Transport Layer Security All requests from the device MUST use the Transport Layer Security
(TLS) [RFC8446] protocol and implement the best practices of BCP 195 (TLS) [RFC8446] protocol and implement the best practices of BCP 195
[RFC7525]. [RFC7525].
Parameters sent without a value MUST be treated as if they were Parameters sent without a value MUST be treated as if they were
omitted from the request. The authorization server MUST ignore omitted from the request. The authorization server MUST ignore
unrecognized request parameters. Request and response parameters unrecognized request parameters. Request and response parameters
MUST NOT be included more than once. MUST NOT be included more than once.
Due to the polling nature of this protocol, to avoid unneeded Due to the polling nature of this protocol, care is needed to avoid
overloading the capacity of the token endpoint. To avoid unneeded
requests on the token endpoint, the client SHOULD only commence a requests on the token endpoint, the client SHOULD only commence a
device authorization request when prompted by the user, and not device authorization request when prompted by the user, and not
automatically such as when the app starts. automatically such as when the app starts or when the previous
authorization session expires or fails.
3.2. Device Authorization Response 3.2. Device Authorization Response
In response, the authorization server generates a unique device In response, the authorization server generates a unique device
verification code and an end-user code that are valid for a limited verification code and an end-user code that are valid for a limited
time and includes them in the HTTP response body using the time and includes them in the HTTP response body using the
"application/json" format [RFC8259] with a 200 (OK) status code. The "application/json" format [RFC8259] with a 200 (OK) status code. The
response contains the following parameters: response contains the following parameters:
device_code device_code
skipping to change at page 11, line 40 skipping to change at page 11, line 40
session has concluded. The client MAY commence a new Device session has concluded. The client MAY commence a new Device
Authorization Request but SHOULD wait for user interaction before Authorization Request but SHOULD wait for user interaction before
restarting to avoid unnecessary polling. restarting to avoid unnecessary polling.
A client receiving an error response as defined in Section 5.2 of A client receiving an error response as defined in Section 5.2 of
[RFC6749] MUST stop polling and SHOULD react accordingly, for [RFC6749] MUST stop polling and SHOULD react accordingly, for
example, by displaying an error to the user, except for the error example, by displaying an error to the user, except for the error
codes "authorization_pending" and "slow_down" which are processed as codes "authorization_pending" and "slow_down" which are processed as
described above. described above.
On encountering a connection timeout, clients MUST unilaterally
reduce their polling frequency before retrying. The use of an
exponential backoff algorithm to achieve this, such as by doubling
the polling interval on each such connection timeout, is RECOMMENDED.
The assumption of this specification is that the secondary device the The assumption of this specification is that the secondary device the
user is authorizing the request on does not have a way to communicate user is authorizing the request on does not have a way to communicate
back to the OAuth client. Only a one-way channel is required to make back to the OAuth client. Only a one-way channel is required to make
this flow useful in many scenarios. For example, an HTML application this flow useful in many scenarios. For example, an HTML application
on a TV that can only make outbound requests. If a return channel on a TV that can only make outbound requests. If a return channel
were to exist for the chosen user interaction interface, then the were to exist for the chosen user interaction interface, then the
device MAY wait until notified on that channel that the user has device MAY wait until notified on that channel that the user has
completed the action before initiating the token request (as an completed the action before initiating the token request (as an
alternative to polling). Such behavior is, however, outside the alternative to polling). Such behavior is, however, outside the
scope of this specification. scope of this specification.
skipping to change at page 14, line 20 skipping to change at page 14, line 24
(allowing the user to retrieve their secondary device, navigate to (allowing the user to retrieve their secondary device, navigate to
the verification URI, login, etc.), but should be sufficiently short the verification URI, login, etc.), but should be sufficiently short
to limit the usability of a code obtained for phishing. This doesn't to limit the usability of a code obtained for phishing. This doesn't
prevent a phisher presenting a fresh token, particularly in the case prevent a phisher presenting a fresh token, particularly in the case
they are interacting with the user in real time, but it does limit they are interacting with the user in real time, but it does limit
the viability of codes sent over email or SMS. the viability of codes sent over email or SMS.
5.5. Session Spying 5.5. Session Spying
While the device is pending authorization, it may be possible for a While the device is pending authorization, it may be possible for a
malicious user to spy on the device user interface and hijack the malicious user to physically spy on the device user interface (by
session by completing the authorization faster than the user that viewing the screen on which it's displayed, for example) and hijack
the session by completing the authorization faster than the user that
initiated it. Devices SHOULD take into account the operating initiated it. Devices SHOULD take into account the operating
environment when considering how to communicate the code to the user environment when considering how to communicate the code to the user
to reduce the chances it will be observed by a malicious user. to reduce the chances it will be observed by a malicious user.
5.6. Non-confidential Clients 5.6. Non-confidential Clients
Most device clients are incapable of being confidential clients, as Device clients are generally incapable of maintaining the
secrets that are statically included as part of an app distributed to confidentiality of their credentials, as users in possession of the
multiple users cannot be considered confidential. For such clients, device can reverse engineer it and extract the credentials.
the recommendations of Section 5.3.1 of [RFC6819] and Section 8.5 of Therefore, unless additional measures are taken, they should be
[RFC8252] apply. treated as public clients (as defined by Section 2.1 of OAuth 2.0)
susceptible to impersonation. The security considerations of
Section 5.3.1 of [RFC6819] and Sections 8.5 and 8.6 of [RFC8252]
apply to such clients.
The user may also be able to obtain the device_code and/or other
OAuth bearer tokens issued to their client, which would allow them to
use their own authorization grant directly by impersonating the
client. Given that the user in possession of the client credentials
can already impersonate the client and create a new authorization
grant (with a new device_code), this doesn't represent a separate
impersonation vector.
5.7. Non-Visual Code Transmission 5.7. Non-Visual Code Transmission
There is no requirement that the user code be displayed by the device There is no requirement that the user code be displayed by the device
visually. Other methods of one-way communication can potentially be visually. Other methods of one-way communication can potentially be
used, such as text-to-speech audio, or Bluetooth Low Energy. To used, such as text-to-speech audio, or Bluetooth Low Energy. To
mitigate an attack in which a malicious user can bootstrap their mitigate an attack in which a malicious user can bootstrap their
credentials on a device not in their control, it is RECOMMENDED that credentials on a device not in their control, it is RECOMMENDED that
any chosen communication channel only be accessible by people in any chosen communication channel only be accessible by people in
close proximity. E.g., users who can see, or hear the device. close proximity. E.g., users who can see, or hear the device.
skipping to change at page 19, line 25 skipping to change at page 19, line 46
Adam Roach, Alissa Cooper, Ben Campbell, Brian Campbell, Benjamin Adam Roach, Alissa Cooper, Ben Campbell, Brian Campbell, Benjamin
Kaduk, Roshni Chandrashekhar, Eric Fazendin, Torsten Lodderstedt, Kaduk, Roshni Chandrashekhar, Eric Fazendin, Torsten Lodderstedt,
James Manger, Breno de Medeiros, Simon Moffatt, Stein Myrseth, Justin James Manger, Breno de Medeiros, Simon Moffatt, Stein Myrseth, Justin
Richer, Nat Sakimura, Andrew Sciberras, Marius Scurtescu, Ken Wang, Richer, Nat Sakimura, Andrew Sciberras, Marius Scurtescu, Ken Wang,
and Steven E. Wright. and Steven E. Wright.
Appendix B. Document History Appendix B. Document History
[[ to be removed by the RFC Editor before publication as an RFC ]] [[ to be removed by the RFC Editor before publication as an RFC ]]
-13 -14
o Added more normative text on polling behavior.
o Added discussion on risk of user retrieving their own device_code.
o Editorial improvements.
-13
o Added a longer discussion about entropy, proposed by Benjamin o Added a longer discussion about entropy, proposed by Benjamin
Kaduk. Kaduk.
o Added device_code to OAuth IANA registry. o Added device_code to OAuth IANA registry.
o Expanded explanation of "case insensitive". o Expanded explanation of "case insensitive".
o Added security section on Device Code Brute Forcing. o Added security section on Device Code Brute Forcing.
o application/x-www-form-urlencoded normativly referenced. o application/x-www-form-urlencoded normativly referenced.
o Editatorial improvements. o Editorial improvements.
-12 -12
o Set a default polling interval to 5s explicitly. o Set a default polling interval to 5s explicitly.
o Defined the slow_down behavior that it should increase the current o Defined the slow_down behavior that it should increase the current
interval by 5s. interval by 5s.
o expires_in now REQUIRED o expires_in now REQUIRED
o Other changes in response to review feedback. o Other changes in response to review feedback.
-11 -11
 End of changes. 17 change blocks. 
33 lines changed or deleted 58 lines changed or added

This html diff was produced by rfcdiff 1.47. The latest version is available from http://tools.ietf.org/tools/rfcdiff/