OAuth 2.0 Device Authorization Grant
Extracted elements (27)
The device authorization grant requires only a one-way communication channel (device to authorization server) to maximize viability in restricted environments such as TV applications capable of only outbound requests. A return channel from the authorizing device to the OAuth client device, if it exists, may be used as an alternative to polling but is outside the scope of this specification.
User codes are recommended to use a case-insensitive A-Z character set (avoiding vowels and ambiguous characters like '0'/'O', '1'/'l'/'I') with dashes for readability, to optimize for mobile input speed and reduce entry errors. An example base-20 charset ('BCDFGHJKLMNPQRSTVWXZ') with 8 characters yields approximately 34.5 bits of entropy.
The device authorization grant is not intended to replace browser-based OAuth in native apps on capable devices; those apps should follow RFC 8252 (OAuth 2.0 for Native Apps). The device flow targets devices that lack a suitable browser or have constrained input capabilities.
All requests from the device MUST use TLS (RFC 8446) and implement the best practices of BCP 195 (RFC 7525).
Authorization servers supporting this specification MUST implement a user-interaction sequence starting with the user navigating to 'verification_uri' and supplying the 'user_code' at some stage during the interaction.
If no polling interval is provided in the device authorization response, clients MUST use 5 seconds as the default polling interval.
If the client was issued client credentials, it MUST authenticate with the authorization server when making the device access token request.
It is NOT RECOMMENDED for authorization servers to include the user code in the verification URI ('verification_uri'), as this increases the length and complexity of the URI the user must type.
On encountering a connection timeout, clients MUST unilaterally reduce their polling frequency before retrying. Use of exponential backoff (e.g., doubling the interval on each timeout) is RECOMMENDED.
On receiving 'slow_down', the client MUST increase its polling interval by 5 seconds for that request and all subsequent requests.
Parameters sent without a value MUST be treated as omitted; the authorization server MUST ignore unrecognized request parameters; request and response parameters MUST NOT be included more than once.
The client SHOULD only commence a device authorization request when prompted by the user and not automatically (e.g., on app start or session expiry) to avoid overloading the token endpoint due to the polling nature of the protocol.
When 'verification_uri_complete' is present, clients MUST still display the 'user_code', as the authorization server will require the user to confirm it to disambiguate devices or as remote phishing mitigation.
The device access token request is a POST to the token endpoint with grant_type set to 'urn:ietf:params:oauth:grant-type:device_code', plus 'device_code' (REQUIRED) and 'client_id' (REQUIRED if not authenticating). The client polls this endpoint repeatedly until the user approves or an error occurs.
The 'device_authorization_endpoint' discovery metadata key is registered in the OAuth Authorization Server Metadata registry (RFC 8414) to advertise the URL of the device authorization endpoint.
The device authorization flow uses a new OAuth endpoint — the device authorization endpoint — separate from the standard authorization endpoint. The device client POSTs to this endpoint to obtain a device code, user code, and verification URI, then displays the user code and URI to the user while polling the token endpoint.
The device authorization request is an HTTP POST to the device authorization endpoint using 'application/x-www-form-urlencoded' encoding. Required parameter is 'client_id' (when not authenticating); optional parameter is 'scope'.
The device authorization response is a JSON object (HTTP 200) containing: 'device_code' (REQUIRED), 'user_code' (REQUIRED), 'verification_uri' (REQUIRED, short and memorable), 'verification_uri_complete' (OPTIONAL, includes user_code for non-textual transmission), 'expires_in' (REQUIRED, lifetime in seconds), and 'interval' (OPTIONAL, minimum polling interval in seconds).
This document registers 'device_code' in the IANA OAuth Parameters registry (token request location), the grant type URN 'urn:ietf:params:oauth:grant-type:device_code' in the OAuth URI registry, error codes 'authorization_pending', 'access_denied', 'slow_down', and 'expired_token' in the OAuth Extensions Error Registry, and 'device_authorization_endpoint' in the OAuth Authorization Server Metadata registry.
Device clients are generally incapable of maintaining credential confidentiality (credentials can be extracted via reverse-engineering), so they should be treated as public clients susceptible to impersonation, per the security considerations of RFC 6819 and RFC 8252.
Device codes are not displayed to users and have no usability length constraints, so a very high entropy code SHOULD be used to prevent an attacker who guesses the device code from obtaining the authorization code.
Device trustworthiness is a concern because the device requesting authorization is not the same as the device from which the user grants access; signals from the approving session are not always relevant. A malicious authorization server could also perform a man-in-the-middle attack on the backchannel flow.
Remote phishing is possible: an attacker can initiate the device flow on a device they control and trick a victim into entering the user code. It is RECOMMENDED to inform the user they are authorizing a device and to confirm device possession; the authorization server SHOULD display device information so users can detect impersonation.
Session spying is a risk: a malicious user could observe the displayed user code and complete the authorization before the legitimate user. Devices SHOULD take into account the operating environment when communicating the code to reduce the chance of observation.
User codes have lower entropy than device codes due to usability constraints, making them susceptible to brute force. The server SHOULD rate-limit user code attempts; the user code SHOULD have enough entropy that, combined with rate-limiting and the code's finite lifetime, a brute-force attack becomes infeasible.
When user codes are transmitted non-visually (e.g., text-to-speech, Bluetooth LE), it is RECOMMENDED that the chosen communication channel only be accessible by people in close proximity to prevent credential bootstrapping attacks by remote malicious users.
The device polling state machine has the following outcomes at the token endpoint: success (access token issued), 'authorization_pending' (continue polling, respecting interval), 'slow_down' (increase interval by 5 seconds and continue polling), 'access_denied' (stop, user denied), 'expired_token' (stop, device_code expired). On any other error, the client MUST stop polling.