RFC 8628

OAuth 2.0 Device Authorization Grant

📅 published August 2019, from ietf

RFC 8628 🎀 OAuth 2.0 Device Authorization Grant

Okay bestie, this one is an IETF Standards Track document from August 2019 💖. The authors are W. Denniss from Google, J. Bradley from Ping Identity, M. Jones from Microsoft, and H. Tschofenig from ARM Limited 🌸. It's published under ISSN 2070-1721. Its header doesn't list anything it obsoletes or updates, so it stands on its own, no cap 💅.

Abstract ✨

So this grant is for internet-connected devices that either have no browser for user-agent-based authorization, or have such tiny input that typing text to log in during the flow is just impractical 💀. It lets OAuth clients on things like smart TVs, media consoles, digital picture frames, and printers get user authorization to reach protected resources, by using a user agent on a separate device 🦋.

Status of This Memo 📜

This is an Internet Standards Track document.

This document is a product of the Internet Engineering Task Force (IETF). It represents the consensus of the IETF community. It has received public review and has been approved for publication by the Internet Engineering Steering Group (IESG). Further information on Internet Standards is available in Section 2 of RFC 7841.

Info about the current status of this doc, any errata, and how to send feedback lives at https://www.rfc-editor.org/info/rfc8628 🔗.

Copyright (c) 2019 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 (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, because 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 they are provided without warranty as described in the Simplified BSD License 🫶.

Table of Contents 🌸

1.  Introduction  . . . . . . . . . . . . . . . . . . . . . . . .   3
2.  Terminology . . . . . . . . . . . . . . . . . . . . . . . . .   5
3.  Protocol  . . . . . . . . . . . . . . . . . . . . . . . . . .   5
  3.1.  Device Authorization Request  . . . . . . . . . . . . . .   5
  3.2.  Device Authorization Response . . . . . . . . . . . . . .   7
  3.3.  User Interaction  . . . . . . . . . . . . . . . . . . . .   8
    3.3.1.  Non-Textual Verification URI Optimization . . . . . .   9
  3.4.  Device Access Token Request . . . . . . . . . . . . . . .  10
  3.5.  Device Access Token Response  . . . . . . . . . . . . . .  11
4.  Discovery Metadata  . . . . . . . . . . . . . . . . . . . . .  12
5.  Security Considerations . . . . . . . . . . . . . . . . . . .  12
  5.1.  User Code Brute Forcing . . . . . . . . . . . . . . . . .  12
  5.2.  Device Code Brute Forcing . . . . . . . . . . . . . . . .  13
  5.3.  Device Trustworthiness  . . . . . . . . . . . . . . . . .  13
  5.4.  Remote Phishing . . . . . . . . . . . . . . . . . . . . .  14
  5.5.  Session Spying  . . . . . . . . . . . . . . . . . . . . .  15
  5.6.  Non-Confidential Clients  . . . . . . . . . . . . . . . .  15
  5.7.  Non-Visual Code Transmission  . . . . . . . . . . . . . .  15
6.  Usability Considerations  . . . . . . . . . . . . . . . . . .  16
  6.1.  User Code Recommendations . . . . . . . . . . . . . . . .  16
  6.2.  Non-Browser User Interaction  . . . . . . . . . . . . . .  17
7.  IANA Considerations . . . . . . . . . . . . . . . . . . . . .  17
  7.1.  OAuth Parameter Registration  . . . . . . . . . . . . . .  17
  7.2.  OAuth URI Registration  . . . . . . . . . . . . . . . . .  17
  7.3.  OAuth Extensions Error Registration . . . . . . . . . . .  18
  7.4.  OAuth Authorization Server Metadata . . . . . . . . . . .  18
8.  Normative References  . . . . . . . . . . . . . . . . . . . .  19
Acknowledgements  . . . . . . . . . . . . . . . . . . . . . . . .  20
Authors' Addresses  . . . . . . . . . . . . . . . . . . . . . . .  21

1. Introduction ✨

This is an OAuth 2.0 [RFC6749] protocol extension that lets OAuth clients ask for user authorization from apps on devices with limited input or no suitable browser 🧚. Think smart TVs, media consoles, picture frames, and printers, which don't have an easy way to type or a proper browser for regular OAuth 😭. The flow in this spec, sometimes called the "device flow," tells the user to review the request on a secondary device, like a smartphone, because that one has the input and browser stuff needed to finish the job 📱.

The device authorization grant is not meant to replace browser-based OAuth in native apps on capable devices like smartphones 🙈. Those apps should follow the practices in "OAuth 2.0 for Native Apps" [RFC8252].

The operating requirements for this grant type are:

(1) The device is already connected to the Internet.

(2) The device is able to make outbound HTTPS requests.

(3) The device is able to display or otherwise communicate a URI and code sequence to the user.

(4) The user has a secondary device (e.g., personal computer or smartphone) from which they can process the request.

Here's the lowkey genius part 🦋. The device authorization grant doesn't need two-way communication between the OAuth client on the device and the user agent. Other OAuth 2 grant types, like the authorization code and implicit grants, do need that. Because of this, it covers several use cases that those other approaches just can't handle 🌈.

Instead of talking to the end user's user agent (aka the browser) directly, the device client tells the end user to grab another computer or device and connect to the authorization server to approve the access request 💜. Since the protocol supports clients that can't receive incoming requests, the clients keep polling the authorization server over and over until the end user finishes approving ⏳.

The device client usually picks which authorization servers to support. That could be its own server or the servers of providers it has relationships with 👑. It's super common for a device client to support just one authorization server, like a TV app for one specific media provider that only uses that provider's server 📺. The user might not have an existing relationship with that authorization provider yet, though one can possibly be set up during the authorization flow 🎀.

      +----------+                                +----------------+
      |          |>---(A)-- Client Identifier --->|                |
      |          |                                |                |
      |          |<---(B)-- Device Code,      ---<|                |
      |          |          User Code,            |                |
      |  Device  |          & Verification URI    |                |
      |  Client  |                                |                |
      |          |  [polling]                     |                |
      |          |>---(E)-- Device Code       --->|                |
      |          |          & Client Identifier   |                |
      |          |                                |  Authorization |
      |          |<---(F)-- Access Token      ---<|     Server     |
      +----------+   (& Optional Refresh Token)   |                |
            v                                     |                |
            :                                     |                |
           (C) User Code & Verification URI       |                |
            :                                     |                |
            v                                     |                |
      +----------+                                |                |
      | End User |                                |                |
      |    at    |<---(D)-- End user reviews  --->|                |
      |  Browser |          authorization request |                |
      +----------+                                +----------------+

Figure 1: Device Authorization Flow

Here's how the device authorization flow in Figure 1 goes, step by step 🪄:

(A) The client requests access from the authorization server and includes its client identifier in the request.

(B) The authorization server issues a device code and an end-user code, and provides the end-user verification URI.

(C) The client tells the end user to use a user agent on another device and visit the provided end-user verification URI. The client gives the user the end-user code to enter so they can review the authorization request 💅.

(D) The authorization server authenticates the end user (via the user agent) and prompts them to input the user code the device client gave them. The authorization server checks the user code the user typed in, and then prompts them to accept or decline the request 🙌.

(E) While the end user reviews the client's request (step D), the client keeps polling the authorization server to find out whether the user finished the authorization step. The client includes the device code and its client identifier 🔁.

(F) The authorization server validates the device code the client sent and responds with the access token if the client is granted access, an error if access is denied, or an indication that the client should keep polling 🌟.

2. Terminology 📖

Quick vocab check 🧚. 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 BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here. So when you see them in ALL CAPS, they're serious business, periodt 💅. Lowercase is just vibes 🙈.

3. Protocol 🧚

(Part 1 of 4 ends here, bestie. The protocol details pick up in part 2 💖🦋)

3.1. Device Authorization Request 🎀

Okay so bestie, this section introduces a brand new OAuth endpoint: the device authorization endpoint 🦋. It's totally separate from the regular OAuth authorization endpoint from [RFC6749], the one the user talks to through a browser. Here's the vibe difference: with the device endpoint, the OAuth client on the device talks straight to the authorization server without any browser popup, and then the actual end user approves the request on a different device. Iconic, right? 💅

So the client kicks things off by making an HTTP "POST" request to the device authorization endpoint, asking for a set of verification codes ✨.

The client builds its device authorization request by including these parameters in the "application/x-www-form-urlencoded" format (see Appendix B of [RFC6749]), with a character encoding of UTF-8 in the HTTP request entity-body 🌸:

client_id REQUIRED if the client is not authenticating with the authorization server as described in Section 3.2.1. of [RFC6749]. The client identifier as described in Section 2.2 of [RFC6749].

scope OPTIONAL. The scope of the access request as defined by Section 3.3 of [RFC6749].

Here's an example of the HTTPS request the client makes 🍓:

POST /device_authorization HTTP/1.1
Host: server.example.com
Content-Type: application/x-www-form-urlencoded

client_id=1406020730&scope=example_scope

All requests from the device MUST use the Transport Layer Security (TLS) protocol [RFC8446] and implement the best practices of BCP 195 [RFC7525] 🔥. No exceptions, periodt.

Parameters sent without a value MUST be treated as if they were omitted from the request 🙈. The authorization server MUST ignore unrecognized request parameters. And request and response parameters MUST NOT be included more than once. Non-negotiable, bestie 💜.

The client authentication requirements of Section 3.2.1 of [RFC6749] apply to requests on this endpoint too. So confidential clients (the ones that have established client credentials) authenticate the same way they would when hitting the token endpoint, and public clients just send the "client_id" parameter to identify themselves 🫶.

Now, the polling thing (more on that in Section 3.4) means the client can accidentally overload the token endpoint if it's not careful 😭. So the client SHOULD only start a device authorization request when the user prompts it, and NOT automatically, like when the app starts up or when the previous authorization session expires or fails. Main character energy is not spamming the server 👑.

3.2. Device Authorization Response ✨

Next up, the server responds. It generates a unique device verification code and an end-user code, both valid for a limited time 🧚. It sends them back in the HTTP response body using the "application/json" format [RFC8259] with a 200 (OK) status code. The response includes these parameters:

device_code REQUIRED. The device 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, because end users will be asked to manually type it into their user agent 💖.

verification_uri_complete OPTIONAL. A verification URI that includes the "user_code" (or other information with the same function as the "user_code"), which is designed for non-textual transmission 🦋.

expires_in REQUIRED. The lifetime in seconds of the "device_code" and "user_code".

interval OPTIONAL. The minimum amount of time in seconds that the client SHOULD wait between polling requests to the token endpoint. If no value is provided, clients MUST use 5 as the default ⭐.

Here's an example response 🌈:

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

{
  "device_code": "GmRhmhcxhwAzkoEqiMEg_DnyEysNkuNhszIySk9eS",
  "user_code": "WDJB-MJHT",
  "verification_uri": "https://example.com/device",
  "verification_uri_complete":
      "https://example.com/device?user_code=WDJB-MJHT",
  "expires_in": 1800,
  "interval": 5
}

And if something goes wrong (like an invalidly configured client) 😬, the authorization server responds the same way as the token endpoint in Section 5.2 of [RFC6749].

3.3. User Interaction 📱

After the client gets a successful authorization response, it shows or otherwise communicates the "user_code" and the "verification_uri" to the end user. Then it tells them to visit that URI in a user agent on a secondary device (like a browser on their phone) and enter the code 💅.

          +-----------------------------------------------+
          |                                               |
          |  Using a browser on another device, visit:    |
          |  https://example.com/device                   |
          |                                               |
          |  And enter the code:                          |
          |  WDJB-MJHT                                    |
          |                                               |
          +-----------------------------------------------+

                  Figure 2: Example User Instruction

The authorizing user goes to the "verification_uri" and authenticates with the authorization server in a secure TLS-protected [RFC8446] session 🔒. The server then asks them to identify the device authorization session by typing in the "user_code" the client gave them. After that, the server SHOULD tell the user what action they're about to take and ask them to approve or deny the request. Once they're done, the server tells them to head back to their device 🎉.

While all this is happening, the device keeps polling the token endpoint with the "device_code" (more on that in Section 3.4) until the user finishes the interaction, the code expires, or some other error shows up 🌸. The "device_code" is NOT meant for the end user directly, so it SHOULD NOT be displayed during the interaction, so nobody gets confused 🙈.

Authorization servers that support this specification MUST implement a user-interaction sequence that starts with the user navigating to "verification_uri" and continues with them supplying the "user_code" at some stage during the interaction. Other than that, the exact sequence and implementation is totally up to the authorization server. For example, the server may let new users sign up for an account during the flow, or add extra security verification steps 🧚.

It is NOT RECOMMENDED for authorization servers to include the user code ("user_code") in the verification URI ("verification_uri"), because that makes the URI longer and more complicated for the user to type 😩. Yes, the user still has to type a similar number of characters with the "user_code" separated out, but once they land on the "verification_uri", the server can highlight any mistakes in the code to make things smoother ✨. The next section covers the user interaction with "verification_uri_complete", which is designed to carry both pieces of info.

3.3.1. Non-Textual Verification URI Optimization 📷

When "verification_uri_complete" is included in the authorization response (Section 3.2), clients MAY present this URI in a non-textual way, using any method that gets the browser opened with the URI, like QR (Quick Response) codes or NFC (Near Field Communication). This saves the user from typing anything 🦋.

For usability reasons, it is RECOMMENDED for clients to still display the textual verification URI ("verification_uri") for users who can't use that shortcut 💖. Clients MUST still display the "user_code", because the authorization server will require the user to confirm it to tell devices apart or as remote phishing mitigation (see Section 5.4). Don't skip it, bestie 🚨.

If the user starts the interaction by navigating to "verification_uri_complete", the user interaction described in Section 3.3 still applies, with the perk that the user doesn't have to type the "user_code". The server SHOULD display the "user_code" and ask the user to check that it matches the one shown on the device, so they know they're authorizing the right device 👀. As before, on top of confirming the device's identity, the user should also get to choose whether to approve or deny the request 👑.

          +-------------------------------------------------+
          |                                                 |
          |  Scan the QR code or, using     +------------+  |
          |  a browser on another device,   |[_]..  . [_]|  |
          |  visit:                         | .  ..   . .|  |
          |  https://example.com/device     | . .  . ....|  |
          |                                 |.   . . .   |  |
          |  And enter the code:            |[_]. ... .  |  |
          |  WDJB-MJHT                      +------------+  |
          |                                                 |
          +-------------------------------------------------+

    Figure 3: Example User Instruction with QR Code Representation
                   of the Complete Verification URI

3.4. Device Access Token Request 🔑

After showing the user their instructions, the client makes an access token request and sends it to the token endpoint (defined by Section 3.2 of [RFC6749]) with a "grant_type" of "urn:ietf:params:oauth:grant-type:device_code". This is an extension grant type (as defined by Section 4.5 of [RFC6749]) created by this specification 🌟, with these parameters:

grant_type REQUIRED. Value MUST be set to "urn:ietf:params:oauth:grant-type:device_code".

device_code REQUIRED. The device verification code, "device_code" from the device authorization response, defined in Section 3.2.

client_id REQUIRED if the client is not authenticating with the authorization server as described in Section 3.2.1. of [RFC6749]. The client identifier as described in Section 2.2 of [RFC6749].

Here's the HTTPS request (line breaks are just for display purposes) 💜:

POST /token HTTP/1.1
Host: server.example.com
Content-Type: application/x-www-form-urlencoded

grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Adevice_code
&device_code=GmRhmhcxhwAzkoEqiMEg_DnyEysNkuNhszIySk9eS
&client_id=1406020730

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]. Heads up though: there are security implications of statically distributed client credentials, so check Section 5.6 🥺.

