Device flow, explained

Host0:00You have signed in to an app on a smart TV, or a streaming stick, or a game console. Think about what that device can actually do. It has no browser worth the name, no keyboard you would wish on anyone, maybe five buttons on a remote. And yet you sign in, securely, in under a minute.

Host0:18The trick is that the TV never touches your password. It asks someone else to. The device turns to you and says: I cannot log in - so go, on a device that can, and vouch for me. That is the device authorization grant, RFC 8628, and it is one of the strangest and best designs in OAuth, because it splits one sign-in across two devices and two channels, on purpose.

Host0:41When you pick sign-in, the device makes one request over the network to the authorization server, and gets back two codes and one address.

Host0:50The first code is short and human-sized: four to eight characters, letters and digits, no ambiguous pairs. That is the user code, and it is built for you to type on a phone keyboard or read off a TV screen from across the room. The second code is long and machine-sized. That is the device code, and it never leaves the device. It is the device's own secret - its claim ticket for polling. And there is an address: the verification URL where you, the human, are supposed to go.

Host1:21Now the two channels are in play. The front channel is you and your phone: open the URL, sign in, type the short code, see what the device is asking for, approve. The back channel is the device, sitting patiently, asking the server over and over: has my human come back yet? Has my human approved?

Host1:43That asking is the poll loop, and it has rules worth knowing, because they are the parts everyone gets subtly wrong.

Host1:51The device does not hammer the server. The first response told it an interval - poll no faster than every five seconds. Poll too early and the server answers with one specific error meaning slow down - and the correct client behavior is to add five seconds to its interval and keep going, not to back off and give up. It sounds trivial. Real implementations have failed this exact check, polling on a fixed timer and tripping the rule the moment the server increases the interval.

Host2:19The codes also expire, fast - on purpose, usually within about fifteen minutes. If you never get around to approving, the device's claim ticket simply dies, and it has to start over. And if someone starts guessing user codes - typing combinations at the verification URL hoping to hit one - the server locks that down: too many wrong guesses and the code is dead. That lockout is why user codes can stay short enough for a human to type.

Host2:48Meanwhile, on your phone, you have signed in - properly, with whatever strong method that service uses - and you are looking at a confirmation screen. This is the moment the whole design exists for. The screen should tell you what device is asking, from where, for what. You confirm, the server marks the device code as approved, and on its very next poll - five seconds later at most - the device finally gets what it wanted: the access token and refresh token. The TV starts playing. Your password never touched it.

Host3:18Notice what was learned: the device's network never saw your credentials, your phone's session never touched the device, and the two codes never travel together. The short one rides the front channel, the long one stays on the back channel, and they only meet inside the authorization server.

Host3:36Now the dark version of the same design. Everything you just heard works just as well for an attacker.

Host3:43Someone emails you, or texts you: complete your sign-in, verify your account, urgent. You tap the link - a real page, a real verification URL, maybe even a real code prefilled - and you approve what looks like a routine request. Except the device that is polling on the other end is not your TV. It is an attacker's laptop, and your approval just handed their device a token. This is device-code phishing, and it is a documented, actively used attack - the remote phish got its own grant.

Host4:14The defenses are the same confirmation screen you barely read. Where is the device asking? A city you have never heard of is the tell. What is it asking for? Read it. Short code lifetimes cap how long a phished code stays alive. And the reflex that beats the attack: if you were not just setting up a device yourself, there is nothing to approve - an approval prompt that arrives uninvited is not a login step, it is the attack.

Host4:42The device console on this site runs the entire grant in your browser, and you play both ends. The TV shows the code, your phone approves, the device polls - with the real slow down rule, real expiry, brute-force lockout, and a scenario that plays the phishing twist from the attacker's side, so you can watch exactly how a helpful confirmation screen turns into a heist. Five minutes there will teach you more about this flow than any diagram.