Device Flow

The Device Flow enables OAuth on devices that have an Internet connection but do not have a web browser or an easy way to enter an email address and password.

In this flow, the device instructs the user to open a URL on a secondary device such as a smartphone or computer in order to complete the authorization. Initially, Simplestream will support entering the device code via the website; but eventually, entering the device code into the iOS or Android mobile apps will be supported.

Documentation for Device Flow is available on the OAuth 2.0 website:

https://www.oauth.com/oauth2-servers/device-flow/

As Laravel Passport does not currently support Device Flow, support has been added via a proxy as described here:

https://developer.okta.com/blog/2019/02/19/add-oauth-device-flow-to-any-server

The Device Flow requires the client to make two API calls:

  1. Get Code - retreive an 8 character alphanumeric code to display to the user
  2. Verify Code - submit the code to the OAuth server for verification
To test the Device Flow, follow the steps below:
Step 01 - Get A Device Code

Step one is to make an API call to the /device/code endpoint to retreive a unique code to display to the user.

Step 02 - Display Device Code To User

Step two is to display the "user_code" to the user and ask them to visit the "verification_url" to register their device:

Sign In

To sign in on your computer or smart phone, go to:

[verification_url]

When prompted, enter the following code:

[code]

Click the button below to open the website in a new window where you can enter the code:

Open Website
Step 03 - Check If User Registered Device Code

Step three is to poll the /device/register endpoint to check if the user has entered the code. The polling interval should be the "interval" value returned by the API call in Step 01, in seconds.

Complete - Access Token Obtained

An access token has been obtained!

The Access Token can be submitted to the /api/auth/user endpoint to obtain the user's profile, including their ID.