Skip to main content

OAuth 2.0 Device Flow

Paige Freeman
  • Updated

OAuth 2.0 Device Flow is used to log in to a device using OAuth when the device doesn’t have a browser, or also when the device has limited keyboard input ability.

The OAuth 2.0 Device Flow works quite different from the other OAuth flows, since it doesn’t involve a browser redirect on the device.

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. (Devices like these are considered “public clients”, so no client_secret is used in them, similar to mobile apps.) This request is made to a new endpoint that is unique to the Device Flow.

POST https://${yourIDPDomain}/${OrganizationTenant}/connect/ deviceauthorization?client_id={CLIENT_ID}

The server will respond with a JSON document with a few pieces of information.

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

Here’s what the properties in the response mean:

  • 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 to start logging in

  • user_code - This is the text the user will enter at the URL above

  • 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 will have to start over

  • interval - The number of seconds the device should wait between polling to see if the user has finished logging in

Now the device needs to display the URL and User Code to the user somehow. 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 token endpoint, using a grant type of device_code.

POST https://${yourIDPDomain}/${OrganizationTenant}/connect/token?grant_type=urn:ietf:params:oauth:grant-type:device_code&client_id=CLIENT_ID&device_code=NGU4QWFiNjQ5YmQwNG3YTdmZMEyNzQ3YzQ1YSA

While the user is busy logging in on their phone, the token endpoint will return the error message below:

{  "error": "authorization_pending"}

The authorization_pending error means the user isn’t finished logging in, but the code hasn’t yet expired either. The device should try this again after the specified number of seconds. Meanwhile the user will be logging in, choosing an account, and approving the request.

Finally, when the user finishes logging in, their phone will give them a “success” message, and there isn’t anything left to do on the phone.

The next time the device makes the POST request to the token endpoint, it will get back an access token!

{  "access_token": "MsQ50jbzRn43NzqNLgV3Ia",  "expires_in": 3600,  "refresh_token": "b7aab34e37298a160e0ede5b43ed1f70a8"}

The flow is complete, and the device can proceed to use the access token with the API!