A Crash Course in the OAuth 2.0 Device Authorization Grant

Authorization for input-constrained devices

Connecting the unconnectable

Audience

This article is aimed at developers looking to understand authorising input-constrained devices such as consoles, TVs, picture frames, smart devices etc.

Readers will need a solid understanding of HTTP and the existing core OAuth standards. My other articles on the subject can be found collected in the list here.

We will provide an overview of the RFC found here. Any specific, missing implementation details can be found there.

Argument

If we are attempting to authorise a primary, input-constrained device, we will need access to a secondary device with easy input. An example might be authorising photo retrieval on a smart picture frame using our phone.

Our primary device will need the following:

1. A connection to the internet.
2. Capacity for outbound HTTPS requests.
3. Ability to communicate a URI to the user. This is how the user links the input-constrained and secondary devices, authorising the former with the latter.

Finally, our user will need access to their secondary, easy-input device.

One of the main perks of the device authorisation grant is that the device being authorised doesn’t need to accept HTTP requests, only make them — it works on a polling basis.

Basic device authorisation grant flow

The above is the basic flow for the grant.

1. The client on the device sends a request to the authorisation server for an access token along with the scopes it desires. Note, this uses a new endpoint, not the /authorise or /token endpoints.
2. The authorisation server returns a device code, user code and verification URI. Remember, the client Id is not just for the device, this is the role of the device code. Samsung will have a client Id it embeds on all TVs everywhere, however we need a specific device code for the specific TV we are logging in, such that we can identify it.
3. Now the device client polls the token endpoint on the authorisation server in order to get tokens. Note, the polling delay can be specified by the authorisation server and defaults to five seconds, there is also a slow_down component to communicate overloading to the client. It should only ever be commenced when manually prompted by the end user.
4. At the same time we need to communicate the necessary information to the end user such that they can authorise on their device. This is covered in the next section.
5. The user authenticates, then authorises the device.
6. Now the device is authorised, the next poll of the token endpoint will return the access and refresh tokens.

Getting the User to Authenticate and Authorise

The most complex bit of the whole grant is how we link the device we want to authorise to the work the end-user is doing to authorise it.

One way is using the verification URI and the user code. This is displayed to the user, the user visits the URI in the browser, types in the user code and now their browser authentication and authorisation is linked to the device.

Basic screen shown on a device containing instructions for what the user needs to do on their input-capable device.

We can also use the notion of verification_uri_complete, which includes the user code in the URI. This can then be converted into things like QR codes, so the user doesn’t need to type anything, just scan the QR code.

However, it’s noted that the user code should still be displayed so the user can double check they’re at the right place.

Adding non-textual instructions for the end-user

Remember, the authorisation server knows to link the user code to the device code, so the user never needs the device code.

Conclusion

That’s it! It’s pretty straightforward. Of course there’s more of the detail in the RFC here, but this is the crash course!