The response to this request is defined in Section 3.5. Unlike other OAuth grant types, the client is expected to retry the access token request repeatedly in a polling fashion, based on the error code in the response 🔄✨.

3.5. Device Access Token Response ✨

Okay so if the user said yes 🥹, the token endpoint sends back a success response, defined in Section 5.1 of [RFC6749]. If they didn't, it sends back an error instead, as defined in Section 5.2 of [RFC6749]. 💅

On top of the error codes from Section 5.2 of [RFC6749], this flow adds these error codes for token endpoint responses:

  • authorization_pending ⏳: the user hasn't finished the user-interaction steps yet (Section 3.3), so the request is still pending. The client SHOULD repeat the access token request to the token endpoint, which is called polling. Before each new request, the client MUST wait at least the number of seconds set by the interval parameter in the device authorization response (see Section 3.2), or 5 seconds if no interval was given. It also needs to respect any increase in the polling interval that a slow_down error asks for.
  • slow_down 🐢: this is a variant of authorization_pending. The request is still pending and polling should keep going, but the interval MUST be increased by 5 seconds for this request and all the ones after it.
  • access_denied 🚫: the authorization request was denied. Rude, but it happens.
  • expired_token ⌛: the device_code has expired, so the device authorization session is over. The client MAY start a new device authorization request, but SHOULD wait for user interaction before restarting, so it isn't polling for no reason.

