We launched new developer portal. For the latest documentation visit developer.cloudentity.com

OAuth 2.0 Device Authorization Grant (Flow)

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

Device Flow Overview

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 the those devices usually lack suitable browsers, or their input capabilities are very limited, for the conveniance 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 the 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.

Granting Authorization Using Device Flow

[mermaid-begin]
sequenceDiagram autoNumber participant Device participant acp as Authorization Server (Cloudentity) participant user as User participant ua as User Agent on Secondary Device Device->>acp: POST /device/authorization note over Device, acp: The request contains device's client identifier acp->>Device: Device code & user code & verification URI par User Workflow Device->>user: Display user code & verification URI note over Device, user: Devices very often provide a QR code the users can scan for conveniance reasons user->>ua: verification URI acp->>user: Prompt user to provide the user code user->>acp: Enter user code acp->>acp: Verify user code ua->>user: Redirect user to login screen user->>acp: Authenticate acp->>user: Prompt the user to accept or decline the request user->>acp: Review authorization and accept the request acp->>user: Notify the user that the device was connected note over acp, user: For example, a "Device connected" page can be displayed in the user agent and Device polling the authorization server note over Device, acp: As soons as the user is displayed the device code
and the verification URI (step 3),
the device begins to poll authorization server's token endpoint note over Device, acp: When polling,
the device must respect the interval defined by the authorization server Device->>acp: GET /token with device code & client identifier acp->>Device: Access token opt acp->>Device: ID/Refresh token end end
  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, ACP recommends limiting the scopes only to the necessary ones.

  2. The authorization server issues a device code and an 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 an 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.