The OAuth 2.0 Device Code Flow is designed for devices that don’t have a web browser or cannot easily display a login interface. This flow allows users to authenticate on one device (such as a smartphone or computer) while granting access to an application running on another device (such as a smart TV, IoT device, or game console).

In this flow, the user manually navigates to a verification URL on a separate device (like a phone or computer), enters a provided code, and approves the application’s request for access. The client device, in the meantime, polls the authorization server at regular intervals to check if the user has granted access. Once the user authorizes the request, the client device receives an access token and can start interacting with protected resources.

The sequence for this flow is as follows:

1. Device Requests Authorization: The device or application makes a request to the authorization server and receives two codes: a device code (used internally by the device) and a user code (which the user must enter on a different device). It also gets a verification URL for the user to visit.

2. User Authorizes the Device: The user goes to the verification URL on their personal device, enters the user code, and logs in (if not already authenticated). This step links the user’s account to the device requesting access.

3. Polling for Access: While the user is authorizing, the device (or application) periodically checks the authorization server to see if the user has granted access using the device code.

4. Access Granted: Once the user completes the authorization process, the device receives an access token from the authorization server, allowing it to interact with protected resources.

Device Flow

1. Device initiates an authorization request to the EmpowerID Device Authorization Endpoint, https://<EID Server>/oauth/v2/device/authorize

   https://<EID Server>/oauth/v2/device/authorize
   ?client_id=xxxxxxxxxxxxxxxxxx
    &scope=openid

2. Authorization server responds with the following,

   1. device_code - For the client to track the process

   2. user_code- To present to the user

   3. verification_uri- Where the user can authorize the request on another device

   4. verification_uri_complete- Where the user can authorize the request on another device with embedded user_code

   5. polling_interval- Indicating how often the client should poll for token issuance

   6. expires_in - Lifetime in seconds for the user_codeand device_code

{
  "device_code": "<device_code>",
  "user_code": "<user_code>",
  "verification_uri": "https://example.com/device",
  "verification_uri_complete": "https://example.com/device?user_code=<user_code>",
  "expires_in": 1800,
  "interval": 5
}

3. The client device (app) periodically polls the token endpoint to check if the user has completed the authorization process. The client uses the device code to poll and the polling interval to prevent excessive requests.

   POST /oauth/v2/token HTTP/1.1
   Host: <EID Server>
   Content-Type: application/x-www-form-urlencoded
   Cache-Control: no-cache
   
   client_id={The Client ID of the OAuth app you registered in EmpowerID}
   &client_secret={The Client Secret of the OAuth app you registered in EmpowerID}
   &grant_type=device_code
   &device_code={The Device Code received in the Authorization Request}

4. The authorization server responds with either a pending status, an error (if the user has not authorized within the expiry time), or the access token (if the user successfully authorizes).
   Authorization Pending

   HTTP/1.1 400 BadRequest
   {
     "error": "authorization_pending",
     "error_description": "Authorization is currently pending. Please try again after a minimum interval of 5 seconds"
   }

Slow Down

HTTP/1.1 400 BadRequest
{
  "error": "slow_down",
  "error_description": "Interval between request is too short. Minimum interval is 5 seconds"
}

Declined

HTTP/1.1 400 BadRequest
{
  "error": "authorization_declined",
  "error_description": "Authorization was declined by the user"
}

Approved / Successful Response

{
    "access_token": "xxxxxxxxxxxxxxxxxxxxxx",
    "token_type": "Bearer",
    "expires_in": 3600,
    "refresh_token": "xxxxxxxxxxxxxxxxxxxxxx",
    "id_token": "xxxxxxxxxxxxxxxxxxxxxx",
    "id": "xxxxxxxxxxxxxxxxxxxxxx"
}

5. Once the client receives the access token (and possibly a refresh token), it can use it to access the protected resources.

Browser Flow

1. The client device (e.g., a smart TV) displays the user code and the verification URL to the user. The user is asked to visit the URL on a device with a browser (e.g., mobile or desktop) and enter the user code.
   Example Instruction:
   “Please visit https://example.com/device and enter the code ABCD1234 to authorize access.”

2. The EmpowerID authorization server redirects the user to the login.

3. Once successful, the device app is authorized to access APIs.