authorization_pending and slow_down are the special ones 🌟. They tell the OAuth client to keep polling the token endpoint by repeating the token request, using the exact behavior described above. If the client gets an error response with any other error code, it MUST stop polling and SHOULD react accordingly, for example by showing an error to the user.

When a connection timeout happens, clients MUST unilaterally reduce their polling frequency before retrying 📉. Using an exponential backoff algorithm to do that, like doubling the polling interval on each connection timeout, is RECOMMENDED.

The assumption here is that the separate device where the user approves the request has no way to talk back to the device running the OAuth client 📺. This protocol only needs a one-way channel, which keeps it viable in restricted environments, like a TV app that can only make outbound requests. If the chosen user-interaction interface did have a return channel, the device MAY wait until it's notified on that channel that the user has finished the action before sending the token request, instead of polling. That behavior is, however, outside the scope of this specification.

4. Discovery Metadata 🗺️

Support for this protocol is declared in OAuth 2.0 Authorization Server Metadata [RFC8414], like this. The value urn:ietf:params:oauth:grant-type:device_code is included in the values of the grant_types_supported key, and the following new key-value pair is added:

  • device_authorization_endpoint: OPTIONAL. This is the URL of the authorization server's device authorization endpoint, as defined in Section 3.1.

5. Security Considerations 🔒

