Device Authorization

Device Authorization grant type

The Device Authorization grant type is designed specifically for applications which run on devices where displaying output to the user is easy but accepting user input is difficult (or impossible). An example of this is an application running on a Smart TV or other IoT device.

In this flow the user gets a code from the application and uses a browser (or app) on their computer or mobile phone to complete device authorization.

The application initiates this flow by calling the Device Endpoint of the OAuth Authorization Server. The Authorization Server returns two randomly-generated codes - a user_code and a device_code. These two codes both index the in-progress grant.

The application must now communicate the user_code to the end user. Usually it will be displayed as text but it could also be displayed within a QR code, printed out, or spoken. The application may also communicate the URL of its User Authorize Endpoint at the same time.

At this point the application will start a background process which polls the token endpoint of the Authorization Server attempting to exchange the device_code for an Access Token. Until the application is authorized, the Authorization Server will respond to this poll with an error.

The user must now authorize the application by authenticating directly to the user authorize endpoint of the Authorization Server and then submitting the user_code. The user_authorize endpoint is a browser endpoint and the method by which the end user is authenticated, and the user experience for user consent, are completely under the control of the Authorization Server.

When authentication and consent are complete, the Authorization Server uses the user_code to lookup the in-progress grant. It associates the authenticated user and marks the application as authorized.

The next time the application polls the token endpoint with the device_code, the Authorization Server will exchange the device_code for an Access Token.

💎

Jon Harry, IBM Security