OAuth 2.0 Device Authorization Grant

Today I would like to talk about the device flow, or the OAuth 2.0 Device Authorization Grant. You have probably used it more than once without knowing it. It’s a recent trend, as the device flow is great to support an ever-growing group of applications.

Internet-connected devices running applications are everywhere nowadays. Traditional examples are smart TVs, media consoles, digital picture frames and printers. Other examples are smart fridges, audio speakers and kiosk systems in stores.

These systems typically have two things in common. They are input constrained to the extent that requiring the user to input text in order to authenticate during the authorization flow is impractical, and many of them lack a browser to perform a user-agent-based authorization.

There are some device requirements:

• The device is already connected to the Internet.
• The device is able to make outbound HTTPS requests.
• The device is able to display or otherwise communicate a URI and code sequence to the user.
• The user has a secondary device (e.g., personal computer or smartphone) from which they can process the request.

Youtube Example

Let’s look at one common example in our lives. At home, most of us have a smart TV and want to stream something. In this example we want to stream video from YouTube. The first time you open YouTube, you need to authenticate with your username and password. The problem begins when you need to enter your password and you spend a lot of time swapping between different character sets on an on-screen keyboard, probably making a mistake in the process. I used YouTube as an example here, but these scenarios are everywhere.

That’s where the OAuth 2.0 device flow is useful.

Opening YouTube on an smart TV requires you to sign in with your YouTube account. However, instead of asking for a username and password, YouTube sends the user to the YouTube website with a unique code. This pairing screen asks the user to use this activation code to login with a phone or browser.

When a user opens this website on a phone or computer, the user is asked to authenticate with a username and password. The main difference is that the user is now authenticating in a regular browser. This means that the user can rely on stored passwords or password managers if desired.

After authentication, the user is asked to enter the pairing code.

After the pairing, the YouTube application on the smart TV is linked to the user’s account. This is a great user experience.

Device Authorization Flow

Now that we know what the device flow looks like from the user’s perspective, let’s dive into the details. The image below shows each of the steps in the device flow.

(A) — Once the user indicates they want to authenticate to the application (e.g., YouTube running on a smart TV), the client will initiate the flow. The client sends a request to the authorization server and includes the client identifier in the request’s body. If desired, the client can also add a scope.

(B) — If everything checks out, the authorization server issues a device code, an user code and provides the verification URI.

(C ) — The client instructs the user to open an user agent on another device and visit the provided verification URI, entering the user code in order to review the authorization request. The exact mechanism for displaying this data is up to the client. Typical examples are static text or a scannable QR code.

(D) — The authorization server authenticates the user (via the user agent), and prompts him to input the user code provided by the device client. The authorization server validates the code provided and prompts the user to accept or decline the request.

(E) — While the end user reviews the client’s request (step D), the client repeatedly polls the authorization server to find out if the user completed the user authorization step. The client includes the device code and its client identifier.

(F) — The authorization server validates the device code provided by the client and responds with the access token if the client is granted access, an error if they are denied access, or an indication that the client should continue to poll. In our YouTube example, the client can use the access token to retrieve the user’s music and start streaming audio.

Security Considerations

1. User Code Brute Forcing

Since the user code is typed by the user, shorter codes are more desirable for usability reasons. The user code should have enough entropy that, when combined with rate-limiting and other mitigations, a brute-force attack becomes infeasible.

2. Device Code Brute Forcing

As the device code is not visible to the user, a very high entropy code should be used.

3. Remote Phishing

Sometimes an attacker might send an email instructing the target user to visit the verification URL and enter the user code. To mitigate such an attack, it is recommended to inform the user that they are authorizing a device during the user-interaction step and to confirm that the device is in their possession.

4. Non-Confidential Clients

Device clients are generally incapable of maintaining the confidentiality of their credentials, as users in possession of the device can reverse-engineer it and extract the credentials. Therefore, unless additional measures are taken, they should be treated as public clients which are susceptible to impersonation.

5. Non-Visual Code Transmission

There is no requirement to always display the user code to the user. It is recommended that to use any chosen communication channel only be accessible by people in close proximity, for example, users who can see or hear the device.

Conclusion

In this article we talked about internet-connected devices that are input-constrained and lack a browser. We saw the challenges that these devices present to developers and customers alike, and how you can use the Device Flow to tackle those challenges.

The great advantage of the OAuth 2.0 Device Flow is that it lets you extend your existing authentication platform to smart device platforms. This flow allows users to authenticate and authorize applications running on one of this constrained devices, using a secondary device.