Okay bestie, this part is serious, so let's get into it 😭🔒

5.1. User Code Brute Forcing 🔢

Since the user code gets typed in by the user, shorter codes are more desirable for usability reasons. That means the entropy is usually lower than what you'd use for the device code or other OAuth bearer token types, where the code length doesn't affect usability. So it's recommended that the server rate-limit user code attempts.

The user code SHOULD have enough entropy that, when you combine it with rate-limiting and other mitigations, a brute-force attack becomes infeasible. For example, it's generally held that 128-bit symmetric keys for encryption are good enough today, because an attacker has to do 2^96 work to have a 2^-32 chance of guessing correctly by brute force. The rate-limiting and finite lifetime on the user code put an artificial limit on how much work an attacker can "do". If, for instance, someone uses an 8-character base 20 user code (with roughly 34.5 bits of entropy), the rate-limiting interval and validity period would only need to allow 5 attempts to get the same 2^-32 probability of success by random guessing.

A successful brute force of the user code would let the attacker approve the authorization grant with their own credentials. After that, the device would receive a device authorization grant linked to the attacker's account 🙈. This is the opposite of an OAuth bearer token being brute forced, where the attacker takes control of the victim's authorization grant. These attacks don't always make economic sense. For example, with a video app, the device owner may then be able to buy movies using the attacker's account. Even then, a privacy risk would still remain, so it's important to protect against it anyway. Also, some uses of the device flow give the granting account the ability to perform actions that need protecting, such as controlling the device.

