The OAuth device flow explained, and how it can be used to solve the problem of obtaining access tokens on devices where the user has limited possibilities to enter their credentials.

OAuth Device Flow

On this page

The OAuth 2.0 Device Authorization Grant (aka Device Flow) is an extension to the original OAuth 2.0 spec. It solves the problem of obtaining access tokens on devices where the user has limited possibilities to enter their credentials.

OAuth Device Flow Example

A typical example is to login to an app on a TV or set-top box. The device (TV) will start a flow, but then when it's time for user authentication and authorization it will show a code or QR code that the user will enter on a computer or a mobile device where it's easier to authenticate. Once authentication is done, the user is presented with a consent screen, where it can authorize the device to access its account.

This makes the flow different from other OAuth flows. There is an out-of-band component, when the user authenticates, and the device is waiting, polling the OAuth server to see if the authorization is complete.

In the Curity Identity Server the device client needs to be a dynamically registered client.

Dynamic Client

The Device Client needs to be a dynamically registered client. It is not possible to perform a device flow with a static (configured) client.

Device Verification Endpoint

To start off the flow the device requests a new authorization from the device verification endpoint.

Device Flow First Part: Device Verification Endpoint
  1. The Device requests a new grant from the Device Verification Endpoint
  2. The server responds with a code to present to the user along with a url for the user to authenticate. A device code is also issued for the device to poll the status of the grant.

In step two the Token Service also responds with a poll interval instructs the device on how often to check back in for the result.

A URL and a Alphanumeric code is returned that should be presented to the user. The user needs to visit the URL and enter the code in order to authorize access for the device.

The result also may contain a QR code that the device can present to the user. This contains the URL to visit and the code to enter.

User Authentication and Device Authorization

The user uses another device (mobile or browser) to visit the URL presented.

Device Flow Second Part: User Authentication and Device Authorization
  1. The user visits the URL
  2. The Token Service redirects to the Authentication Service for user authentication (SSO may occur)
  3. Once Authentication is done the Authentication Service redirects back to the Token Service
  4. The user is presented with a consent and once approved the user flow is complete. User can close browser.

Token Endpoint

Device Flow Third Part: Token Endpoint
  1. The Device polls the Token Service's Token Endpoint using the device code issued in the first flow.
  2. Once the user has approved the grant, the Token Service returns an Access Token and a Refresh Token (if so configured).

While waiting for the user approval, the Token Endpoint will respond with a 400 with the error authorization_pending. This means wait and try again after the defined poll interval.

Device Verification Endpoint Request

  • Method: POST
  • Content-Type: application/x-www-form-urlencoded
  • Response Type: application/json

Request Parameters

ParameterValueMandatoryDescription
client_idThe Client IDyesThe ID of the requesting client
client_secretThe client secretyes*The secret of the client. *Mandatory if client authentication is of type secret, and the authentication is not done using basic authentication
scopeSpace separated string of scopesnoList the scopes the client is requesting access to.

Response

  • Response Type: application/json
ParameterValueMandatoryDescription
user_codealphanumericyesThe code to present to the user, that the user needs to enter out of band
verification_urlURLyesThe URL the user should visit to enter the user_code and authenticate
verification_url_completeURInoThe verification_url with the user_code added as query for shorthand access
device_codestringyesThe code the device should use to poll and retrieve tokens from the token endpoint
qr_codedata urlnoAn image as data url to present, contains the verification_url_complete encoded
intervalintegernoThe polling interval the device should respect when waiting for user approval
expires_inintegeryesThe time is seconds the device_code and user_code is valid for

Token Endpoint Request

  • Method: POST
  • Content-Type: application/x-www-form-urlencoded
  • Response Type: application/json

Request Parameters

ParameterValueMandatoryDescription
client_idThe Client IDyesThe ID of the requesting client
client_secretThe client secretyes*The secret of the client. *Mandatory if client authentication is of type secret, and the authentication is not done using basic authentication
grant_typeurn:ietf:params:oauth:grant-type:device_codeyesDefines the flow type: device flow
device_codestringyesThe device code from the Device Verification Endpoint Request

Response

  • Response Type: application/json
ParameterValueMandatoryDescription
access_tokenA newly issued access tokenyesThe resulting access token for the flow
refresh_tokenA newly issued refresh tokennoOnly issued if the client is configured to receive refresh tokens
expires_inExpiration in secondsyesThe time to live of the access token in seconds
scopeSpace separated stringnoIf not present the requested scopes where issued. If present the issued scopes may differ from the requested scopes.
token_typeBearer or other token typeyesDescribes how the token can be used. Most commonly Bearer token usage.

If the user authorization is not complete the response will look as follows:

Pending Response

  • Response Type: application/json
  • Status Code: 400
ParameterValueMandatoryDescription
errorauthorization_pendingyesThe authorization is not yet complete. Wait for interval time and try again`
error_descriptionhuman readable stringnoA more detailed description of the state

Other errors in the response should cause the device to abort polling and ask the user to restart the flow.

Photo of Jacob Ideskog

Jacob Ideskog

Identity Specialist and CTO at Curity

Join our Newsletter

Get the latest on identity management, API Security and authentication straight to your inbox.

Start Free Trial

Try the Curity Identity Server for Free. Get up and running in 10 minutes.

Start Free Trial