OAuth 2.0 Device Authorization Grant

The OAuth 2.0 Device Code Flow enables authentication for devices without browsers or input capabilities. 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).

The user navigates to a verification URL on a secondary device, enters a provided code, and approves the application's access request. Meanwhile, the client device 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 access protected resources.

Device Authorization Flow

Flow Steps

1. Device Requests Authorization - Device requests device and user codes from authorization server, receiving a device code (for internal tracking), user code (for user entry), and verification URL
2. User Authorizes Device - User navigates to verification URL on secondary device, enters user code, and authenticates to link their account to the requesting device
3. Device Polls for Access - Device periodically checks authorization server using the device code to determine if user has granted access
4. Access Granted - After user completes authorization, device receives access token from authorization server

Device Flow

1. Send authorization request to https://<EID Server>/oauth/v2/device/authorize

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

Request Parameter	Required/Optional	Description
client_id	required	EmpowerID OAuth application client identifier
scope	required	Space-separated permission list. Include openid for OpenID Connect.

2. Authorization server responds with device authorization details:

{
  "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
}

Response Parameter	Description
device_code	Code for client to track the authorization process
user_code	Short code presented to user for entry on secondary device
verification_uri	URL where user authorizes the request on another device
verification_uri_complete	URL where user authorizes the request with embedded user code
expires_in	Lifetime in seconds for the user code and device code
interval	Minimum seconds between polling requests

3. Device polls the token endpoint periodically. Use the device code to poll and respect 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
&code={The Device Code received in the Authorization Request}

4. 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

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

Slow Down

{
  "error": "slow_down",
  "error_description": "Interval between request is too short. Minimum interval is 5 seconds"
}

Declined

{
  "error": "authorization_declined",
  "error_description": "Authorization was declined by the user"
}

Approved

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

5. After receiving the access token and refresh token, use them to access protected resources.

Browser Flow

1. Client device (e.g., smart TV) displays the user code and verification URL to the user.

Please visit https://example.com/device
Enter code: ABCD1234

2. User visits the URL on a device with a browser (e.g., mobile or desktop) and enters the user code.

3. Authorization server redirects the user to login.

4. After successful authentication, the device application is authorized to access APIs.