< draft-ietf-oauth-device-flow-08.txt   draft-ietf-oauth-device-flow-09.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: September 20, 2018 Ping Identity Expires: October 22, 2018 Ping Identity
M. Jones M. Jones
Microsoft Microsoft
H. Tschofenig H. Tschofenig
ARM Limited ARM Limited
March 19, 2018 April 20, 2018
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-08 draft-ietf-oauth-device-flow-09
Abstract Abstract
This OAuth 2.0 authorization flow for browserless and input This OAuth 2.0 authorization flow for browserless and input
constrained devices, often referred to as the device flow, enables constrained devices, often referred to as the device flow, enables
OAuth clients to request user authorization from devices that have an OAuth clients to request user authorization from devices that have an
Internet connection, but don't have an easy input method (such as a Internet connection, but don't have an easy input method (such as a
smart TV, media console, picture frame, or printer), or lack a smart TV, media console, picture frame, or printer), or lack a
suitable browser for a more traditional OAuth flow. This suitable browser for a more traditional OAuth flow. This
authorization flow instructs the user to perform the authorization authorization flow instructs the user to perform the authorization
skipping to change at page 1, line 44 skipping to change at page 1, line 44
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 September 20, 2018. This Internet-Draft will expire on October 22, 2018.
Copyright Notice Copyright Notice
Copyright (c) 2018 IETF Trust and the persons identified as the Copyright (c) 2018 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
skipping to change at page 2, line 36 skipping to change at page 2, line 36
3.2. Device Authorization Response . . . . . . . . . . . . . . 6 3.2. Device Authorization Response . . . . . . . . . . . . . . 6
3.3. User Interaction . . . . . . . . . . . . . . . . . . . . 7 3.3. User Interaction . . . . . . . . . . . . . . . . . . . . 7
3.3.1. Non-textual Verification URI Optimization . . . . . . 8 3.3.1. Non-textual Verification URI Optimization . . . . . . 8
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 . . . . . . . . . . . . . . . . . . . . . 11 4. Discovery Metadata . . . . . . . . . . . . . . . . . . . . . 11
5. Security Considerations . . . . . . . . . . . . . . . . . . . 11 5. Security Considerations . . . . . . . . . . . . . . . . . . . 11
5.1. User Code Brute Forcing . . . . . . . . . . . . . . . . . 11 5.1. User Code Brute Forcing . . . . . . . . . . . . . . . . . 11
5.2. Device Trustworthiness . . . . . . . . . . . . . . . . . 12 5.2. Device Trustworthiness . . . . . . . . . . . . . . . . . 12
5.3. Remote Phishing . . . . . . . . . . . . . . . . . . . . . 12 5.3. Remote Phishing . . . . . . . . . . . . . . . . . . . . . 12
5.4. Session Spying . . . . . . . . . . . . . . . . . . . . . 12 5.4. Session Spying . . . . . . . . . . . . . . . . . . . . . 13
5.5. Non-confidential Clients . . . . . . . . . . . . . . . . 12 5.5. Non-confidential Clients . . . . . . . . . . . . . . . . 13
5.6. Non-Visual Code Transmission . . . . . . . . . . . . . . 13 5.6. Non-Visual Code Transmission . . . . . . . . . . . . . . 13
6. Usability Considerations . . . . . . . . . . . . . . . . . . 13 6. Usability Considerations . . . . . . . . . . . . . . . . . . 13
6.1. User Code Recommendations . . . . . . . . . . . . . . . . 13 6.1. User Code Recommendations . . . . . . . . . . . . . . . . 13
6.2. Non-Browser User Interaction . . . . . . . . . . . . . . 14 6.2. Non-Browser User Interaction . . . . . . . . . . . . . . 14
7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 14 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 14
7.1. OAuth URI Registration . . . . . . . . . . . . . . . . . 14 7.1. OAuth URI Registration . . . . . . . . . . . . . . . . . 14
7.1.1. Registry Contents . . . . . . . . . . . . . . . . . . 14 7.1.1. Registry Contents . . . . . . . . . . . . . . . . . . 14
7.2. OAuth Extensions Error Registration . . . . . . . . . . . 14 7.2. OAuth Extensions Error Registration . . . . . . . . . . . 15
7.2.1. Registry Contents . . . . . . . . . . . . . . . . . . 14 7.2.1. Registry Contents . . . . . . . . . . . . . . . . . . 15
7.3. OAuth 2.0 Authorization Server Metadata . . . . . . . . . 15 7.3. OAuth 2.0 Authorization Server Metadata . . . . . . . . . 15
7.3.1. Registry Contents . . . . . . . . . . . . . . . . . . 15 7.3.1. Registry Contents . . . . . . . . . . . . . . . . . . 15
8. Normative References . . . . . . . . . . . . . . . . . . . . 15 8. Normative References . . . . . . . . . . . . . . . . . . . . 15
Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 16 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 16
Appendix B. Document History . . . . . . . . . . . . . . . . . . 16 Appendix B. Document History . . . . . . . . . . . . . . . . . . 16
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 17 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 18
1. Introduction 1. Introduction
This OAuth 2.0 protocol flow for browserless and input constrained This OAuth 2.0 protocol flow for browserless and input constrained
devices, often referred to as the device flow, enables OAuth clients devices, often referred to as the device flow, enables OAuth clients
to request user authorization from devices that have an internet to request user authorization from devices that have an internet
connection, but don't have an easy input method (such as a smart TV, 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 media console, picture frame, or printer), or lack a suitable browser
for a more traditional OAuth flow. This authorization flow instructs for a more traditional OAuth flow. This authorization flow instructs
the user to perform the authorization request on a secondary device, the user to perform the authorization request on a secondary device,
skipping to change at page 6, line 22 skipping to change at page 6, line 22
client_id=459691054427 client_id=459691054427
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.
3.2. Device Authorization Response 3.2. Device Authorization Response
In response, the authorization server generates a device verification In response, the authorization server generates a device verification
code and an end-user code that are valid for a limited time, and 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" includes them in the HTTP response body using the "application/json"
format with a 200 (OK) status code. The response contains the format with a 200 (OK) status code. The response contains the
following parameters: following parameters:
device_code device_code
REQUIRED. The device verification code. REQUIRED. The device verification code.
user_code user_code
REQUIRED. The end-user verification code. REQUIRED. The end-user verification code.
skipping to change at page 7, line 22 skipping to change at page 7, line 22
"verification_uri":"https://www.example.com/device", "verification_uri":"https://www.example.com/device",
"verification_uri_complete":"https://www.example.com/device?user_code=WDJB-MJHT", "verification_uri_complete":"https://www.example.com/device?user_code=WDJB-MJHT",
"expires_in" : 1800, "expires_in" : 1800,
"interval": 5 "interval": 5
} }
3.3. User Interaction 3.3. User Interaction
After receiving a successful Authorization Response, the client After receiving a successful Authorization Response, the client
displays or otherwise communicates the "user_code" and the displays or otherwise communicates the "user_code" and the
"verification_uri" to the end-user, and instructs them to visit the "verification_uri" to the end-user and instructs them to visit the
URI in a user agent on a secondary device (for example, in a browser URI in a user agent on a secondary device (for example, in a browser
on their mobile phone), and enter the user code. on their mobile phone), and enter the user code.
+-----------------------------------------------+ +-----------------------------------------------+
| | | |
| Using a browser on another device, visit: | | Using a browser on another device, visit: |
| https://example.com/device | | https://example.com/device |
| | | |
| And enter the code: | | And enter the code: |
| WDJB-MJHT | | WDJB-MJHT |
| | | |
+-----------------------------------------------+ +-----------------------------------------------+
Figure 2: Example User Instruction Figure 2: Example User Instruction
The authorizing user navigates to the "verification_uri" and The authorizing user navigates to the "verification_uri" and
authenticates with the authorization server in a secure TLS-protected authenticates with the authorization server in a secure TLS-protected
session. The authorization server prompts the end-user to identify session. The authorization server prompts the end-user to identify
the device authorization session by entering the "user_code" provided the device authorization session by entering the "user_code" provided
by the client. The authorization server should then inform the user by the client. The authorization server should then inform the user
about the action they are undertaking, and ask them to approve or about the action they are undertaking and ask them to approve or deny
deny the request. Once the user interaction is complete, the server the request. Once the user interaction is complete, the server
informs the user to return to their device. informs the user to return to their device.
During the user interaction, the device continuously polls the token During the user interaction, the device continuously polls the token
endpoint with the "device_code", as detailed in Section 3.4, until endpoint with the "device_code", as detailed in Section 3.4, until
the user completes the interaction, the code expires, or another the user completes the interaction, the code expires, or another
error occurs. The "device_code" is not intended for the end-user and error occurs. The "device_code" is not intended for the end-user and
MUST NOT be displayed or communicated. MUST NOT be displayed or communicated.
Authorization servers supporting this specification MUST implement a Authorization servers supporting this specification MUST implement a
user interaction sequence that starts with the user navigating to user interaction sequence that starts with the user navigating to
"verification_uri" and continues with them supplying the "user_code" "verification_uri" and continues with them supplying the "user_code"
at some stage during the interaction. Other than that, the exact at some stage during the interaction. Other than that, the exact
sequence and implementation of the user interaction is up to the sequence and implementation of the user interaction is up to the
authorization server, and is out of scope of this specification. authorization server and is out of scope of this specification.
It is NOT RECOMMENDED for authorization servers to include the user It is NOT RECOMMENDED for authorization servers to include the user
code in the verification URI ("verification_uri"), as this increases code in the verification URI ("verification_uri"), as this increases
the length and complexity of the URI that the user must type. The the length and complexity of the URI that the user must type. The
next section documents user interaction with next section documents user interaction with
"verification_uri_complete", which is designed to carry this "verification_uri_complete", which is designed to carry this
information. information.
3.3.1. Non-textual Verification URI Optimization 3.3.1. Non-textual Verification URI Optimization
skipping to change at page 8, line 46 skipping to change at page 8, line 46
| Using a browser on another +------------+ | | Using a browser on another +------------+ |
| device, visit: |[_].. . [_]| | | device, visit: |[_].. . [_]| |
| https://example.com/device | . .. . .| | | https://example.com/device | . .. . .| |
| | . . . ....| | | | . . . ....| |
| |. . . . | | | |. . . . | |
| And enter the code: |[_]. ... . | | | And enter the code: |[_]. ... . | |
| WDJB-MJHT +------------+ | | WDJB-MJHT +------------+ |
| | | |
+-------------------------------------------------+ +-------------------------------------------------+
Figure 3: Example User Instruction With QR Code Representation of the Figure 3: Example User Instruction with QR Code Representation of the
Complete Verification URI Complete Verification URI
3.4. Device Access Token Request 3.4. Device Access Token Request
After displaying instructions to the user, the client makes an Access After displaying instructions to the user, the client makes an Access
Token Request to the token endpoint with a "grant_type" of Token Request to the token endpoint with a "grant_type" of
"urn:ietf:params:oauth:grant-type:device_code". This is an extension "urn:ietf:params:oauth:grant-type:device_code". This is an extension
grant type (as defined by Section 4.5 of [RFC6749]) with the grant type (as defined by Section 4.5 of [RFC6749]) with the
following parameters: following parameters:
skipping to change at page 12, line 13 skipping to change at page 12, line 13
the user code format. the user code format.
5.2. Device Trustworthiness 5.2. Device Trustworthiness
Unlike other native application OAuth 2.0 flows, the device Unlike other native application OAuth 2.0 flows, the device
requesting the authorization is not the same as the device that the requesting the authorization is not the same as the device that the
user grants access from. Thus, signals from the approving user's user grants access from. Thus, signals from the approving user's
session and device are not relevant to the trustworthiness of the session and device are not relevant to the trustworthiness of the
client device. client device.
Note that if an authorization server used with this flow is
malicious, then it could man-in-the middle the backchannel flow to
another authorization server. In this scenario, the man-in-the-
middle is not completely hidden from sight, as the end-user would end
up on the authorization page of the wrong service, giving them an
opportunity to notice that the authorization being requested is
wrong. For this to be possible, the device manufacturer must either
directly be the attacker, shipping a device intended to perform the
man-in-the-middle attack, or be using an authorization server that is
controlled by an attacker, possibly because the attacker compromised
the authorization server used by the device. In part, the person
purchasing the device is counting on it and its business partners to
be trustworthy.
5.3. Remote Phishing 5.3. Remote Phishing
It is possible for the device flow to be initiated on a device in an It is possible for the device flow to be initiated on a device in an
attacker's possession. For example, the attacker might send an email attacker's possession. For example, the attacker might send an email
instructing the target user to visit the verification URL and enter instructing the target user to visit the verification URL and enter
the user code. To mitigate such an attack, it is RECOMMENDED to the user code. To mitigate such an attack, it is RECOMMENDED to
inform the user that they are authorizing a device during the user inform the user that they are authorizing a device during the user
interaction step (see Section 3.3), and to confirm that the device is interaction step (see Section 3.3), and to confirm that the device is
in their possession. in their possession. The authorization server SHOULD display
information about the device so that the person can notice if a
software client was attempting to impersonating a hardware device.
For authorization servers that support the option specified in For authorization servers that support the option specified in
Section 3.3.1 for the client to append the user code to the Section 3.3.1 for the client to append the user code to the
authorization URI, it is particularly important to confirm that the authorization URI, it is particularly important to confirm that the
device is in the user's possession, as the user no longer has to type device is in the user's possession, as the user no longer has to type
the code manually. One possibility is to display the code during the the code manually. One possibility is to display the code during the
authorization flow, and asking the user to verify that the same code authorization flow and asking the user to verify that the same code
is being displayed on the device they are setting up. is being displayed on the device they are setting up.
The user code needs to have a long enough lifetime to be useable The user code needs to have a long enough lifetime to be useable
(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.
skipping to change at page 15, line 30 skipping to change at page 15, line 49
o Metadata name: device_authorization_endpoint o Metadata name: device_authorization_endpoint
o Metadata Description: The Device Authorization Endpoint. o Metadata Description: The Device Authorization Endpoint.
o Change controller: IESG o Change controller: IESG
o Specification Document: Section 4 of [[ this specification ]] o Specification Document: Section 4 of [[ this specification ]]
8. Normative References 8. Normative References
[I-D.ietf-oauth-discovery] [I-D.ietf-oauth-discovery]
Jones, M., Sakimura, N., and J. Bradley, "OAuth 2.0 Jones, M., Sakimura, N., and J. Bradley, "OAuth 2.0
Authorization Server Metadata", draft-ietf-oauth- Authorization Server Metadata", draft-ietf-oauth-
discovery-05 (work in progress), January 2017. discovery-10 (work in progress), March 2018.
[IANA.OAuth.Parameters] [IANA.OAuth.Parameters]
IANA, "OAuth Parameters", IANA, "OAuth Parameters",
<http://www.iana.org/assignments/oauth-parameters>. <http://www.iana.org/assignments/oauth-parameters>.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, Requirement Levels", BCP 14, RFC 2119,
DOI 10.17487/RFC2119, March 1997, DOI 10.17487/RFC2119, March 1997,
<https://www.rfc-editor.org/info/rfc2119>. <https://www.rfc-editor.org/info/rfc2119>.
skipping to change at page 16, line 35 skipping to change at page 16, line 52
that shaped and formed the final specification: that shaped and formed the final specification:
Roshni Chandrashekhar, Marius Scurtescu, Breno de Medeiros, Stein Roshni Chandrashekhar, Marius Scurtescu, Breno de Medeiros, Stein
Myrseth, Simon Moffatt, Brian Campbell, James Manger, Justin Richer, Myrseth, Simon Moffatt, Brian Campbell, James Manger, Justin Richer,
Ken Wang, Steven E. Wright, Nat Sakimura, and Torsten Lodderstedt. Ken Wang, Steven E. Wright, Nat Sakimura, and Torsten Lodderstedt.
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 ]]
-09
o Addressed review comments by Security Area Director Eric Rescorla
about the potential of a confused deputy attack.
-08
o Expanded the User Code Brute Forcing section to include more
detail on this attack.
-07 -07
o Replaced the "user_code" URI parameter optimization with o Replaced the "user_code" URI parameter optimization with
verification_uri_complete following the IETF99 working group verification_uri_complete following the IETF99 working group
discussion. discussion.
o Added security consideration about spying. o Added security consideration about spying.
o Required that device_code not be shown. o Required that device_code not be shown.
o Added text regarding a minimum polling interval. o Added text regarding a minimum polling interval.
-06 -06
 End of changes. 17 change blocks. 
18 lines changed or deleted 43 lines changed or added

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