Logan.Portfolio

OAuth 2.0 Series

OAuth 2.0 Grant Types: Device Authorization Flow

The Device Authorization Flow (also known as Device Code Flow) is an OAuth 2.0 grant type specifically designed for devices with limited input capabilities or without a full web browser. These devices are often referred to as "input-constrained devices" or "browserless devices."

← Back to Learnings

What is the Device Authorization Flow?

Primary Purpose: To enable users to authorize an application on a constrained device (e.g., Smart TV, IoT device, Command Line Interface tool) to access their protected resources without requiring the user to directly enter sensitive credentials (username/password) on that device.

Instead, the user will use another device with a full browser (like a smartphone, tablet, or desktop computer) to complete the authentication and authorization process.

Example Use Case:

You purchase a new Smart TV and want to log into the YouTube app on the TV. Instead of typing a long email address and password using the TV remote, the YouTube app on the TV displays a short code and a brief URL. You simply access that URL on your phone, enter the code, and grant access.

Key Roles in the Device Authorization Flow

The roles are similar to other OAuth 2.0 flows, but their interaction differs slightly:

  • Resource Owner: The end-user (you) who owns the data on the Resource Server.
  • Device (Client): The input-constrained application/device (Smart TV, IoT device, CLI tool). This is the "Client" in this context.
  • Authorization Server: The server responsible for authenticating the Resource Owner and issuing tokens.
  • Resource Server: The server hosting the protected resources (e.g., Google Photos, YouTube API).

Detailed Flow of Operations

Let's imagine you're trying to connect the YouTube app on your Smart TV to your Google account:

graph TB A["📺 Smart TV (Device)"] B["🔐 Authorization Server"] C["📱 User's Phone/Computer"] D["🗄️ Resource Server (YouTube API)"] A -->|"1. Request device code"| B B -->|"2. Return device_code & user_code"| A A -->|"3. Display user_code & URL"| A C -->|"4. Visit URL & enter code"| B B -->|"5. User authentication & consent"| C A -->|"6. Poll for tokens"| B B -->|"7. Return access_token"| A A -->|"8. API requests"| D D -->|"9. Protected resources"| A

Step-by-Step Explanation:

Step 1: Device requests a device code and user verification code

  • Your Smart TV's YouTube app (Device/Client) sends an HTTP POST request to the Authorization Server's device_authorization endpoint.
  • This request typically includes the application's client_id and the desired scope (permissions).

Request Example (Smart TV to Authorization Server):

POST /device/code HTTP/1.1
Host: accounts.google.com
Content-Type: application/x-www-form-urlencoded

client_id=YOUR_TV_APP_CLIENT_ID&
scope=https://www.googleapis.com/auth/youtube.readonly

Step 2: Authorization Server responds with device code, user code, and verification info

  • The Authorization Server generates a device_code (for the device to poll status) and a user_code (for the user to enter into a browser).
  • It also provides a verification_uri (the URL the user needs to visit) and an interval (the time the device should wait before checking status again).
  • On the Smart TV: The YouTube app will display the user_code (e.g., "ABCDEFGH") and the verification_uri (e.g., "google.com/device") to you.

Response Example (Authorization Server to Smart TV):

HTTP/1.1 200 OK
Content-Type: application/json

{
    "device_code": "AH-1Ng31ha...",
    "user_code": "WDJB-MJHT",
    "verification_uri": "https://www.google.com/device",
    "verification_uri_complete": "https://www.google.com/device?user_code=WDJB-MJHT",
    "expires_in": 1800,
    "interval": 5
}

Step 3: User verifies and grants consent

  • You (the Resource Owner) open a browser on your phone or computer.
  • You navigate to the verification_uri displayed on the TV.
  • The Google website will prompt you to log in (Authentication).
  • After logging in, the website will ask you to enter the user_code (e.g., "WDJB-MJHT") displayed on the TV.
  • Once you enter the correct code, Google will display a consent screen detailing the permissions the YouTube app on your TV is requesting.
  • You confirm and grant authorization.

Step 4: Device polls the Authorization Server for tokens

  • Meanwhile, your Smart TV continuously sends POST requests to the Authorization Server's /token endpoint, using the device_code it received in Step 2.
  • It will do this according to the provided interval (e.g., every 5 seconds).

Polling Request Example (Smart TV to Authorization Server):

POST /oauth2/v4/token HTTP/1.1
Host: accounts.google.com
Content-Type: application/x-www-form-urlencoded

grant_type=urn:ietf:params:oauth:grant-type:device_code&
device_code=AH-1Ng31ha...&
client_id=YOUR_TV_APP_CLIENT_ID

Step 5: Authorization Server responds with tokens or an error

  • If the user has not yet completed authorization: The Authorization Server will return an authorization_pending error (or similar), instructing the device to continue polling.
  • If the user has granted authorization: When you've completed the authorization on your phone/computer, the Smart TV's next poll will receive the access_token (and a refresh_token if requested and supported by your client).

Pending Response Example:

HTTP/1.1 400 Bad Request
Content-Type: application/json

{
    "error": "authorization_pending",
    "error_description": "The authorization request is still pending"
}

Success Response Example:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "access_token": "ya29.a0AWTD...",
    "token_type": "Bearer",
    "expires_in": 3599,
    "refresh_token": "1//0ewt_P...",
    "scope": "https://www.googleapis.com/auth/youtube.readonly"
}

Step 6: Device uses the Access Token to access resources

  • Your Smart TV uses the access_token to call the YouTube API (Resource Server) to read your channel data, play videos, etc.
  • The access_token is typically included in the Authorization header as a Bearer token.

Advantages of Device Authorization Flow

  • Constrained Device Friendly: Solves the input and display challenges on devices without a full browser.
  • Secure: Does not require the user to enter sensitive credentials directly on the constrained device, minimizing credential exposure risk. The access_token also does not pass through the user-agent (browser) of the constrained device.
  • Improved User Experience: Much easier than attempting to log in using a virtual keyboard on a TV or a CLI.

Disadvantages of Device Authorization Flow

  • Requires a Second Device: The user needs access to another device with a full browser to complete the authorization process.
  • User Dependency: The entire flow stalls if the user does not complete the code verification and consent steps.
  • Polling: The constrained device must continuously poll the Authorization Server, which can create overhead if the interval is too short or if there are many devices.

Security Considerations and Best Practices

Critical Security Requirements:

1. HTTPS is Mandatory:

All communications must be encrypted using HTTPS to protect codes (device_code, user_code) and tokens in transit.

2. Code Expiration:

device_code and user_code must have a short lifespan to reduce the risk of brute-force attacks or misuse.

3. Randomness of Codes:

user_code and device_code must be randomly generated and sufficiently complex to prevent guessing.

4. Polling Rate Control:

The Authorization Server must control the frequency at which devices poll to prevent Denial of Service (DoS) attacks or abuse. If a device polls too quickly, the Authorization Server may deny requests or increase the returned interval.

5. User Experience (UX):

Ensure users clearly understand the steps required on both devices. Clear instructions are paramount.

Conclusion

The Device Authorization Flow is an essential OAuth 2.0 grant type that bridges the gap between secure authentication and user experience for input-constrained devices. By separating the user interaction from the device itself, it provides a secure and user-friendly method for authorizing applications on Smart TVs, IoT devices, CLI tools, and other browserless devices. Its implementation requires careful attention to security considerations, particularly around code generation, expiration, and polling controls.

← Back to Learnings