Device Authorization Flow
With input-constrained devices that connect to the internet, rather than authenticate the user directly, the device asks the user to go to a link on their computer or smartphone and authorize the device. This avoids a poor user experience for devices that do not have an easy way to enter text. To do this, device apps use the Device Authorization Flow (ratified in OAuth 2.0), in which they pass along their Client ID to initiate the authorization process and get a token.
How it works
The Device Authorization Flow contains two different paths; one occurs on the device requesting authorization and the other occurs in a browser. The browser flow path, wherein a device code is bound to the session in the browser, occurs in parallel to part of the device flow path.
- The user starts the app on the device.
- The device app requests authorization from the Auth0 Authorization Server using its Client ID (/oauth/device/code endpoint).
- The Auth0 Authorization Server responds with a
expires_in(lifetime in seconds for
user_code), and polling
- The device app asks the user to activate using their computer or smartphone. The app may accomplish this by:
- asking the user to visit the
verification_uriand enter the
user_codeafter displaying these values on-screen
- asking the user to interact with either a QR Code or shortened URL with embedded user code generated from the
- directly navigating to the verification page with embedded user code using
verification_uri_complete, if running natively on a browser-based device
- asking the user to visit the
- The device app begins polling your Auth0 Authorization Server for an Access Token (/oauth/token endpoint) using the time period specified by
intervaland counting from receipt of the last polling request's response. The device app continues polling until either the user completes the browser flow path or the user code expires.
- When the user successfully completes the browser flow path, your Auth0 Authorization Server responds with an Access Token (and optionally, a Refresh Token). The device app should now forget its
device_codebecause it will expire.
- Your device app can use the Access Token to call an API to access information about the user.
- The API responds with requested data.
- The user visits the
verification_urion their computer, enters the
user_codeand confirms that the device that is being activated is displaying the
user_code. If the user visits the
verification_uri_completeby any other mechanism (such as by scanning a QR code), only the device confirmation will be needed.
- Your Auth0 Authorization Server redirects the user to the login and consent prompt, if needed.
- The user authenticates using one of the configured login options and may see a consent page asking to authorize the device app.
- Your device app is authorized to access the API.
How to implement it
The easiest way to implement the Device Authorization Flow is to follow our tutorial: Call API Using Device Authorization Flow.
To force the user to reauthorize a device, you must revoke the Refresh Token assigned to the device. To learn how, see Unlink Devices from Users. Note that the device will not be forced to reauthorize until the current Access Token expires and the application tries to use the revoked Refresh Token.