Uitsmijter — OAuth 2.0 Device Authorization Grant (RFC 8628)

Feature requests
,
1

Uitsmijter is set to expand its OAuth 2.0 capabilities in the upcoming 0.11 release by implementing the Device Authorization Grant, as defined in RFC 8628. This addition addresses a fundamental challenge in modern authentication: how do you securely authenticate a user on a device that has no practical way to open a browser or accept keyboard input?

The Problem It Solves

Traditional OAuth 2.0 flows — Authorization Code, Implicit, and their PKCE variants — rely on the ability to redirect a user’s browser to an authorization server and back. This works perfectly on desktops and smartphones, but breaks down in a growing category of environments:

  • Command-line tools (CLIs) — developer tools, deployment agents, and build pipelines running in headless terminals
  • Smart TVs and set-top boxes — media applications where navigating to a URL and typing a code is cumbersome or impossible with a remote
  • IoT and embedded devices — sensors, kiosks, printers, home automation hubs, and industrial controllers with limited or no display
  • Gaming consoles — platforms with restrictive browser environments
  • Shared or locked-down machines — environments where a full browser session cannot be initiated

These are collectively called input-constrained devices, and they need a different authentication pathway.

How the Flow Works

The Device Authorization Grant introduces an out-of-band authentication pattern, meaning authentication happens on a separate, more capable device (like a smartphone or laptop) rather than the device requesting access. The flow proceeds as follows:

1. Device Registration Request

The device (e.g. a CLI tool) sends a request to Uitsmijter’s device authorization endpoint, identifying itself with its client_id and the OAuth scopes it requires. No user involvement is needed at this point.

2. Code Issuance

Uitsmijter responds with three key values:

  • device_code — a long, opaque token used internally by the device to poll for a result
  • user_code — a short, human-readable code (typically 8 characters, e.g. WDJB-MJHT) displayed to the user
  • verification_uri — the URL the user should visit on another device (e.g. https://auth.example.com/device)

An optional verification_uri_complete may also be returned, embedding the user code directly in the URL so it can be encoded as a QR code for even smoother UX.

3. User Interaction (on a Secondary Device)

The user takes out their phone or opens a laptop and:

  1. Navigates to the verification URL
  2. Authenticates with Uitsmijter (username/password, SSO, MFA — whatever is configured)
  3. Enters the displayed user code
  4. Reviews and approves the authorization request (scopes, client name, etc.)

This step happens entirely within a familiar, capable browser environment.

4. Device Polling

While the user completes step 3, the original device repeatedly polls Uitsmijter’s token endpoint, presenting its device_code. Uitsmijter will respond with one of several states:

Response Meaning
authorization_pending User hasn’t finished yet — keep polling
slow_down Polling too fast — increase the interval
expired_token The user code has expired — restart the flow
access_denied The user explicitly declined
Token response Authorization succeeded — tokens issued

The polling interval and code expiry window are both communicated in the initial response (typically 5-second intervals and a 15-minute expiry).

5. Token Issuance

Once the user approves, the next poll returns a standard OAuth 2.0 token response: an access token, optionally a refresh token, and an ID token if OpenID Connect is in use. The device can now authenticate API requests on behalf of the user.

Why This Matters for Uitsmijter

Uitsmijter already handles Authorization Code + PKCE flows, client credentials, and token introspection. Adding Device Authorization Grant means it can now serve as the single identity backbone for an organization’s entire surface area — not just web apps and mobile clients, but every CLI tool, every TV app, every IoT endpoint that needs to act on behalf of a real, authenticated user.

This is particularly relevant for:

  • Developer toolchains — teams using Uitsmijter for SSO can now authenticate their internal CLI tools (deployment scripts, admin utilities, data pipelines) against the same identity provider
  • Media and entertainment platforms — TV and streaming applications can leverage Uitsmijter for subscription-gated content access
  • Industrial and enterprise IoT — devices operating in secure environments can be tied to specific user identities with full audit trails

Release Timeline

Device Authorization Grant is planned as part of the Uitsmijter 0.11 release chain, which is targeted for launch at the beginning of Q2 2026 — around April 2026. The 0.11 milestone represents a significant expansion of Uitsmijter’s protocol surface and positions it for broader adoption in device-centric and enterprise deployment scenarios.