The precise length of the user code and the entropy inside it is up to the authorization server. When it picks the user code format, it needs to consider how sensitive its protected resources are, how practical the code length is from a usability standpoint, and any mitigations in place, such as rate-limiting.

5.2. Device Code Brute Forcing 🔐

An attacker who guesses the device code could potentially obtain the authorization code once the user completes the flow 😬. Since the device code isn't displayed to the user, there are no usability considerations on its length, so a very high entropy code SHOULD be used.

5.3. Device Trustworthiness 🤔

Unlike other native application OAuth 2.0 flows, the device requesting the authorization is not the same device the user grants access from. So signals from the approving user's session and device aren't always relevant to how trustworthy the client device is.

Note that if an authorization server used with this flow is malicious, it could perform a man-in-the-middle attack on the backchannel flow to another authorization server. In this case, the man-in-the-middle isn't completely hidden, because the end user would land on the authorization page of the wrong service. That gives them a chance to notice the URL in the browser's address bar is wrong 👀. For this to happen, the device manufacturer would have to be the attacker and ship a device meant to perform the man-in-the-middle attack, or the device would have to be using an authorization server controlled by an attacker, maybe because the attacker compromised the authorization server the device uses. In part, the person buying the device is counting on the manufacturer and its business partners to be trustworthy.

