Device Flow for Input Constrained Devices

Device flow is useful for authorization flows on devices that do not support a web browser, or are input constrained. These include smart TVs, gaming consoles, printers, cars, and other IoT devices.

Imagine yourself trying to login to your favorite streaming app from your Smart TV. You have to enter your username and password to login to your streaming service.

Since the only supported input device is your TV’s remote control with arrow keys and an enter button, you need to navigate through the on-screen keyboard on the TV display with your remote control and find all the letters, numbers, and special characters needed to enter your login credentials.

If you make any mistakes, you will have to go through it all over again.

This is obviously not a pleasant user experience. It creates a lot of user friction that may end up turning away users instead of engaging them.

So, how can you authenticate into an input constrained device without having to compromise user experience and security? This is where the OAuth2 Device Flow comes into the picture.

Device flow is an extension to the OAuth 2.0 specification. It is designed to make it easy for users to authenticate using input constrained devices that don’t have an access to a browser or have limited input capabilities.

So, how does it work? Let’s see device flow in action.

OAuth 2.0 Device Flow with WSO2 Identity Server

For these next steps, we will be using WSO2 Identity Server 6.0 as our Identity Provider, and Apache Tomcat as the web server.

To use the device flow in our client app, first we need to enable the device flow grant type in the service provider configurations.

To do that, we will go to the Inbound Authentication Configuration and expand the OAuth/OpenID Connect Configuration.

There, we would enable the grant type, device_code and tick the checkbox to allow authentication without the client secret.

Click update to save the configurations.

Next, let’s head over to the client application we have configured to demonstrate how this works for end users.

This example shows a streaming app installed on a smart TV. You want to login to your account to access your favorite shows.

Let’s click on authorize.

Now, we can either scan the QR code displayed on the screen, or else type in the url to our mobile device web browser and go to the link.

When we go to the link, we enter the code displayed on the screen. If we scan the QR code from our mobile device, the code would automatically appear in the input field.

Let’s click on continue.

Now we are prompted for our username and password. Since we are accessing the authentication endpoint via our personal device, we can use any login assistance provided in the device, such as a password manager app to simplify the login experience.

After the authentication is successful, we are logged into our account.

As a user, we didn’t have to worry about mistyping passwords, or entering our account credentials to an untrusted device, such as a hotel room smart TV controller.

OAuth 2.0 Device Flow Internals

Now let’s take look at what’s happening under the hood. This diagram shows the basic steps in the device code flow. Let’s go through them one by one.

In the first step, the device client (Smart TV) will initiate the device flow with a device authorization request. In the Locast example, this happens when the user chooses the option, “Sign in with Code”. The client sends this request to the /device_authorization endpoint with the client ID.

Then the Authorization server responds with a device code, a user code, and a verification URI back to the device client. That’s the second step.

Now with this info at hand, the device client, the smart TV in our case, would display this verification URI and the user code to the user. The manner in which this info is presented is up to the device client to decide. They can simply display the verification URI or else, they can use a scannable QR code as Locast does.

At the same time where the device client displays this info to the user, it also starts to poll the /token endpoint of the Authorization Server asking for an access token. In this polling request, the device client would send the client ID and the device code. After receiving the token request, the Authorization Server will then validate if there’s an active user session for this client and return its status.

That’s our third step in the diagram.

While this client polling is happening, the user will continue the flow by accessing the URI and providing the user code. Here, the Authorization Server would authenticate the user if they don’t have a valid session. This would involve all the authentication steps that are enforced for this client in the Authorization Server. That’s our fourth and fifth steps.

And once the user is authenticated, the /token endpoint will send the correct response to the polling request that would include an access token (Optionally a refresh token and a ID token). That concludes our flow and now, the user would have connected their Locast account to his Smart TV.

Here’s the sequence diagram for the flow we just discussed.

Recap

As long as the device has the means to communicate over the internet and a method to present the URL and the code (like on the screen of a smart TV), device flow provides an effective solution without compromising the user experience and the security.

You can try integrating OAuth 2.0 Device Flow into your applications with WSO2 Identity Server now.

Thanks for reading!