Device Authentication

Device Authentication in Descope implements the OAuth 2.0 Device Authorization Grant (RFC 8628), enabling secure authentication for input-constrained devices like smart TVs, streaming devices, gaming consoles, and IoT devices. This method allows devices without keyboards or with limited input capabilities to securely obtain user authorization by letting users authenticate on a separate device with better input capabilities.

Overview

Device Authentication solves the challenge of authenticating users on devices that have limited input capabilities or lack a web browser. Instead of requiring users to enter credentials directly on the device, the flow redirects the authentication process to a secondary device (like a smartphone or computer) where users can easily complete the authentication process.

Common Use Cases

• Smart TVs and Streaming Devices: Netflix, YouTube, and other streaming apps
• Gaming Consoles: PlayStation, Xbox authentication flows
• IoT Devices: Smart home devices, industrial equipment
• Kiosks and Digital Signage: Public terminals with limited input
• Voice Assistants: Smart speakers and voice-controlled devices
• CLI Tools: Command-line applications and tools.

How Device Authentication Works

The Device Authentication flow involves several steps across two devices: the requesting device (with limited input) and the authorization device (user's phone/computer).

Technical Flow

Step 1. Request codes (device → Descope):

The device calls the Device Authorization endpoint to get a device_code, user_code, verification_uri (and verification_uri_complete), plus expires_in and a polling interval.

Step 2. Show the user what to do:

The device displays the user code and verification URL (or a QR code that encodes verification_uri_complete).

Step 3. User verifies & signs in:

On a phone/computer, the user opens the link. A Descope Flow confirms the user code and, if needed, authenticates the user (and collects consent) in one seamless step.

Step 4. Poll for completion (device):

The device polls the token endpoint with the device_code at the suggested interval until it receives success or a terminal error (authorization_pending, slow_down, access_denied, expired_token).

Step 5. Receive tokens & proceed:

On success, the token endpoint returns an access_token (and a id_token and refresh_token). The device stores these and calls protected APIs and resources with the access_token.

Implementation Walkthrough

Step 1: Device Code Request

The device initiates the flow by requesting a device code from Descope:

POST /oauth2/v1/device
Content-Type: application/x-www-form-urlencoded
 
client_id=YOUR_CLIENT_ID&scope=openid+profile+email

Step 2: Device Code Response

Descope responds with the necessary codes and URLs.

For example:

{
  "device_code": "GmRhmhcxhwAzkoEqiMEg_DnyEysNkuNhszIySk9eS", // The device verification code
  "user_code": "WDJB-MJHT", // The end-user verification code
  "verification_uri": "https://auth.example.com/device", // Your flow hosting URL
  "verification_uri_complete": "https://auth.example.com/device?user_code=WDJB-MJHT", // Verification URI including user code
  "expires_in": 1800, // Lifetime in seconds of device_code and user_code
  "interval": 5 // The minimum amount of time in seconds that the client should wait between polling requests to the token endpoint.
}

Step 3: User Code Display

The device displays the user code and instructions:

To authenticate this device:
1. Visit: https://auth.descope.com/device
2. Enter code: WDJB-MJHT

Step 4: User Authorization

The user visits the verification URL on their phone/computer, which launches a Descope Flow that handles:

1. User Code Confirmation: The user enters the displayed user code to link their session to the device
2. Authentication: The user completes authentication using any configured Descope authentication methods (password, social login, MFA, etc.)
3. Device Authentication Confirmation: The user confirms that they would like to authenticate the device.

Step 5: Token Polling

The device polls Descope for an access token:

POST /oauth2/v1/token
Content-Type: application/x-www-form-urlencoded
 
grant_type=urn:ietf:params:oauth:grant-type:device_code&
device_code=GmRhmhcxhwAzkoEqiMEg_DnyEysNkuNhszIySk9eS&
client_id=YOUR_CLIENT_ID

Step 6: Token Response

Once authorized, Descope returns a response including the following:

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "Bearer",
  "refresh_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6Il...",
  "id_token": "eyJhbGciOiJSUzI1NiIsImtpZCI6IlNL...",
  "expires_in": 3600,
  "scope": ""
}

Verification Flow

The verification flow consists minimally of the following steps:

1. Input Screen:

A screen for the user to input the user code. The input box should have the form.userCode context key. Can be auto-filled by including the user_code query parameter in the flow URL.

2. The Device Flow User Code Verification Action

Use this action to verify that the user code is correct.

3. User Authentication

Have the user authenticate using an authentication action or subflow.

4. Device authentication approval

We recommend confirming with the user that they would like to authenticate the device before using the mandatory Device Flow Approval Action.

5. Confirmation Screen

After the user has given approval, display a confirmation screen to indicate that the device authentication was successful.