Page Comparison

...

...

...

...

Introduction

The device authorisation authorization grant is designed for Internet connected devices that either lack a browser to perform a user-agent based authorisation or authorization or are input constrained to the extent that requiring the user to input text in order to authenticate during the authorisation flow 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 standards https://tools.ietf.org/html/rfc8628

Device-Auth User flow

This section describes how device authorisation flow authorization flow can be achieved from a device. 

API Spec: User Authentication#/Device%20Authorization

Endpoint specifications:

...

User flow:

1. User Turn on device (e.g: STB) first time
2. User is prompted with a random 8 characters code (aka user_code)
3. User is prompted to go to a website to login (authenticate)
4. Once successfully authenticated, user will be asked to enter the user_code from step 2
5. User enter user_code and submit it
6a6. If user_code is valid => the device (in #1) will be successfully login => user can start streaming services entitled to his/her account.6b. If user_code is invalid => the device (in #1) will prompt user that login was failed => user won't be able to use any services.

Requesting a user_code:

When the user wants to log in, the device starts out by making a POST request to begin the process. The POST request contains only one piece of information, its client_id. This request is made to a /api/auth/v1/device endpoint that is unique to the Device Flow.

...

{
"device_code": "NGU4QWFiNjQ5YmQwNG3YTdmZMEyNzQ3YzQ1YSA",
"verification_uri": "https://example.com/device",
"user_code": "ABCD-1234ABCD1234",
"expires_in": 1800,
"interval": 5
}

...

• device_code - This is a long string that the device will use to eventually exchange for an access token.
• verification_uri - This is the URL the user needs to enter into their phone browser to start logging in.
• user_code - This is the text code the user will enter at the URL above,  it will be of 8 characters, upper case A-Z and numeric.
• expires_in - The number of seconds that this set of values is valid. After this amount of time, the device_code and user_code will expire and the device process will have to start over.
• interval - The number of seconds the device should wait between polling to see if the user has finished logging inauthentication.

Now the device needs to display the URL and User Code to the user.

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 

curl -X POST "https://testing.booxmedia.xyz/api/auth/v1/device/verify" -H "accept: */*" -H "Content-Type: application/json" -d "{\"user_code\":\"ABCD-1234\",\"user_id\":\"1234\"}"

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

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\”}”

...

{
  "errors": [
    {
      "id": "6de7da3e-8877-4f2b-a670-16e18e5d79a0",
      "status": "429",
      "code": "0",
      "title": "Too Many Requests",
      "detail": " - Slow Down"
    }
  ]
}

Once the verification is successful, the api/auth/v1/access_tokens endpoint will respond with access_token and refresh_token which can be used by the device for further use of services.

{
  "data": {
    "type": "AccessToken",
    "id": "9bc6871e-ce26-4b8a-96f6-e6688599d938",
    "attributes": {
      "login_timestamp": 1538126476,
      "user_id": "1234",
      "user_profile_id": "84eb61a9-75d4-42c7-8c15-84c3d7776227",
      "user_flags": [
        "TEST_FLAG1"
      ],
      "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJBbWlub01vdmUiLCJpYXQiOjE1Mzc1MjIxNzQsImV4cCI6MTUzODEyNjk3OSwiYXVkIjoid3d3LmJvb3h0di5maSIsInN1YiI6ImV4YW1wbGVfdXNlckBlbWFpbGRvbWFpbi5jb20iLCJwcm9maWxlX2lkIjoiNmM3Zjk0YWYtYjYwMy00ZjM5LTgzODQtZjEyMjI2ZWE5ZDRjNmM3Zjk0YWYtYjYwMy00ZjM5LTgzODQtZjEyMjI2ZWE5ZDRjIiwidHlwZSI6ImFjY2VzcyIsInN0Yl9zZXJpYWxfbm8iOiI2MTU1MDAyNjYxNjIifQ.RW6NdDE_kGgkOVKqodeT1fDdxU7Slaf551rp5ctBcFc",
      "expires_at_timestamp": 1538126476,
      "refresh_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJBbWlub01vdmUiLCJpYXQiOjE1Mzc1MjIxNzQsImV4cCI6MTU0NTk4OTM3OSwiYXVkIjoid3d3LmJvb3h0di5maSIsInN1YiI6ImV4YW1wbGVfdXNlckBlbWFpbGRvbWFpbi5jb20iLCJ0eXBlIjoicmVmcmVzaCJ9.9Pxzv0oGxjZmAIpZiH-aiue7LwAMcddPPHnaiOkpb-A"
    }
  }
}