| name | oauth-device-code-flow |
| description | Authorized assessment of the OAuth 2.0 Device Authorization Grant (RFC 8628): device_code / user_code issuance, verification URI integrity, polling and rate limits, client binding, and token exchange abuse. Use when CLI tools, smart TVs, IoT, headless clients, or “enter the code at …” flows appear in scope for OAuth device login. |
OAuth Device Code Flow (Authorized Assessment)
Device Authorization Grant (urn:ietf:params:oauth:grant-type:device_code) only.
For browser redirect/state/nonce, use oauth-oidc-misconfiguration.
When To Use
| Situation | Direction |
|---|
| CLI/TV/IoT/headless shows user code + verification URL | This skill |
Traffic has device_authorization_endpoint, device_code, user_code, or device grant | This skill |
| Device-code phishing, polling abuse, unbound token issue | This skill |
| Broad OAuth redirect/state/nonce/mix-up | oauth-oidc-misconfiguration |
| RS JWT crypto / claim forgery only | api-auth-and-jwt-abuse |
Keywords: RFC 8628, device_code, user_code, verification_uri, verification_uri_complete, slow_down, authorization_pending, expired_token, access_denied.
Scope And Authorization
- Authorized apps and in-scope AS only. Do not attack third-party IdPs (Google, Microsoft, GitHub, etc.) outside explicit permission — test the client integration and any AS you own or the program names.
- Prefer test users/clients you control. Do not harvest real-user
user_code values from shared screens or production displays.
- Treat
device_code, user_code, and tokens as credentials: redact; store offline; rotate after production demos.
- Assessment only — not mass phishing or credential stuffing. Require accept/reject evidence. Hardening pairs with
code-quality-standards.
Workflow
1. Map the deployment
From discovery and traffic, record:
| Field | Capture |
|---|
| Roles | Device client, AS, verification UX, resource server |
| Endpoints | device_authorization_endpoint, token_endpoint, verify host |
| Client | client_id; public vs confidential; secret at token? |
| Codes | device_code entropy/TTL; user_code charset/length; expires_in |
| URIs | verification_uri, verification_uri_complete |
| Polling | interval; pending / slow_down / expired_token errors |
| Scopes | Requested vs granted; consent surface |
Baseline: device-auth → display code+URI → user approves on second device → poll token until approved/denied/expired.
2. Device authorization request integrity
- Issue legitimate device-auth; capture JSON (
device_code, user_code, verification_uri, expires_in, interval).
- Probe missing/invalid
client_id, over-broad scope, unexpected params.
- Confirm confidential clients authenticate at device-auth and/or token as required.
- Check whether unregistered
client_id values can mint codes.
POST /device_authorization HTTP/1.1
Host: as.example
Content-Type: application/x-www-form-urlencoded
client_id=<ID>&scope=openid%20profile
3. User code and verification URI
| Check | Secure expectation |
|---|
user_code entropy | Sufficient length/charset; not sequential |
| Rate limit on verify | Online brute-force throttled/locked |
verification_uri host | Stable HTTPS AS/branded — not attacker-influenced |
verification_uri_complete | TLS; no open redirect after login |
| Phishing surface | Client hardcodes/allowlists trusted verify host |
| Display channel | Codes not in analytics, crash dumps, world-readable logs |
Note if shoulder-surf of user_code alone completes consent unbound from the original device_code/client.
4. Polling and token endpoint
| # | Probe | Secure behavior |
|---|
| 1 | Poll before approve | authorization_pending (no tokens) |
| 2 | Faster than interval | slow_down/throttle; no tokens |
| 3 | After deny | access_denied; no tokens |
| 4 | After expires_in | expired_token; not reusable |
| 5 | Redeem code twice | Second fails |
| 6 | Swap code across client_ids | Fail (client binding) |
| 7 | Wrong/missing client auth | Fail for confidential clients |
| 8 | Parallel flood | Rate limit; no double refresh issue |
POST /token HTTP/1.1
Host: as.example
Content-Type: application/x-www-form-urlencoded
grant_type=urn:ietf:params:oauth:grant-type:device_code
&device_code=<DEVICE_CODE>&client_id=<ID>
High severity: tokens without consent; cross-client redeem; weak codes + no backoff enabling online guessing.
5. Consent and post-token
- Verify UX authenticates user and shows client + scopes before approve.
- Browser login CSRF/session issues on verify →
oauth-oidc-misconfiguration.
- Short access TTL; refresh rotation/revocation; device logout.
- JWT
alg/kid/aud on API → api-auth-and-jwt-abuse.
- Shared TV/kiosk refresh storage: impact for test accounts only.
6. Remediation
Via code-quality-standards: high-entropy one-time device_code; strong user_code + verify rate limits; client-allowlisted HTTPS verify host; enforce interval/slow_down; bind code to client_id (+ auth if confidential); clear consent; never log codes/tokens; RFC 8628 errors.
Routing
| Need | Skill |
|---|
| Broad OAuth/OIDC redirect, state, nonce, mix-up | oauth-oidc-misconfiguration |
Access/refresh JWT forgery, alg/kid/aud on RS | api-auth-and-jwt-abuse |
| Secure client/AS implementation standards | code-quality-standards |
Selection: device grant / user codes / verify URI / polling → this skill. Browser SSO → oauth-oidc-misconfiguration. API JWT after tokens → api-auth-and-jwt-abuse. Code fixes → code-quality-standards.
Output Checklist