5.4. Remote Phishing 🎣

The device flow can be started on a device that's in an attacker's possession. For example, an attacker might email the target user, telling them to visit the verification URL and enter the user code 📧. To mitigate this, it is RECOMMENDED to tell the user that they're authorizing a device during the user-interaction step (see Section 3.3), and to confirm that the device is in their possession. The authorization server SHOULD display information about the device, so the user can notice if a software client is trying to pass itself off as a hardware device.

For authorization servers that support the verification_uri_complete optimization discussed in Section 3.3.1, it's especially important to confirm that the device is in the user's possession. That's because the user no longer has to type in the code shown on the device by hand. One suggestion is to display the code during the authorization flow and ask the user to check that the same code is showing on the device they're setting up.

The user code needs a long enough lifetime to be usable, so the user has time to grab their second device, go to the verification URI, log in, and so on. It should also be short enough to limit how useful a code is if someone gets hold of it for phishing. This doesn't stop a phisher from presenting a fresh token, especially if they're chatting with the user in real time. It does, however, limit how useful codes sent over email or text message are.

5.5. Session Spying 👀

While the device is pending authorization, a malicious person might physically spy on the device's user interface, like by looking at the screen it's displayed on, and hijack the session by finishing the authorization faster than the user who started it 😱. Devices SHOULD take the operating environment into account when deciding how to show the code to the user, to lower the chances a malicious person will see it.

5.6. Non-Confidential Clients 🫣

Device clients generally can't keep their credentials confidential, because users who have the device can reverse-engineer it and pull the credentials out. So unless additional measures are taken, they should be treated as public clients (as defined by Section 2.1 of [RFC6749]), which are open to impersonation. The security considerations of Section 5.3.1 of [RFC6819] and Sections 8.5 and 8.6 of [RFC8252] apply to such clients.

The user may also be able to get the device_code and/or other OAuth bearer tokens issued to their client. That would let them use their own authorization grant directly by impersonating the client. Since a user who has the client credentials can already impersonate the client and create a new authorization grant (with a new device_code), this doesn't count as a separate impersonation vector 🙌.

5.7. Non-Visual Code Transmission 🔊

There's no requirement that the user code be shown visually on the device. Other one-way communication methods can work too, like text-to-speech audio or Bluetooth Low Energy 🎧. To mitigate an attack where a malicious user bootstraps their credentials on a device they don't control, it is RECOMMENDED that any chosen communication channel can only be reached by people who are physically close, like users who can see or hear the device.

6. Usability Considerations 🌸

This section is a non-normative discussion of usability considerations.

6.1. User Code Recommendations 📱

Okay bestie, let's talk about the user code 💅 For lots of people, their nearest internet-connected device is their phone, and phone keyboards are kinda slow when you need to switch case or type numbers 😭 So to speed up entry and cut down on retries, we have to think about those limits when we pick the character set.

One move is to stick with case-insensitive A-Z letters and no digits. Those can usually be typed on a phone keyboard without any modifier keys. Then you remove the vowels so nobody accidentally spells a real word, and you get the base 20 set BCDFGHJKLMNPQRSTVWXZ 🦋 Dashes or other punctuation can be added for readability ✨

Take WDJB-MJHT. It has 8 significant characters, with dashes added so end users can read it easily, and its entropy is 20^8 🔥

Pure numeric codes are also a great choice for usability 🔢, especially for clients targeting locales where A-Z keyboards aren't the norm 🌏. The code just needs to be longer to keep the entropy high.

Here's a numeric example with 9 significant digits, dashes added for readability, and an entropy of 10^9: 019-450-730 💖

When the server processes the input, it should strip the dashes and other punctuation it added for readability, so the user including that punctuation is totally optional 🫶 For codes that only use A-Z, like the base 20 set above, the server should uppercase the input before comparing, because the user might type lowercase letters 🌸 It's also recommended to strip every character outside the chosen set, so an errant space can't wreck otherwise-valid input 🙈

