OAuth W. Denniss Internet-Draft Google Intended status: Standards Track S. Myrseth Expires: August 20, 2016 Forgerock J. Bradley Ping Identity M. Jones Microsoft H. Tschofenig ARM Limited February 17, 2016 OAuth 2.0 Device Flow draft-ietf-oauth-device-flow-00 Abstract The device flow is suitable for OAuth 2.0 clients executing on devices which 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). Note: This version of the document is a continuation of an earlier, long expired draft. The content of the expired draft has been copied almost unmodified. The goal of the work on this document is to capture deployment experience. Status of This Memo 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 August 20, 2016. Denniss, et al. Expires August 20, 2016 [Page 1] Internet-Draft OAuth 2.0 Device Flow February 2016 Copyright Notice 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. Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 4 3. Specification . . . . . . . . . . . . . . . . . . . . . . . . 4 3.1. Client Requests Authorization . . . . . . . . . . . . . . 4 3.2. Client Requests Access Token . . . . . . . . . . . . . . 6 3.3. Additional Error Responses . . . . . . . . . . . . . . . 6 4. Contributors . . . . . . . . . . . . . . . . . . . . . . . . 7 5. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 7 6. Security Considerations . . . . . . . . . . . . . . . . . . . 7 7. Normative References . . . . . . . . . . . . . . . . . . . . 7 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 7 1. Introduction The device flow is suitable for clients executing on devices which 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. Denniss, et al. Expires August 20, 2016 [Page 2] Internet-Draft OAuth 2.0 Device Flow February 2016 +----------+ +----------------+ | |>---(A)-- Client Identifier --->| | | | | | | |<---(B)-- Verification Code, --<| | | | User Code, | | | | & Verification URI | | | Device | | | | Client | Client Identifier & | | | |>---(E)-- Verification Code --->| | | | ... | | | |>---(E)---> | | | | | 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: (A) The client requests access from the authorization server and includes its client identifier in the request. (B) The authorization server issues a verification code, an end- user code, and provides the end-user verification URI. (C) The client instructs the end-user to use its user-agent (elsewhere) and visit the provided end-user verification URI. The client provides the end-user with the end-user code to enter in order to grant access. (D) The authorization server authenticates the end-user (via the user-agent) and prompts the end-user to grant the client's access request. If the end-user agrees to the client's access request, the end-user enters the end-user code provided by the client. The authorization server validates the end-user code provided by the end-user. Denniss, et al. Expires August 20, 2016 [Page 3] Internet-Draft OAuth 2.0 Device Flow February 2016 (E) While the end-user authorizes (or denies) the client's request (D), the client repeatedly polls the authorization server to find out if the end-user completed the end-user authorization step. The client includes the verification code and its client identifier. (F) Assuming the end-user granted access, the authorization server validates the verification code provided by the client and responds back with the access token. 2. Terminology 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]. Device Endpoint: The authorization server's endpoint capable of issuing verification codes, user codes, and verification URLs. Device Verification Code: A short-lived token representing an authorization session. End-User Verification Code: 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 used to bind the device to the end-user. 3. Specification 3.1. Client Requests Authorization 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: response_type: REQUIRED. The parameter value MUST be set to "device_code". client_id: Denniss, et al. Expires August 20, 2016 [Page 4] Internet-Draft OAuth 2.0 Device Flow February 2016 REQUIRED. The client identifier as described in Section 2.2 of [RFC6749]. scope: OPTIONAL. The scope of the access request as described by Section 3.3 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 response_type=device_code&client_id=s6BhdRkqt3 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: device_code REQUIRED. The verification code. user_code REQUIRED. The end-user verification code. verification_uri REQUIRED. The end-user verification URI on the authorization server. The URI should be short and easy to remember as end- users will be asked to manually type it into their user-agent. expires_in OPTIONAL. The duration in seconds of the verification code lifetime. interval OPTIONAL. The minimum amount of time in seconds that the client SHOULD wait between polling requests to the token endpoint. For example: Denniss, et al. Expires August 20, 2016 [Page 5] Internet-Draft OAuth 2.0 Device Flow February 2016 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 } 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. 3.2. Client Requests Access Token Since the client is unable to receive incoming requests from the authorization server, it polls the authorization server repeatedly until the end-user grants or denies the request, or the verification code expires. The client makes the following request at an arbitrary but reasonable interval which MUST NOT exceed the minimum interval rate provided by the authorization server (if present via the "interval" parameter). 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 to the token endpoint as described in Section 4.1.1 of [RFC6749] . The "redirect_uri" parameter is NOT REQUIRED as part of this request. 3.3. Additional Error Responses The following error responses are defined in addition to those within Section 4.2.2.1. of [RFC6749]: authorization_pending Denniss, et al. Expires August 20, 2016 [Page 6] Internet-Draft OAuth 2.0 Device Flow February 2016 The authorization request is still pending as the end-user hasn't yet visited the authorization server and entered their verification code. slow_down The client is polling too quickly and should back off at a reasonable rate. 4. Contributors The -00 version of this document is based on a previous edited by David Recordon and Brent Goldman. The content of that document was initially part of the OAuth 2.0 protocol specificaiton 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 this document around 2010. 5. Acknowledgements Add your name here. 6. Security Considerations TBD 7. Normative References [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., Ed., "The OAuth 2.0 Authorization Framework", RFC 6749, DOI 10.17487/RFC6749, October 2012, . Authors' Addresses William Denniss Google 1600 Amphitheatre Pkwy Mountain View, CA 94043 USA Phone: +1 650-253-0000 Email: wdenniss@google.com URI: http://google.com/ Denniss, et al. Expires August 20, 2016 [Page 7] Internet-Draft OAuth 2.0 Device Flow February 2016 Stein Myrseth Forgerock Lysaker torg 2 Lysaker 1366 NORWAY Email: stein.myrseth@forgerock.com John Bradley Ping Identity Email: ve7jtb@ve7jtb.com URI: http://www.thread-safe.com/ Michael B. Jones Microsoft Email: mbj@microsoft.com URI: http://self-issued.info/ Hannes Tschofenig ARM Limited Austria Email: Hannes.Tschofenig@gmx.net URI: http://www.tschofenig.priv.at Denniss, et al. Expires August 20, 2016 [Page 8]