Introduction
The device authorization grant is designed for Internet connected devices that either lack a browser to perform a user-agent based authorization or are input constrained to the extent that requiring the user to input text in order to authenticate during the authorization flow is impractical. It enables clients on such devices (like smart TVs, media consoles, digital picture frames, and printers) to obtain user authorisation to access protected resources by using a user agent on a separate device.
Implementation follows OAuth 2.0 Device Authorization Grant https://tools.ietf.org/html/rfc8628
Device-Auth User flow
This section describes how device authorization flow can be achieved from a device.
...
| Endpoint | HTTP Method | Purpose |
|---|---|---|
| /api/auth/v1/device | POST | Creates unique user code and a verification URI to present it on a external browser to verify the user. |
| /api/auth/v1/device/verify | POST | Verifies the user code with the authenticated user. |
| /api/auth/v1/access_token grant_type="urn:ietf:params:oauth:grant-type:device_code" | POST | Provides access_token to the device once the user is verified externally. |
...
Now the device needs to display the URL and User Code to the user.
| Info |
|---|
UI is free to add spaces or dashes to the user code in order to make it easier to read and enter into the secondary device, as long as all such characters are stripped from the input when they send it back to us. |
Verification:
User logs in with regular authentication mechanism to the service from mobile phone/browser, then enters the verification_uri provided by the device endpoint, a POST request is made to /api/auth/v1/device/verify endpoint to verify the user. See: User Authentication#/Device%20Authorization/verifyUserCode
...
While the device waits for the user to enter the code and log in, it will make a POST request every 5 seconds as specified by the interval returned. This POST request will be made to the /api/auth/v1/access_tokenendpoint, using a grant type of urn:ietf:params:oauth:grant-type:device_code
| Code Block |
|---|
curl -X POST "https://testing.booxmedia.xyz/api/auth/v1/access_tokens" -H "accept: application/vnd.api+json" -H "Content-Type: application/json" -d "{\"grant_type\":\"urn:ietf:params:oauth:grant-type:device_code
\",\"credentials\”:{\”client_id\”:\”1234xyz”, \”device_code\”:\”NGU4QWFiNjQ5YmQwNG3YTdmZMEyNzQ3YzQ1YSA
”},\”login_user_profile\":\"84eb61a9-75d4-42c7-8c15-84c3d7776227\”}” |
...