draft-ietf-oauth-device-flow-01.txt   draft-ietf-oauth-device-flow-02.txt 
OAuth W. Denniss OAuth W. Denniss
Internet-Draft Google Internet-Draft Google
Intended status: Standards Track S. Myrseth Intended status: Standards Track S. Myrseth
Expires: September 4, 2016 ForgeRock Expires: January 9, 2017 ForgeRock
J. Bradley J. Bradley
Ping Identity Ping Identity
M. Jones M. Jones
Microsoft Microsoft
H. Tschofenig H. Tschofenig
ARM Limited ARM Limited
March 3, 2016 July 8, 2016
OAuth 2.0 Device Flow OAuth 2.0 Device Flow
draft-ietf-oauth-device-flow-01 draft-ietf-oauth-device-flow-02
Abstract Abstract
The device flow is suitable for OAuth 2.0 clients executing on The device flow is suitable for OAuth 2.0 clients executing on
devices that do not have an easy data-entry method (e.g., game devices that do not have an easy data-entry method (e.g., game
consoles, TVs, picture frames, and media hubs), but where the end- consoles, TVs, picture frames, and media hubs), but where the end-
user has separate access to a user-agent on another computer or user has separate access to a user-agent on another computer or
device (e.g., desktop computer, a laptop, a smart phone, or a device (e.g., desktop computer, a laptop, a smart phone, or a
tablet). tablet).
skipping to change at page 1, line 42 skipping to change at page 1, line 42
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 4, 2016. This Internet-Draft will expire on January 9, 2017.
Copyright Notice Copyright Notice
Copyright (c) 2016 IETF Trust and the persons identified as the Copyright (c) 2016 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 20 skipping to change at page 2, line 20
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
described in the Simplified BSD License. described in the Simplified BSD License.
Table of Contents Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2
2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 4 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 4
3. Specification . . . . . . . . . . . . . . . . . . . . . . . . 4 3. Specification . . . . . . . . . . . . . . . . . . . . . . . . 4
3.1. Client Requests Authorization . . . . . . . . . . . . . . 4 3.1. Device Authorization Request . . . . . . . . . . . . . . 4
3.2. Client Requests Access Token . . . . . . . . . . . . . . 6 3.2. Device Authorization Response . . . . . . . . . . . . . . 5
3.3. Additional Error Responses . . . . . . . . . . . . . . . 6 3.3. User Instruction . . . . . . . . . . . . . . . . . . . . 6
4. Security Considerations . . . . . . . . . . . . . . . . . . . 7 3.4. Device Token Request . . . . . . . . . . . . . . . . . . 6
5. Normative References . . . . . . . . . . . . . . . . . . . . 7 3.5. Device Token Response . . . . . . . . . . . . . . . . . . 7
Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 7 4. Security Considerations . . . . . . . . . . . . . . . . . . . 8
Appendix B. Document History . . . . . . . . . . . . . . . . . . 7 5. Normative References . . . . . . . . . . . . . . . . . . . . 8
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 8 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 8
Appendix B. Document History . . . . . . . . . . . . . . . . . . 8
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 9
1. Introduction 1. Introduction
The device flow is suitable for clients executing on devices that do The device flow is suitable for clients executing on devices that do
not have an easy data-entry method and where the client is incapable not have an easy data-entry method and where the client is incapable
of receiving incoming requests from the authorization server of receiving incoming requests from the authorization server
(incapable of acting as an HTTP server). (incapable of acting as an HTTP server).
Instead of interacting with the end-user's user-agent, the client Instead of interacting with the end-user's user-agent, the client
instructs the end-user to use another computer or device and connect instructs the end-user to use another computer or device and connect
skipping to change at page 3, line 14 skipping to change at page 3, line 14
+----------+ +----------------+ +----------+ +----------------+
| |>---(A)-- Client Identifier --->| | | |>---(A)-- Client Identifier --->| |
| | | | | | | |
| |<---(B)-- Verification Code, --<| | | |<---(B)-- Verification Code, --<| |
| | User Code, | | | | User Code, | |
| | & Verification URI | | | | & Verification URI | |
| Device | | | | Device | | |
| Client | Client Identifier & | | | Client | Client Identifier & | |
| |>---(E)-- Verification Code --->| | | |>---(E)-- Verification Code --->| |
| | ... | | | | polling... | |
| |>---(E)---> | | | |>---(E)-- Verification Code --->| |
| | | Authorization | | | | Authorization |
| |<---(F)-- Access Token --------<| Server | | |<---(F)-- Access Token --------<| Server |
+----------+ (w/ Optional Refresh Token) | | +----------+ (w/ Optional Refresh Token) | |
v | | v | |
: | | : | |
(C) User Code & Verification URI | | (C) User Code & Verification URI | |
: | | : | |
v | | v | |
+----------+ | | +----------+ | |
| End-user | | | | End-user | | |
skipping to change at page 4, line 34 skipping to change at page 4, line 34
The authorization server's endpoint capable of issuing The authorization server's endpoint capable of issuing
verification codes, user codes, and verification URLs. verification codes, user codes, and verification URLs.
Device Verification Code: Device Verification Code:
A short-lived token representing an authorization session. A short-lived token representing an authorization session.
End-User Verification Code: End-User Verification Code:
A short-lived token which the device displays to the end user, is A short-lived token which the device displays to the end user, is
entered by the end-user on the authorization sever, and is thus entered by the end-user on the authorization server, and is thus
used to bind the device to the end-user. used to bind the device to the end-user.
3. Specification 3. Specification
3.1. Client Requests Authorization 3.1. Device Authorization Request
The client initiates the flow by requesting a set of verification The client initiates the flow by requesting a set of verification
codes from the authorization server by making an HTTP "POST" request codes from the authorization server by making an HTTP "POST" request
to the device endpoint. The client constructs a request URI by to the device endpoint. The client constructs a request URI by
adding the following parameters to the request: adding the following parameters to the request:
response_type: response_type:
REQUIRED. The parameter value MUST be set to "device_code". REQUIRED. The parameter value MUST be set to "device_code".
skipping to change at page 5, line 22 skipping to change at page 5, line 22
For example, the client makes the following HTTPS request (line For example, the client makes the following HTTPS request (line
breaks are for display purposes only): breaks are for display purposes only):
POST /token HTTP/1.1 POST /token HTTP/1.1
Host: server.example.com Host: server.example.com
Content-Type: application/x-www-form-urlencoded Content-Type: application/x-www-form-urlencoded
response_type=device_code&client_id=s6BhdRkqt3 response_type=device_code&client_id=s6BhdRkqt3
3.2. Device Authorization Response
In response, the authorization server generates a verification code In response, the authorization server generates a verification code
and an end-user code and includes them in the HTTP response body and an end-user code and includes them in the HTTP response body
using the "application/json" format with a 200 status code (OK). The using the "application/json" format with a 200 status code (OK). The
response contains the following parameters: response contains the following parameters:
device_code device_code
REQUIRED. The verification code. REQUIRED. The verification code.
user_code user_code
skipping to change at page 6, line 16 skipping to change at page 6, line 18
Content-Type: application/json Content-Type: application/json
Cache-Control: no-store Cache-Control: no-store
{ {
"device_code":"74tq5miHKB", "device_code":"74tq5miHKB",
"user_code":"94248", "user_code":"94248",
"verification_uri":"http://www.example.com/device", "verification_uri":"http://www.example.com/device",
"interval"=5 "interval"=5
} }
The client displays the end-user code and the end-user verification 3.3. User Instruction
URI to the end-user, and instructs the end-user to visit the URI
using a user-agent and enter the end-user code. After receiving a successful Authorization Response, the client
displays the end-user code and the end-user verification URI to the
end-user, and instructs the end-user to visit the URI using a user-
agent and enter the end-user code.
The end-user manually types the provided verification URI and The end-user manually types the provided verification URI and
authenticates with the authorization server. The authorization authenticates with the authorization server. The authorization
server prompts the end-user to authorize the client's request by server prompts the end-user to authorize the client's request by
entering the end-user code provided by the client. Once the end-user entering the end-user code provided by the client. Once the end-user
approves or denies the request, the authorization server informs the approves or denies the request, the authorization server informs the
end-user to return to the device for further instructions. end-user to return to the device for further instructions.
3.2. Client Requests Access Token 3.4. Device Token Request
Since the client is unable to receive incoming requests from the As the user is authorizing the request on secondary device which may
authorization server, it polls the authorization server repeatedly not have a way to communicate to the original device, the client
until the end-user grants or denies the request, or the verification polls the token endpoint until the end-user grants or denies the
code expires. request, or the device code expires.
The client makes the following request at an arbitrary but reasonable The client polls at reasonable interval which MUST NOT exceed the
interval which MUST NOT exceed the minimum interval rate provided by minimum interval provided by the authorization server via the
the authorization server (if present via the "interval" parameter). "interval" parameter (if provided).
Alternatively, the client MAY provide a user interface for the end-
user to manually inform it when authorization was granted.
The client requests an access token by making an HTTP "POST" request The client makes a request to the token endpoint by sending the
to the token endpoint as described in Section 4.1.1 of [RFC6749] . following parameters using the "application/x-www-form-urlencoded"
The "redirect_uri" parameter is NOT REQUIRED as part of this request. format per Appendix B with a character encoding of UTF-8 in the HTTP
request entity-body:
3.3. Additional Error Responses grant_type
The following error responses are defined in addition to those within REQUIRED. Value MUST be set to "device_code".
Section 4.2.2.1. of [RFC6749]:
device_code
REQUIRED. The device verification code, "device_code" from the
Device Authorization Response, defined in Section 3.2.
client_id
REQUIRED, if the client is not authenticating with the
authorization server as described in Section 3.2.1. of [RFC6749]
For example, the client makes the following HTTPS request (line
breaks are for display purposes only):
POST /token HTTP/1.1
Host: server.example.com
Content-Type: application/x-www-form-urlencoded
grant_type=device_code&device_code=pxDoJ3Bt9WVMTXfDATLkxJ9u
&client_id=459691054427
Note that unlike the Access Token Request for the authorization_code
grant type defined in Section 4.1.3 of [RFC6749] the "redirect_uri"
parameter is NOT REQUIRED as part of this request.
If the client was issued client credentials (or assigned other
authentication requirements), the client MUST authenticate with the
authorization server as described in Section 3.2.1 of [RFC6749].
3.5. Device Token Response
If the user has approved the grant, the token endpoint responds with
a success response defined in Section 5.1 of [RFC6749] otherwise, it
responds with an error, as defined in Section 5.2 of [RFC6749].
In addition to the error codes defined in Section 5.2 of [RFC6749],
the following error codes are specific for the device flow:
authorization_pending authorization_pending
The authorization request is still pending as the end-user hasn't The authorization request is still pending as the end-user hasn't
yet visited the authorization server and entered their yet visited the authorization server and entered their
verification code. verification code.
slow_down slow_down
The client is polling too quickly and should back off at a The client is polling too quickly and should back off at a
reasonable rate. reasonable rate.
expired_token
The device_code has expired. The client will need to make a new
Device Authorization Request.
The error code "authorization_pending" and "slow_down" are considered
soft errors. The the client should continue to poll when receiving
"authorization_pending" errors, reducing the interval if a
"slow_down" error is received. Other error codes are considered hard
errors, the client should stop polling and react accordingly, for
example, by displaying an error to the user.
4. Security Considerations 4. Security Considerations
TBD TBD
5. Normative References 5. Normative References
[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,
<http://www.rfc-editor.org/info/rfc2119>. <http://www.rfc-editor.org/info/rfc2119>.
 End of changes. 18 change blocks. 
35 lines changed or deleted 89 lines changed or added

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