What Is the OAuth 2.0 Device Authorization Flow?

The OAuth 2.0 Device Authorization Grant (RFC 8628), more commonly known as “Device Authorization Flow” or "Device Flow," enables secure authentication for Internet-connected devices that either lack a browser or have limited input capabilities. Device Flow addresses the friction faced when logging in on smart TVs, gaming consoles, IoT devices, and other hardware that makes traditional credential entry cumbersome and frustrating.

Unlike standard OAuth flows, Device Flow separates the authentication process from the device requesting access. This decoupling creates a streamlined user experience where authentication happens on a secondary device with more user-friendly input options, typically a smartphone.

Main points

• What is Device Flow? An OAuth flow that decouples authentication from the device requesting access, enabling login for devices with limited input options.

• How it works: Device displays a short user code and URL (often via QR code) to the user, who then uses another device to visit the URL, enter the user code, authenticates, and authorizes the device.

• Security and usability: Balances convenience with security by eliminating the need to enter passwords on cumbersome interfaces while maintaining OAuth's token-based security design.

Let’s explore the core components of Device Flow, demonstrate a complete authorization sequence, examine real-world implementations, and consider how this flow makes logging in easier for end users.

Step-by-step Device Authorization flow

Here’s how the Device Flow works, step by step:

• Device authorization request: The device calls the Device Authorization endpoint to get a device_code, user_code, verification_uri (and verification_uri_complete), plus expires_in and a polling interval.

• Show the user what to do: The device displays the user code and verification URL (or a QR code that encodes verification_uri_complete).

• User verification and authentication: On a secondary device (e.g., a phone/computer), the user opens the link, confirms the user code, and (if needed) authenticates the user while collecting consent.

• Poll for completion: The device polls the token endpoint with the device_code at the suggested interval until it receives success or a terminal error (authorization_pending, slow_down, access_denied, expired_token).

• Receive tokens and proceed: On success, the token endpoint returns an access_token (and an id_token, plus a refresh_token). The device stores these and calls protected APIs and resources with the access_token.

Device Flow example: Logging in to a streaming service on a smart TV

Suppose you want to watch a movie on Netflix through your smart TV. You’ve installed the Netflix app on your device, and you have the option to manually enter your credentials. But another option catches your eye: a QR code that you can simply scan with your smartphone camera.

Here's how this interaction would play out:

1. Initiate the process: You open the app and are prompted to sign in. You select the option to log in without typing your password, and a URL is shown along with a user code, plus a QR code that contains both pieces of information.

2. See the instructions: The TV app will display a message, like "To sign in, go to example.com/device in your browser and enter the code WDJB-MJHT."

3. Visit the website: You open the website on your phone's browser, either by typing or scanning the QR code.

4. Code entry: If you manually typed the URL, you'll need to enter the code shown on your TV. If you scan the QR code, it often fills in automatically.

5. Sign in normally: You log in with your credentials just as you usually would, likely skipping this step if you're already logged in on your phone.

6. Display scopes: If the application is requesting scopes that aren't implied (i.e., using your Netflix account to sign in on another device), you'll see the permissions it wants here.

7. Show confirmation: Once logged in, you typically see a simple success message like "You can now return to your device" or "Your app is now connected."

8. Automatic completion: Your TV detects that you've authenticated and automatically signs you in to your account.

Thanks to the Device Flow, at no point did you need to awkwardly fiddle with an on-screen keyboard, punching in your password by navigating across each character one at a time. All the action took place on your smartphone, and if you scanned the QR code, you didn’t even need to type.

The building blocks of Device Flow

