OAuth 2.0 Device Authorization Grant
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:
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.
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.
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.
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
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
Request Parameter | Required/Optional | Description |
---|---|---|
| required | Must be the EmpowerID OAuth application client identifier. |
| required | A space-separated list of strings that the user consents to. Values include |
Authorization server responds with the following,
device_code
- For the client to track the processuser_code
- To present to the userverification_uri
- Where the user can authorize the request on another deviceverification_uri_complete
- Where the user can authorize the request on another device with embeddeduser_code
polling_interval
- Indicating how often the client should poll for token issuanceexpires_in
- Lifetime in seconds for theuser_code
anddevice_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
}
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 &code={The Device Code received in the Authorization Request}
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
Slow Down
Declined
Approved / Successful Response
Once the client receives the access token (and possibly a refresh token), it can use it to access the protected resources.
Browser Flow
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.”The EmpowerID authorization server redirects the user to the login.
Once successful, the device app is authorized to access APIs.