Authorization Server Requirements

16.4

Supporting the Device Flow is not a huge amount of additional work for an authorization server. Here are a few things to keep in mind as you’re adding support for the Device Flow to an existing authorization server.

Device Code Request

The device will make a request to the authorization server to obtain the set of verification codes needed for the flow. The following parameters are part of the request.

  • client_id – Required, the client identifier as described in Client Registration.
  • scope – Optional, the scope of the request as described in Scope.

After validating the client ID and scopes, the authorization server returns the response with the verification URL, device code and user code. There are a few optional parameters that the authorization server can return in addition to the example given above.

  • device_code – Required, the verification code generated by the authorization server.
  • user_code – Required, the code the user will enter on the device screen, should be relatively short. Typically 6-8 numbers and letters are used.
  • verification_uri – Required, the URL on the authorization server that the user should visit to begin authorization. The user is expected to hand-enter this URL on their computer or mobile phone.
  • expires_in – Optional, the lifetime in seconds of the device code and user code.
  • interval – Optional, the minimum amount of time in seconds that the client should wait between polling requests to the token endpoint.

User Code

In many situations, the user’s nearest device will be their mobile phone. Typically these interfaces are more limited than a full computer keyboard, like how the iPhone requires an additional tap to change the key case or switch to numeric entry. To help reduce data entry errors, and to speed up entry of the code, the character set of the user code should take into account these limitations, such as using only capital letters.

A reasonable character set to use for the device code is case insensitive A-Z characters, without vowels so as to avoid accidentally spelling words. This results in the base-20 character set BCDFGHJKLMNPQRSTVWXZ. When comparing the entered code, it is best to ignore any characters such as punctuation that are not in the character set. An example code following this guideline with an entropy of 20^8 is BDWP-HQPK. The authorization server should compare the entered string case-insensitively ignoring punctuation, so should allow the following as a match: bdwphqpk.

Verification URL

The verification URL that the device will display should be as short as possible, and easy to remember. It will be displayed on potentially very small screens, and users will have to type it in manually on their computer or phone.

Note that the server should return a full URL including the URL scheme, although some devices may choose to trim that when displaying the URL. As such, the server should be configured to redirect http to https, and to serve on both the plain domain and with a www prefix in case the user mis-enters or the device omits that part of the URL.

Google’s authorization server is a great example of a short URL that is easy to enter. The response from the code request is https://www.google.com/device but all the device needs to display is google.com/device and Google will redirect appropriately.

Optimization for Non-Textual Interfaces

Clients without a display, or with a non-textual display, obviously have no way to show a URL to the user. As such, there are some additional methods that could be used to communicate the verification URL and user code to the user.

The device may be able to broadcast the verification URL via NFC, or Bluetooth, or even by displaying a QR code. In these cases, the device may include the user code as part of the verification URL using the parameter user_code. For example:

https://authorization-server.com/device?user_code=BDWP-HQPK

This way, when the user launches the URL, the user code can be pre-filled in the verification interface. It is recommended that the authorization server still require the user confirm the code rather than proceed automatically.

If the device has the ability to display the code, even if it cannot display a URL, then additional security is gained by prompting the user to confirm that the code on the verification interface matches the code displayed on their device. If that is not an option, then the authorization server can at least ask the user to confirm that they just requested to authorize a device.