As the examples above highlight, the Device Authorization Flow involves several steps across two devices: the requesting device (with limited input) and the authorization device (e.g., the user's phone/computer). You’ll need a basic understanding of OAuth concepts to follow along with some of these essential building blocks. 

Check out our learning center guide on OAuth for a beginner-friendly introduction that will contextualize the following section.

Device Flow concepts from OAuth

These are the components and concepts common to OAuth flows and Device Flow:

• Access tokens: An access_token is a digital key that contains scopes and gives the device permission to access resources.

• Scopes: The specific permissions the device is requesting.

• Grant type: Device Flow has its own special grant type (urn:ietf:params:oauth:grant-type:device_code) to identify the auth method.

• Client identifier: The client_id identifies the device to the server.

Device Flow endpoints

Endpoints refer to the location at which information is relayed during the Device Flow.

• Device authorization endpoint: Where the device starts the process and receives codes.

• Token endpoint: Where the device checks for authentication completion.

Key Device Flow codes and parameters

These parameters refer to the different variables necessary for completing the process.

• Device code: A device_code is a code only the device and authorization server know about.

• User code: A user_code is a human-friendly code short enough for easy typing.

• Verification URI: The verification_uri is the web address users must visit on their secondary device.

• QR code option: Many Device Flow implementations offer a scannable code (via smartphone camera) for easier access to the verification URI (verification_uri_complete), which often inputs the user code automatically through the encoded URL.

Polling approach

Once the process begins, the initiating device repeatedly polls for a response from the server. 

• Checking for completion: The device periodically asks if the user has approved access.

• Time limits: Codes expire after a set time to prevent fraudulent use (expires_in).

• Status updates: The device polls the authorization server (at the polling interval) to find out if the authorization has been completed. 

Secondary device interactions

The points below describe the user experience on the second device, typically a smartphone.

• Code validation: The system verifies the user code that was entered or included in the URL.

• User authentication: Normal login experience on the user’s device, per the requirements of the associated app (e.g., logging in on the Netflix website to log in on a smart TV).

• Scopes verification: Some flows show an additional screen outlining the specific permissions (i.e., access to contacts), including an additional confirmation that the user would like to delegate access to the device.

• Post-login notification: Some services send a notification (via email or app) about a new device being activated, ensuring a legitimate user was behind the addition.

Error handling

The authorization server sends specific error codes for different scenarios:

• authorization_pending: User hasn't completed authentication yet, continue polling.

• slow_down: Continue polling but increase the interval by 5 seconds.

• access_denied: User denied the authorization request.

• expired_token: The device code has expired, start over.

Device Flow in real-world scenarios

Device Flow offers many advantages over traditional authentication methods, especially in situations where user input is hampered by device constraints. While the smart TV example above represents one of the most familiar use cases, Device Flow has proven valuable across widely varying contexts.

IoT device login

Smart home devices like security cameras, thermostats, and lighting systems typically have no interface or input capabilities. Instead, they rely on an app or browser powered by a smartphone to authenticate with the user’s account. Devices like these, which lack any input options, almost solely rely on Device Flow to connect with external systems. And, because many of these devices are tied to a person’s private life, it’s crucial that they’re secure. Device flow helps them avoid storing or handling credentials.

Game consoles

While hooking up a mouse and keyboard to your Xbox isn’t unheard of, gaming consoles still present a classic case of input constraints. Using a standard controller to navigate an on-screen keyboard is frustrating and error-prone, which is why Device Flow is a favorite alternative for console gamers. Like smart TVs, game consoles often have purchasing power for digital content, making Device Flow’s inherent security posture even more compelling.

Printer and scanner setup

Modern printers are rarely isolated from the web, but even the latest models don’t offer much in the way of input options. Setting up internet-connected scanners and printers used to involve configuring everything on a tiny screen, but now Device Flow lets users log in to cloud services via a secondary device. While printers have long been considered finicky devices, this lower-friction login method takes some of the pressure off of first-time setup.

Security and implementation considerations

User code security

Since the user code is typed by the user, shorter codes are desirable for usability reasons. This means the entropy (randomness) is typically less than what would be used for the device code itself, where the code length does not impact usability. Therefore, it is considered best practice to rate-limit user code attempts.

Device code security

An attacker who guesses the device code (e.g., by brute force) would be potentially able to obtain the authorization code once the user completes the flow (by inputting the user code). Since the device code is not displayed to the user (meaning there are no usability considerations on the length), a very high entropy code SHOULD be used.

Remote phishing protection

Phishing attacks on device codes are well-documented in the wild. For example, a threat actor might send a message instructing the target user to visit the verification URL and enter the user code. This allows the attacker to capture the access and refresh tokens that are generated. To mitigate such an attack, it is RECOMMENDED to inform the user that they are authorizing a device during the user-interaction step and to confirm that the device is in their possession.

User code best practices

For many users, their nearest Internet-connected device will be their smartphone; typically, these devices offer input methods that make it more difficult to change the case or character than a computer keyboard. To improve usability (improving entry speed and reducing retries), the limitations of such devices should be taken into account when selecting the user code character set:

• Base 20 characters: Using case-insensitive characters like "BCDFGHJKLMNPQRSTVWXZ" (avoiding vowels and confusing characters)

• Pure numeric codes: Good for locales where A-Z keyboards aren't standard

• Readable formatting: Include dashes or punctuation for readability (e.g., "WDJB-MJHT" or "019-450-730")

Drag & drop Device Flow with Descope

OAuth 2.0 Device Authorization Grant provides an elegant solution for authentication on input-constrained devices. By separating the authentication process from the requesting device, it delivers both security and usability benefits. However, implementing and maintaining device authentication flows requires identity expertise and ongoing developer commitment to keep up with the OAuth standard and its recommended security best practices. 

Descope provides developers with APIs and no / low code workflows to easily deploy Device Authorization Flows for users to seamlessly access Internet-connected devices. Descope acts as the Authorization Server and takes care of authentication, user code input and confirmation, and token exchange and management. You can learn more in Descope’s documentation.

Sign up for a free account to set up your own Device Flow with Descope. Have questions about our product? Book a demo with our team to learn more.