2026-09-26 · 8 min read
- oauth
- device-flow
- security
The OAuth device authorization grant serves devices that cannot host a practical browser or accept a redirect. The device requests authorization details, presents a verification URI and user code, and polls the token endpoint while the user authorizes on a separate device.
The flow separates possession of a device code from user authentication, but both the client and authorization server must resist phishing, code guessing, excessive polling, replay, and accidental disclosure.
Establish trusted endpoints and client policy
Obtain the device authorization and token endpoints from trusted issuer configuration. Register the client according to its ability to protect credentials, define allowed scopes and audiences, and keep production and test issuers separate.
- Never choose endpoints from an untrusted response.
- Use TLS and normal server identity validation.
- Request the minimum authorization required.
- Apply rate limits by client, device, and network risk.
Design a verification experience users can trust
Display the verification domain clearly, use a human-readable user code, and explain what account and device are being linked before consent. A verification URI complete can improve usability, but the authorization server should still show and confirm the user code to reduce cross-device phishing.
Do not show the device code, token endpoint, or raw protocol response. QR codes should encode only a provider-approved verification URL and must have a readable URL fallback.
Implement one polling state machine
Respect the returned interval from the first request onward. Continue while authorization is pending, increase delay when slow_down is returned, stop on denial or expiry, and distinguish protocol responses from transient transport errors.
Ensure only one worker polls a device code. Bound network retries, honor cancellation, persist only the minimum state needed for a process restart, and never restart an expired authorization silently.
Protect codes, tokens, and telemetry
Treat device codes, access tokens, refresh tokens, and user codes as secrets during their useful lifetime. Keep them out of URLs where not specified, analytics, crash reports, console logs, screenshots, and support tickets.
Record privacy-safe attempt identifiers, states, durations, response classes, and rate-limit events. After success, store tokens using platform protections, validate issuer and audience as appropriate, rotate refresh tokens when supported, and clear polling state.
Test clocks, cancellation, and abuse
Use Flashman's URL parser for harmless provider fixtures, JSON formatter for sanitized protocol messages, JWT decoder for synthetic token structure, timestamp converter for interval and expiry cases, and QR generator for non-production UX tests.
Cover pending, approval, denial, slow_down, expiry, malformed responses, network loss, clock adjustment, process restart, duplicate workers, cancellation, code guessing limits, phishing-resistant confirmation, issuer mix-ups, token rotation, revocation, and secret-safe logs.