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.
- The Device requests a new grant from the Device Verification Endpoint
- 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.
- The user visits the URL
- The Token Service redirects to the Authentication Service for user authentication (SSO may occur)
- Once Authentication is done the Authentication Service redirects back to the Token Service
- The user is presented with a consent and once approved the user flow is complete. User can close browser.
Token Endpoint
- The Device polls the Token Service's Token Endpoint using the device code issued in the first flow.
- 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
| Parameter | Value | Mandatory | Description |
|---|---|---|---|
| client_id | The Client ID | yes | The ID of the requesting client |
| client_secret | The client secret | yes* | The secret of the client. *Mandatory if client authentication is of type secret, and the authentication is not done using basic authentication |
| scope | Space separated string of scopes | no | List the scopes the client is requesting access to. |
Response
- Response Type:
application/json
| Parameter | Value | Mandatory | Description |
|---|---|---|---|
| user_code | alphanumeric | yes | The code to present to the user, that the user needs to enter out of band |
| verification_url | URL | yes | The URL the user should visit to enter the user_code and authenticate |
| verification_url_complete | URI | no | The verification_url with the user_code added as query for shorthand access |
| device_code | string | yes | The code the device should use to poll and retrieve tokens from the token endpoint |
| qr_code | data url | no | An image as data url to present, contains the verification_url_complete encoded |
| interval | integer | no | The polling interval the device should respect when waiting for user approval |
| expires_in | integer | yes | The 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
| Parameter | Value | Mandatory | Description |
|---|---|---|---|
| client_id | The Client ID | yes | The ID of the requesting client |
| client_secret | The client secret | yes* | The secret of the client. *Mandatory if client authentication is of type secret, and the authentication is not done using basic authentication |
| grant_type | urn:ietf:params:oauth:grant-type:device_code | yes | Defines the flow type: device flow |
| device_code | string | yes | The device code from the Device Verification Endpoint Request |
Response
- Response Type:
application/json
| Parameter | Value | Mandatory | Description |
|---|---|---|---|
| access_token | A newly issued access token | yes | The resulting access token for the flow |
| refresh_token | A newly issued refresh token | no | Only issued if the client is configured to receive refresh tokens |
| expires_in | Expiration in seconds | yes | The time to live of the access token in seconds |
| scope | Space separated string | no | If not present the requested scopes where issued. If present the issued scopes may differ from the requested scopes. |
| token_type | Bearer or other token type | yes | Describes 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
| Parameter | Value | Mandatory | Description |
|---|---|---|---|
| error | authorization_pending | yes | The authorization is not yet complete. Wait for interval time and try again` |
| error_description | human readable string | no | A 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.
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
