OAuth                                                         W. Denniss
Internet-Draft                                                    Google
Intended status: Standards Track                              S. Myrseth
Expires: September 4, 2016 January 9, 2017                                       ForgeRock
                                                              J. Bradley
                                                           Ping Identity
                                                                M. Jones
                                                           H. Tschofenig
                                                             ARM Limited
                                                           March 3,
                                                            July 8, 2016

                         OAuth 2.0 Device Flow


   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

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 September 4, 2016. January 9, 2017.

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  Device Authorization Request  . . . . . . . . . . . . . .   4
     3.2.  Client Requests Access Token  Device Authorization Response . . . . . . . . . . . . . .   6   5
     3.3.  Additional Error Responses  User Instruction  . . . . . . . . . . . . . . . . . . . .   6
     3.4.  Device Token Request  . . . . . . . . . . . . . . . . . .   6
     3.5.  Device Token Response . . . . . . . . . . . . . . . . . .   7
   4.  Security Considerations . . . . . . . . . . . . . . . . . . .   7   8
   5.  Normative References  . . . . . . . . . . . . . . . . . . . .   7   8
   Appendix A.  Acknowledgements . . . . . . . . . . . . . . . . . .   7   8
   Appendix B.  Document History . . . . . . . . . . . . . . . . . .   7   8
   Authors' Addresses  . . . . . . . . . . . . . . . . . . . . . . .   8   9

1.  Introduction

   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)--->
      |          |>---(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:

      (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

      (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

      (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",
   "OPTIONAL" in this document are to be interpreted as described in

   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, server, and is thus
      used to bind the device to the end-user.

3.  Specification

3.1.  Client Requests  Device Authorization Request

   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:


      REQUIRED.  The parameter value MUST be set to "device_code".


      REQUIRED.  The client identifier as described in Section 2.2 of


      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


3.2.  Device Authorization Response

   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:


      REQUIRED.  The verification code.


      REQUIRED.  The end-user verification code.


      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.


      OPTIONAL.  The duration in seconds of the verification code


      OPTIONAL.  The minimum amount of time in seconds that the client
      SHOULD wait between polling requests to the token endpoint.

   For example:

      HTTP/1.1 200 OK
      Content-Type: application/json
      Cache-Control: no-store



3.3.  User Instruction

   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 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

3.4.  Device Token

   Since Request

   As the client user is unable authorizing the request on secondary device which may
   not have a way to communicate to receive incoming requests from the
   authorization server, it original device, the client
   polls the authorization server repeatedly token endpoint until the end-user grants or denies the
   request, or the verification device code expires.

   The client makes the following request polls 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 parameter (if provided).

   The client MAY provide makes a user interface for the end-
   user request to manually inform it when authorization was granted.

   The client requests an access the token endpoint by making an 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 "POST"
   request entity-body:


      REQUIRED.  Value MUST be set to "device_code".

      REQUIRED.  The device verification code, "device_code" from the token endpoint
      Device Authorization Response, defined in Section 3.2.


      REQUIRED, if the client is not authenticating with the
      authorization server as described in Section 4.1.1 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


   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.

3.3.  Additional Error Responses

   The following error responses are

   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 those within the error codes defined in Section 5.2 of [RFC6749]: [RFC6749],
   the following error codes are specific for the device flow:


      The authorization request is still pending as the end-user hasn't
      yet visited the authorization server and entered their
      verification code.


      The client is polling too quickly and should back off at a
      reasonable rate.


      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


5.  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,

Appendix A.  Acknowledgements

   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.

Appendix B.  Document History

   [[ to be removed by the RFC Editor before publication as an RFC ]]


   o  Applied spelling and grammar corrections and added the Document
      History appendix.

   o  Initial working group draft based on draft-recordon-oauth-

Authors' Addresses

   William Denniss
   1600 Amphitheatre Pkwy
   Mountain View, CA  94043

   Phone: +1 650-253-0000
   Email: wdenniss@google.com
   URI:   http://google.com/

   Stein Myrseth
   Lysaker torg 2
   Lysaker  1366

   Email: stein.myrseth@forgerock.com

   John Bradley
   Ping Identity

   Email: ve7jtb@ve7jtb.com
   URI:   http://www.thread-safe.com/

   Michael B. Jones

   Email: mbj@microsoft.com
   URI:   http://self-issued.info/

   Hannes Tschofenig
   ARM Limited

   Email: Hannes.Tschofenig@gmx.net
   URI:   http://www.tschofenig.priv.at