| OAuth | W. Denniss |
| Internet-Draft | |
| Intended status: Standards Track | S. Myrseth |
| Expires: January 9, 2017 | ForgeRock |
| J. Bradley | |
| Ping Identity | |
| M. Jones | |
| Microsoft | |
| H. Tschofenig | |
| ARM Limited | |
| July 8, 2016 |
OAuth 2.0 Device Flow
draft-ietf-oauth-device-flow-02
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 consoles, TVs, picture frames, and media hubs), but where the end-user has separate access to a user-agent on another computer or device (e.g., desktop computer, a laptop, a smart phone, or a tablet).
This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet-Drafts is at http://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress."
This Internet-Draft will expire on January 9, 2017.
Copyright (c) 2016 IETF Trust and the persons identified as the document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License.
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 of receiving incoming requests from the authorization server (incapable of acting as an HTTP server).
Instead of interacting with the end-user's user-agent, the client instructs the end-user to use another computer or device and connect to the authorization server to approve the access request. Since the client cannot receive incoming requests, it polls the authorization server repeatedly until the end-user completes the approval process.
Note that this device flow does not utilize the client secret.
+----------+ +----------------+
| |>---(A)-- Client Identifier --->| |
| | | |
| |<---(B)-- Verification Code, --<| |
| | User Code, | |
| | & Verification URI | |
| Device | | |
| Client | Client Identifier & | |
| |>---(E)-- Verification Code --->| |
| | polling... | |
| |>---(E)-- Verification Code --->| |
| | | Authorization |
| |<---(F)-- Access Token --------<| Server |
+----------+ (w/ Optional Refresh Token) | |
v | |
: | |
(C) User Code & Verification URI | |
: | |
v | |
+----------+ | |
| End-user | | |
| at |<---(D)-- User authenticates -->| |
| Browser | | |
+----------+ +----------------+
Figure 1: Device Flow.
The device flow illustrated in Figure 1 includes the following steps:
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].
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 endpoint. The client constructs a request URI by adding the following parameters to the request:
POST /token HTTP/1.1 Host: server.example.com Content-Type: application/x-www-form-urlencoded response_type=device_code&client_id=s6BhdRkqt3
For example, the client makes the following HTTPS request (line breaks are for display purposes only):
In response, the authorization server generates a verification code 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 response contains the following parameters:
HTTP/1.1 200 OK
Content-Type: application/json
Cache-Control: no-store
{
"device_code":"74tq5miHKB",
"user_code":"94248",
"verification_uri":"http://www.example.com/device",
"interval"=5
}
For example:
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 authenticates with the authorization server. The authorization 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 approves or denies the request, the authorization server informs the end-user to return to the device for further instructions.
As the user is authorizing the request on secondary device which may not have a way to communicate to the original device, the client polls the token endpoint until the end-user grants or denies the request, or the device code expires.
The client polls at reasonable interval which MUST NOT exceed the minimum interval provided by the authorization server via the "interval" parameter (if provided).
The client makes a request to the token endpoint by sending the following parameters using the "application/x-www-form-urlencoded" format per Appendix B with a character encoding of UTF-8 in the HTTP request entity-body:
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
For example, the client makes the following HTTPS request (line breaks are for display purposes only):
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].
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:
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.
TBD
| [RFC2119] | Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997. |
| [RFC6749] | Hardt, D., "The OAuth 2.0 Authorization Framework", RFC 6749, DOI 10.17487/RFC6749, October 2012. |
The -00 version of this document was based on draft-recordon-oauth-v2-device edited by David Recordon and Brent Goldman. The content of that document was initially part of the OAuth 2.0 protocol specification but was later removed due to the lack of sufficient deployment expertise at that time. We would therefore also like to thank the OAuth working group for their work on the initial content of this specification through 2010.
[[ to be removed by the RFC Editor before publication as an RFC ]]
-01
-00