OAuth 2.0 Device FlowGoogle1600 Amphitheatre PkwyMountain ViewCA94043USA+1 650-253-0000wdenniss@google.comhttp://google.com/ForgeRockLysaker torg 2Lysaker1366NORWAYstein.myrseth@forgerock.comPing Identityve7jtb@ve7jtb.comhttp://www.thread-safe.com/Microsoftmbj@microsoft.comhttp://self-issued.info/ARM LimitedAustriaHannes.Tschofenig@gmx.nethttp://www.tschofenig.priv.at
Security Area
OAuthOAuthSecurityAuthorizationIoTInternet of ThingsSmart Objects
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).
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 | | |
+----------+ +----------------+
]]>
The device flow illustrated in 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.(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.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 .
The authorization server's endpoint capable of issuing
verification codes, user codes, and verification URLs.
A short-lived token representing an authorization session.
A short-lived token which the device displays to the end user,
is entered by the end-user on the authorization server, and is
thus used to bind the device to the end-user.
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 .
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:
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
lifetime.
OPTIONAL. The minimum amount of time in seconds that the
client SHOULD wait between polling requests to the token
endpoint.
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:
REQUIRED. Value MUST be set to "device_code".
REQUIRED. The device verification code, "device_code" from the
Device Authorization Response, defined in Section 3.2.
REQUIRED, if the client is not authenticating with the
authorization server as described in Section 3.2.1. of
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
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 .
If the user has approved the grant, the token endpoint responds with
a success response defined in Section 5.1 of
otherwise, it responds with an error, as defined in Section 5.2 of .
In addition to the error codes defined in Section 5.2 of
, 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.
TBD
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
Applied spelling and grammar corrections and added the Document History appendix.
-00
Initial working group draft based on draft-recordon-oauth-v2-device.