It is RECOMMENDED to avoid character sets with two or more characters that are easy to mix up, like 0 and O, or 1, l and I. 🧐 And where it's practical, if a set includes a character that people might confuse with one outside the set, a character outside the set MAY be swapped in for the one it's commonly mixed up with. For example, O may be substituted for 0 when you're using the numerical 0-9 character set 👑

6.2. Non-Browser User Interaction 🌈

Devices and authorization servers MAY negotiate an alternative code transmission and user-interaction method on top of the one described in Section 3.3 ✨ This could mean no browser and no typing the code by hand. For example, the code could be sent over Bluetooth to the authorization server's companion app 📲 These methods can still use this protocol, because all the user really has to do is identify the authorization session to the authorization server 💜 Just know that user interaction other than through the verification URI is outside the scope of this specification 🙃

7. IANA Considerations 📋

7.1. OAuth Parameter Registration 🎀

This specification registers the following values in the IANA "OAuth Parameters" registry [IANA.OAuth.Parameters] established by [RFC6749].

Name: device_code
Parameter Usage Location: token request
Change Controller: IESG
Reference: Section 3.4 of RFC 8628

7.2. OAuth URI Registration 🦋

This specification registers the following values in the IANA "OAuth URI" registry [IANA.OAuth.Parameters] established by [RFC6755].

URN: urn:ietf:params:oauth:grant-type:device_code
Common Name: Device Authorization Grant Type for OAuth 2.0
Change Controller: IESG
Specification Document: Section 3.4 of RFC 8628

7.3. OAuth Extensions Error Registration ⚠️

This specification registers the following values in the IANA "OAuth Extensions Error Registry" registry [IANA.OAuth.Parameters] established by [RFC6749].

Name: authorization_pending
Usage Location: Token endpoint response
Protocol Extension: RFC 8628
Change Controller: IETF
Reference: Section 3.5 of RFC 8628

Name: access_denied
Usage Location: Token endpoint response
Protocol Extension: RFC 8628
Change Controller: IETF
Reference: Section 3.5 of RFC 8628

Name: slow_down
Usage Location: Token endpoint response
Protocol Extension: RFC 8628
Change Controller: IETF
Reference: Section 3.5 of RFC 8628

Name: expired_token
Usage Location: Token endpoint response
Protocol Extension: RFC 8628
Change Controller: IETF
Reference: Section 3.5 of RFC 8628

7.4. OAuth Authorization Server Metadata 🗂️

This specification registers the following values in the IANA "OAuth Authorization Server Metadata" registry [IANA.OAuth.Parameters] established by [RFC8414].

Metadata name: device_authorization_endpoint
Metadata Description: URL of the authorization server's device
authorization endpoint
Change Controller: IESG
Reference: Section 4 of RFC 8628

8. Normative References 📚

Acknowledgements 🫶

This doc started life as the Internet-Draft draft-recordon-oauth-v2-device, written by David Recordon and Brent Goldman 💜 That draft was built on content from earlier draft versions of the OAuth 2.0 protocol specification, which were removed before publication because there wasn't enough deployment expertise to back them up at the time 🙈 Huge thanks to the OAuth Working Group members who contributed to those earlier drafts ✨

This document was produced in the OAuth Working Group under the chairpersonship of Rifaat Shekh-Yusef and Hannes Tschofenig, with Benjamin Kaduk, Kathleen Moriarty, and Eric Rescorla serving as Security Area Directors 👑

The following individuals contributed ideas, feedback, and wording that shaped and formed the final specification: Ben Campbell, Brian Campbell, Roshni Chandrashekhar, Alissa Cooper, Eric Fazendin, Benjamin Kaduk, Jamshid Khosravian, Mirja Kuehlewind, Torsten Lodderstedt, James Manger, Dan McNulty, Breno de Medeiros, Alexey Melnikov, Simon Moffatt, Stein Myrseth, Emond Papegaaij, Justin Richer, Adam Roach, Nat Sakimura, Andrew Sciberras, Marius Scurtescu, Filip Skokan, Robert Sparks, Ken Wang, Christopher Wood, Steven E. Wright, and Qin Wu 🌸

Authors' Addresses 🎀

William Denniss
Google
1600 Amphitheatre Pkwy
Mountain View, CA  94043
United States of America

Email: wdenniss@google.com
URI:   https://wdenniss.com/deviceflow


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
📦 where this page comes from