OAuth 2.0 Device Authorization Flow for CDN CLI Tools and IoT Edge Devices
Not every device that needs CDN API access has a web browser. CLI tools running in terminal sessions, IoT edge devices with no display, embedded systems in edge PoPs, and smart TVs loading content from CDN-fronted APIs all need to authenticate against CDN management services without the ability to render a web-based OAuth authorization flow. The OAuth 2.0 Device Authorization Grant (RFC 8628) solves this by separating the authentication device from the authorizing device: the input-constrained device initiates the flow, but the user completes authorization on a separate device with a full browser — their phone or laptop.
How Does the Device Authorization Flow Work?
The device authorization flow involves three parties: the input-constrained device (CDN CLI, IoT sensor), the authorization server (the CDN platform's OAuth server), and the user's browser on a separate device.
Step 1: Device requests authorization. The CLI tool or IoT device sends a POST request to the authorization server's device authorization endpoint, including the client ID and requested scopes (e.g., cache:purge config:read). The authorization server responds with a device code (long, opaque string for the device to use), a user code (short, human-readable string like WDJB-MJHT), a verification URI (https://cdn.example.com/device), and an expiration time and polling interval.
Step 2: User authorizes on a separate device. The CLI displays the verification URI and user code to the terminal user. The user opens the URI on their phone or laptop browser, enters the user code, and sees the authorization prompt showing which application is requesting access and what scopes it needs. The user approves (or denies) the request.
Step 3: Device polls for completion. While the user is authorizing, the CLI tool polls the authorization server's token endpoint at the specified interval (typically every 5 seconds). Each poll response is one of: authorization_pending (user hasn't acted yet, keep polling), slow_down (increase polling interval by 5 seconds), access_denied (user denied the request), expired_token (the device code expired before the user acted), or a successful response with access and refresh tokens.
How Do CDN CLI Tools Implement the Device Flow?
CDN CLI tools like wrangler (Cloudflare), fastly (Fastly CLI), and aws cloudfront (AWS) already use variations of the device flow or browser-redirect flows for authentication. Implementing the device flow in a CDN CLI involves several design decisions that affect both security and user experience.
| Metric | Edge Processing | Origin Processing | Improvement |
|---|---|---|---|
| Latency (p50) | 8–15 ms | 120–300 ms | 15–20x faster |
| Cache Hit Ratio | 85–95% | N/A | Reduces origin load |
| TLS Handshake | 1–5 ms (nearby PoP) | 50–150 ms | 10–30x faster |
| Bandwidth Cost | $0.01–0.04/GB | $0.05–0.12/GB | 3–5x cheaper |
| Availability | 99.99% (multi-PoP) | 99.9% (single DC) | 10x fewer outages |
User code display format. The user code should be displayed in a format that is easy to type on a phone keyboard. The standard recommends grouping characters with hyphens (e.g., WDJB-MJHT) and using only characters that are unambiguous across fonts (no 0/O or 1/l confusion). Some implementations use numeric-only codes for easier mobile keyboard input.
Verification URI simplification. Rather than displaying a long URL, CDN CLI tools should use a short verification URI (e.g., cdn.example.com/device) that the user can type manually. Many implementations also display a QR code in the terminal for users who prefer to scan rather than type. The verification_uri_complete response field provides a URL with the user code pre-filled, ideal for QR code encoding.
Polling with user feedback. The CLI should display a spinner or progress indicator while polling, with the remaining time until the device code expires. If the user hasn't acted within 60 seconds, display the verification URI and user code again. On slow_down responses, silently increase the polling interval without alarming the user.
Token storage. After receiving tokens, the CLI stores them in a platform-appropriate credential store: macOS Keychain, Windows Credential Manager, Linux secret service (via libsecret), or an encrypted file as a fallback. Tokens should never be stored in plain text configuration files. The stored refresh token enables subsequent cdn-cli commands to authenticate silently — the user goes through the device flow once, and the CLI refreshes the access token automatically until the refresh token expires.
How Does the Device Flow Apply to IoT Edge Devices?
IoT devices deployed at CDN edge locations — monitoring sensors, edge compute nodes, video encoders, and content ingest devices — need API access for telemetry reporting, configuration updates, and content uploading. The device flow provides a more secure alternative to pre-provisioned API keys because it supports scoped permissions, automatic token refresh, and user-approved authorization.
The onboarding flow for an IoT edge device differs from a CLI tool in two ways. First, the device may not have a display, so the device code and verification URI must be communicated through an alternative channel — a blinking LED pattern encoding the user code, an NFC tag readable by the installer's phone, or a setup page served by the device's local network interface. Second, the device operates unattended after initial authorization, so the refresh token lifetime must be long enough to survive between maintenance visits (typically 90-180 days).
For high-security edge deployments, the device flow can be combined with certificate-based device identity. The device presents a client certificate during the device authorization request, proving its hardware identity to the authorization server. The authorization server can then restrict which scopes are available to that device class: a monitoring sensor can request telemetry:write but not config:write, regardless of what the authorizing user approves.
What Security Considerations Are Unique to the Device Flow?
The device authorization flow introduces a security concern that other OAuth flows do not have: the remote phishing attack. An attacker initiates a device flow against the CDN's authorization server, receiving a legitimate device code and user code. The attacker then sends the user code to a target via email or chat: "Please authorize this device code for the CDN maintenance window." If the target visits the legitimate verification URL and enters the code, they authorize the attacker's session.
This attack succeeds because the verification URL is the real CDN authorization page — not a phishing site. The user's browser shows the legitimate domain with a valid TLS certificate. The defense is the authorization prompt itself: it must clearly display which application or device is requesting access, what scopes are requested, and a warning if the authorization was initiated from an unusual location or device type.
Additional security measures for CDN device flow implementations include short device code lifetimes (5-15 minutes, not hours), one-time-use device codes (the code is invalidated after the first successful or denied authorization), IP-based anomaly detection (flag when the polling device and the authorizing browser are in different geographic regions), and rate limiting on the device authorization endpoint (prevent device code farming).
The device authorization flow fills a critical gap in CDN authentication infrastructure. It enables secure, user-approved, scoped authentication for the growing ecosystem of CDN management tools and edge devices that operate outside the browser — without falling back to the insecure patterns of hardcoded API keys or shared credentials that have historically been the default for non-browser clients.