Skip to main content

OAuth 2.0 Device Authorization Grant (Flow)

Get familiar with the OAuth 2.0 Device Authorization Grant (formerly known as Device Flow).

What Device Flow Is

Device Authorization Grant is an extension to the OAuth 2.0 framework. It enables browserless devices or devices with limited input capabilities to obtain access tokens. Such devices include smart TVs, gaming consoles, but also printers, scanners, and more. Since most of those devices usually lack suitable browsers, or their input capabilities are very limited, for the convenience of users and improved security, the Device Flow enables the users to review the authorization and provide their consent on a secondary device. The device used for authorization must have both the input capabilities and a suitable browser.

Remember

The Device Flow should not be used to replace browser-based OAuth authorization in native applications on devices that are capable with delivering the right user experience and security level. Such devices include, for example, smartphones or tablets. Native applications should use authorization measures as defined in the RFC8252.

Requirements for Device Flow

To be able to use the Device Flow, devices must be:

  • Already connected to the Internet

  • Able to make outbound HTTPS requests

  • Able to display or communicate a URI and a code sequence to the user

The users must have a secondary device like personal computer or smartphone that is capable of displaying consent data to the user and enable them to process the request.

How Device Flow Works

Device_Flow.svg

  1. The device (its client application) initiates the authorization flow by requesting a set of verification codes from the authorization server.

    An HTTP POST request is sent to the authorization server's device authorization endpoint. It includes:

    • client_id request body parameter that corresponds to the client identifier the authorization server issued for the registered client application (device).

    • scope request body parameter (optional) that defines the scope of the access request as defined in the RFC6749.

    Security recommendation

    For improved security, SecureAuth recommends limiting the scopes only to the necessary ones.

  2. The authorization server issues a device code and user code and provides the end-user verification URI.

  3. The device (client application) instructs the end user to use their secondary device and its user agent (browser) and visit the provided end-user verification URI. The client application also provides the user with the user code to enter in the user agent in order to review the authorization request.

  4. The user enters the verification URI in the user agent on a secondary device or scans the provided QR code.

  5. The authorization server prompts the user to enter the user code the end user got in the third step.

  6. The user enters the user code it got from the primary device using the secondary device's user agent.

  7. The authorization server validates the code.

  8. The user is redirected to their login screen.

  9. The authorization server authenticates the user via their user agent.

  10. The authorization server prompts the user to either accept or decline the device's request for consent.

  11. The user reviews the authorization and either accepts or declines the consent.

  12. In pararell to end user reviewing the authorization request, the device repeatedly polls the authorization server's /token endpoint to find out if the user completed the authorization step.

    Polling interval

    The authorization server may provide a specific polling interval which is the minimum amount of time (in seconds) that client application should wait between its polling requests to the /token endpoint.

    If the authorization server does not specify a polling interval, all client applications must use 5 seconds as the default value.

    The request to the /token endpoint contains the following required parameters connected to the Device Flow itself:

    • device_code with the value set to the device code the client got in the second step

    • grant_type set to urn:ietf:params:oauth:grant-type:device_code

    • client_id that corresponds to the client identifier the authorization server issued for the registered client application (device).

    The request must also contain all parameters required by the chosen client authentication method.

  13. The authorization server validates the device code provided by the client application and if the user accepted the authorization request, the server responds with an access token.

    If the user does not authorize the device's request, the authorization server denies the request to the /token endpoint.

  14. Optionally, the authorization server may also issue a refresh token in addition to the access token.

In this section: