< draft-ietf-oauth-device-flow-05.txt   draft-ietf-oauth-device-flow-06.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 14, 2017 Ping Identity Expires: December 2, 2017 Ping Identity
M. Jones M. Jones
Microsoft Microsoft
H. Tschofenig H. Tschofenig
ARM Limited ARM Limited
March 13, 2017 May 31, 2017
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-05 draft-ietf-oauth-device-flow-06
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 http://datatracker.ietf.org/drafts/current/. Drafts is at http://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 14, 2017. This Internet-Draft will expire on December 2, 2017.
Copyright Notice Copyright Notice
Copyright (c) 2017 IETF Trust and the persons identified as the Copyright (c) 2017 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
(http://trustee.ietf.org/license-info) in effect on the date of (http://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 27 skipping to change at page 2, line 27
the Trust Legal Provisions and are provided without warranty as the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License. described in the Simplified BSD License.
Table of Contents Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3
2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 5 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 5
3. Protocol . . . . . . . . . . . . . . . . . . . . . . . . . . 5 3. Protocol . . . . . . . . . . . . . . . . . . . . . . . . . . 5
3.1. Device Authorization Request . . . . . . . . . . . . . . 5 3.1. Device Authorization Request . . . . . . . . . . . . . . 5
3.2. Device Authorization Response . . . . . . . . . . . . . . 6 3.2. Device Authorization Response . . . . . . . . . . . . . . 6
3.3. User Instruction . . . . . . . . . . . . . . . . . . . . 7 3.3. User Interaction . . . . . . . . . . . . . . . . . . . . 7
3.3.1. Optimization for Non-textual Verification URIs . . . 8
3.4. Device Access Token Request . . . . . . . . . . . . . . . 8 3.4. Device Access Token Request . . . . . . . . . . . . . . . 8
3.5. Device Access Token Response . . . . . . . . . . . . . . 9 3.5. Device Access Token Response . . . . . . . . . . . . . . 9
4. Discovery Metadata . . . . . . . . . . . . . . . . . . . . . 10 4. Discovery Metadata . . . . . . . . . . . . . . . . . . . . . 10
5. Security Considerations . . . . . . . . . . . . . . . . . . . 10 5. Security Considerations . . . . . . . . . . . . . . . . . . . 10
5.1. User Code Brute Forcing . . . . . . . . . . . . . . . . . 10 5.1. User Code Brute Forcing . . . . . . . . . . . . . . . . . 11
5.2. Device Trustworthiness . . . . . . . . . . . . . . . . . 10 5.2. Device Trustworthiness . . . . . . . . . . . . . . . . . 11
5.3. Remote Phishing . . . . . . . . . . . . . . . . . . . . . 10 5.3. Remote Phishing . . . . . . . . . . . . . . . . . . . . . 11
5.4. Non-confidential Clients . . . . . . . . . . . . . . . . 11 5.4. Non-confidential Clients . . . . . . . . . . . . . . . . 11
5.5. Non-Visual Code Transmission . . . . . . . . . . . . . . 11 5.5. Non-Visual Code Transmission . . . . . . . . . . . . . . 12
6. Usability Considerations . . . . . . . . . . . . . . . . . . 11 6. Usability Considerations . . . . . . . . . . . . . . . . . . 12
6.1. User Code Recommendations . . . . . . . . . . . . . . . . 11 6.1. User Code Recommendations . . . . . . . . . . . . . . . . 12
6.2. Non-Browser User Interaction . . . . . . . . . . . . . . 12 6.2. Non-Browser User Interaction . . . . . . . . . . . . . . 12
7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 12 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 13
7.1. OAuth URI Registration . . . . . . . . . . . . . . . . . 12 7.1. OAuth URI Registration . . . . . . . . . . . . . . . . . 13
7.1.1. Registry Contents . . . . . . . . . . . . . . . . . . 12 7.1.1. Registry Contents . . . . . . . . . . . . . . . . . . 13
7.2. OAuth Extensions Error Registration . . . . . . . . . . . 12 7.2. OAuth Extensions Error Registration . . . . . . . . . . . 13
7.2.1. Registry Contents . . . . . . . . . . . . . . . . . . 12 7.2.1. Registry Contents . . . . . . . . . . . . . . . . . . 13
7.3. OAuth 2.0 Authorization Server Metadata . . . . . . . . . 13 7.3. OAuth 2.0 Authorization Server Metadata . . . . . . . . . 14
7.3.1. Registry Contents . . . . . . . . . . . . . . . . . . 13 7.3.1. Registry Contents . . . . . . . . . . . . . . . . . . 14
8. Normative References . . . . . . . . . . . . . . . . . . . . 13 8. Normative References . . . . . . . . . . . . . . . . . . . . 14
Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 14 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 15
Appendix B. Document History . . . . . . . . . . . . . . . . . . 14 Appendix B. Document History . . . . . . . . . . . . . . . . . . 15
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 15 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 16
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 7, line 17 skipping to change at page 7, line 17
Cache-Control: no-store Cache-Control: no-store
{ {
"device_code":"GMMhmHCXhWEzkobqIHGG_EnNYYsAkukHspeYUk9E8", "device_code":"GMMhmHCXhWEzkobqIHGG_EnNYYsAkukHspeYUk9E8",
"user_code":"WDJB-MJHT", "user_code":"WDJB-MJHT",
"verification_uri":"https://www.example.com/device", "verification_uri":"https://www.example.com/device",
"expires_in" : 1800, "expires_in" : 1800,
"interval": 5 "interval": 5
} }
3.3. User Instruction 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.
The end-user navigates to the "verification_uri" and authenticates +-----------------------------------------------+
with the authorization server. The authorization server prompts the | |
end-user to identify the device authorization session by entering the | Using a browser on another device, visit: |
"user_code" provided by the client. The authorization server should | https://example.com/device |
then inform the user about the action they are undertaking, and ask | |
them to approve or deny the request. Once the user interaction is | And enter the code: |
complete, the server informs the user to return to their device. | WDJB-MJHT |
| |
+-----------------------------------------------+
Clients MAY additionally present the verification URI in a non- Figure 2: Example User Instruction
textual manner using any method that results in a the browser being
opened with the URI, like QR codes, or NFC, to save the user typing The authorizing user navigates to the "verification_uri" and
the URI. For such shortcuts, the client MAY include the user code authenticates with the authorization server in a secure TLS-protected
with the parameter "user_code" on the verification URI, as a hint for session. The authorization server prompts the end-user to identify
the authorization server. The server MAY accept this hint, and skip the device authorization session by entering the "user_code" provided
the user code input step, however the client MUST still display the by the client. The authorization server should then inform the user
user code, as the server MAY also ignore the hint or require visual about the action they are undertaking, and ask them to approve or
confirmation. Clients SHOULD still display the unmodified deny the request. Once the user interaction is complete, the server
verification URI for users not able to use such a shortcut. 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. error occurs.
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.
3.3.1. Optimization for Non-textual Verification URIs
Clients MAY present the verification URI in a non-textual manner
using any method that results in the browser being opened with the
URI, such as with QR codes, or NFC, to save the user typing the URI.
For usability reasons, it is RECOMMENDED for clients to still display
the unmodified verification URI for users not able to use such a
shortcut.
To optimize the user interaction for such non-textual verification
URI transmission, clients MAY include the user code as part of the
verification URI using the URI parameter "user_code".
An example verification URI with the user code included:
https://example.com/device?user_code=WDJB-MJHT
When the user code is included in the verification URI in this way,
it is considered as a hint to the authorization server to enable
potential optimizations. The authorization server MAY use this hint
to optimize the user interaction (such as by removing the need for
the user to type the code), it MAY also ignore it completely. The
client MUST still display the user code textually, for authorization
servers that require users to input the user code manually, or
otherwise use the user code as part of a visual confirmation step.
This optimization is intended for non-textual transmission of the
verification URI, it is NOT RECOMMENDED to include the user code in
verification URIs shown textually, as this increases the length and
complexity of the URI that the user must type.
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:
grant_type grant_type
REQUIRED. Value MUST be set to "urn:ietf:params:oauth:grant- REQUIRED. Value MUST be set to "urn:ietf:params:oauth:grant-
skipping to change at page 10, line 16 skipping to change at page 11, line 4
Support for the device flow MAY be declared in the OAuth 2.0 Support for the device flow MAY be declared in the OAuth 2.0
Authorization Server Metadata [I-D.ietf-oauth-discovery] with the Authorization Server Metadata [I-D.ietf-oauth-discovery] with the
following metadata: following metadata:
device_authorization_endpoint device_authorization_endpoint
OPTIONAL. URL of the authorization server's device authorization OPTIONAL. URL of the authorization server's device authorization
endpoint defined in Section 3.1. endpoint defined in Section 3.1.
5. Security Considerations 5. Security Considerations
5.1. User Code Brute Forcing 5.1. User Code Brute Forcing
Since the user code is typed by the user, the entropy is typically Since the user code is typed by the user, the entropy is typically
less than would be used for the device code or other OAuth bearer less than would be used for the device code or other OAuth bearer
token types. It is therefore recommended that the server rate-limit token types. It is therefore recommended that the server rate-limit
user code attempts. The user code SHOULD have enough entropy that user code attempts. The user code SHOULD have enough entropy that
when combined with rate limiting makes a brute-force attack when combined with rate limiting makes a brute-force attack
infeasible. infeasible.
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.
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 they might send an attacker's possession. For example, the attacker might send an email
email instructing the target user to visit the verification URL and instructing the target user to visit the verification URL and enter
enter the user code. To mitigate such an attack, it is RECOMMENDED the user code. To mitigate such an attack, it is RECOMMENDED to
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.
For authorization servers that support the option specified in
Section 3.3.1 for the client to append the user code to 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
the code manually. One possibility is to display the code during the
authorization flow, and asking the user to verify that the same code
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.
5.4. Non-confidential Clients 5.4. Non-confidential Clients
skipping to change at page 14, line 31 skipping to change at page 15, line 26
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, and Justin Myrseth, Simon Moffatt, Brian Campbell, James Manger, and Justin
Richer. Richer.
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 ]]
-06
o Clarified usage of the "user_code" URI parameter optimization
following the IETF98 working group discussion.
-05 -05
o response_type parameter removed from authorization request. o response_type parameter removed from authorization request.
o Added option for clients to include the user_code on the o Added option for clients to include the user_code on the
verification URI. verification URI.
o Clarified token expiry, and other nits. o Clarified token expiry, and other nits.
-04 -04
o Security & Usability sections. OAuth Discovery Metadata. o Security & Usability sections. OAuth Discovery Metadata.
 End of changes. 16 change blocks. 
45 lines changed or deleted 91 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/