This article explains RFC 8628 (OAuth 2.0 Device Authorization Grant), a.k.a. “Device Flow”.
Device Flow is another way to issue an access token as well as the flows defined in RFC 6749 (The OAuth 2.0 Authorization Framework).
The reason for developing the new flow is described at the top of the specification as follows.
The OAuth 2.0 device authorization grant is designed for Internet-connected devices that either lack a browser to perform a user-agent-based authorization or are input constrained to the extent that requiring the user to input text in order to authenticate during the authorization flow is impractical.
Let’s start learning the device flow.
1. Device Flow
(1) There is a device. A typical example is a smart TV. A client application runs on the device.
(2) Prepare an authorization server.
(3) An authorization server that supports the device flow has a device authorization endpoint.
(4) A client application sends a request to the endpoint.
The specification about the request is described in “3.1. Device Authorization Request”. Request parameters are as follows.
client_id— Required. Client ID.
scope— Optional. Scopes.
The following is an example of the device authorization request shown in the specification.
POST /device_authorization HTTP/1.1
(5) The endpoint returns a response.
The specification about the response is described in “3.2. Device Authorization Response”. Response parameters are as follows.
device_code— Required. Device code (device verification code).
user_code— Required. User code (end-user verification code).
verification_uri— Required. End-user verification URI.
verification_uri_complete— Optional. End-user verification URI including a user code.
expires_in— Required. Lifetime in seconds of the device code and the user code.
interval— Optional. The minimum amount of time in seconds between polling requests to the token endpoint.
The following is an example of the device authorization response shown in the specification.
HTTP/1.1 200 OK
It should be noted that a user code (end-user verification code) and a device code (device verification code) are issued. They will be used in a request to an end-user verification endpoint and a token request, which will be explained later.
(6) The client application displays the values of
user_code which are contained in the device authorization response.
(7) For end-users’ convenience, typical implementations additionally show a QR code that represents the value of
verification_uri_complete if one is included in the device authorization response.
verification_uri represents the URI of the end-user verification endpoint of the authorization server.
verification_uri_complete also represents the URI of the end-user verification endpoint, but it contains a user code as a part of the path or a query parameter, too. Please refer to the example in the step (5).
(9) The end-user prepares a web browser. In typical cases, it is a web browser on a PC or a smartphone.
(10) The end-user accesses the device verification endpoint using the web browser.
(11) The device verification endpoint returns an HTML page for user authentication and getting a user code.
(12) The end-user inputs required values and sends them to the server.
(13) The authorization server authenticates the end-user and verifies the user code.
(14) The authorization server returns a page to get consent from the end-user. Implementations may omit this step by integrating it into the previous step.
(15) The end-user selects approval or disapproval and sends the decision to the server.
(16) The authorization server processes the decision and returns the result.
(17) Meanwhile, after receiving the response from the device authorization endpoint, the client application repeats token requests until it gets the final result.
The specification about the token request is described in “3.4. Device Access Token Request”. Request parameters are as follows.
grant_type— Required. The fixed string,
device_code— Required. The device code.
client_id— Client ID.
The following is an example of token request shown in the specification.
POST /token HTTP/1.1
The value of the
grant_type request parameter is
urn:ietf:params:oauth:grant-type:device_code and this indicates that the token request is for the device flow. A token request for the device flow must include the
device_code request parameter whose value is the value of the
device_code response parameter in the device authorization response.
(18) A token response is returned.
Even if the token response indicates an error, the client application repeats token requests while the error code is either
slow_down. The token endpoint continues to return either the
authorization_pending error or the
slow_down error until the decision of (dis)approval in the step (16) is processed or the device code expires.
When receiving a successful response or an error code other than
slow_down, the client application stops making token requests and the device flow finishes there.
2. User Code
If a means that simplifies the input method such as QR code is not provided, end-users have to input a user code manually. Therefore, user codes should not be too long while securing entropy to some extent and should avoid containing characters that are easily confused with each other, like
0 (zero) and
O (capital letter “O”). “6.1. User Code Recommendations” lists recommendations for the user code like these.
The first example of character set for user codes listed in the section consists of 20 characters,
BCDFGHJKLMNPQRSTVWXZ. This is the result of removing vowels (
AEIOUY) from the alphabet 26 characters. The character set is case-insensitive, and including punctuation such as dashes is allowed for readability while such punctuation should be ignored when user codes are compared for verification. The specification shows
WDJB-MJHT as an example of user code that uses the character set.
The second example consists of 10 characters,
0123456789. This is the character set that simply consists of digits only. The specification shows
019-450-730 as an example.
3. Device Flow Implementation
This section introduces the device flow implementation of Authlete.
Authlete supports the device flow since the version 2.1. As the version of the shared server (
api.authlete.com) was updated to 2.1 in February, 2020, developers can try the device flow using the shared server without contract for a dedicated server.
3.1. Service Configuration
A new tab, “Device Flow”, has been added to the service management console. To use the device flow, the fields in the tab need to be set up.
- Device Authorization Endpoint — The URL of the device authorization endpoint. This property corresponds to the
device_authorization_endpointmetadata defined in OAuth 2.0 Device Authorization Grant (Device Flow). The value must consist of only ASCII characters and its length must not exceed 200. The scheme part must be
https. This property is used as the value of
device_authorization_endpointin the response from the discovery endpoint. Also, if a JWT-based client authentication method (
private_key_jwt) is used, the
audclaim in the client assertion (
client_assertion) is compared to the value of this property.
- Verification URI — The verification URI. This property is used as the value of the
verification_uriparameter in responses from the device authorization endpoint. The value must consist of only ASCII characters and its length must not exceed 200. The scheme part must be
https. This property must be set in advance to use Device Flow. Otherwise, an error is returned when
/api/device/authorizationAPI is called.
- Verification URI with Placeholder — The verification URI with a placeholder for a user code. The value must consist of only ASCII characters and its length must not exceed 200. The scheme part must be
https. If this property is set and its value includes a fixed string
https://example.com/verification?user_code=USER_CODE), it is used to generate the value of the
verification_uri_completeparameter in responses from the device authorization endpoint. Authlete replaces the fixed string with an actual user code. If the value of this property is not set or does not include the fixed string, the
verification_uri_completeparameter will not be embedded in responses from the device authorization endpoint.
- Verification Code Duration — The duration of device verification codes (
device_code) and end-user verification codes (
user_code) in seconds. The value is used as the value of the
expires_inparameter in responses from the device authorization endpoint. A positive number must be set to this property in advance to use Device Flow. Otherwise, an error is returned when
/api/device/authorizationAPI is called.
- Polling Interval — The minimum interval between polling requests to the token endpoint in seconds. The value must be between 0 to 65,535. The value is used as the value of the
intervalparameter in responses from the device authorization endpoint unless it is zero.
- User Code Character Set — The character set for user codes (
BASE20is selected, user codes will consist of BCDFGHJKLMNPQRSTVWXZ (20 upper-case non-vowel characters) (e.g.
NUMERICis selected, 0123456789 are used (e.g.
019450730). If this property is not set,
BASE20is used as the default value. Note that user codes generated by Authlete do not include dashes and other punctuation.
- User Code Length — The length of user codes (
user_code). The value must be between 0 to 255. If the value is 0, the length of user codes will be 8 in the case of the character set
BASE20(the entropy is 20^8) and 9 in the case of the character set
NUMERIC(the entropy is 10^9). The value of this property affects the entropy of user codes directly. Too small values would cause DB errors frequently due to the UNIQUE constraint. Too big values would demotivate end-users from inputting user codes. Therefore, don't set an extreme value.
DEVICE_CODE in the list of “Supported Grant Types” in the “Authorization” tab needs to be checked.
3.2. Client Configuration
DEVICE_CODE in the list of “Grant Types” in the “Authorization” tab in the client management console, too.
3.3. Authorization Server
java-oauth-server, an open-source authorization server, has implementations of the device authorization endpoint and the end-user verification endpoint. Their paths are
/api/device/verification, respectively. Download it and try the device flow.
3.4. Authlete API
The following APIs have been added to Authlete to support the device flow.
/api/device/authorization— processes device authorization requests.
/api/device/complete— processes the (dis)approval by end-users.
/api/device/verification— verifies user codes and returns information.
The relationship between an authorization server and the Authlete APIs are as follows.
3.5. Good Points of Authlete’s Device Flow Implementation
Authlete’s good points compared to ordinary implementations are as follows.
- The device authorization endpoint supports the
resourceparameter which is defined in RFC 8707 (Resource Indicators for OAuth 2.0).
- The device authorization endpoint supports the
authorization_detailsparameter which is defined in RAR (Rich Authorization Requests for OAuth 2.0).
- The device authorization endpoint supports client authentication methods that are defined in RFC 7523 (JSON Web Token (JWT) Profile for OAuth 2.0 Client Authentication and Authorization Grants) and RFC 8705 (OAuth 2.0 Mutual-TLS Client Authentication and Certificate-Bound Access Tokens).
- There are no restrictions on implementations of the end-user verification endpoint. Especially, developers can adopt any user authentication method and any structure for the HTML page.
openidis included in the
scopeparameter, an ID token is issued in addition to an access token. This behavior is a relatively big extension for RFC 8628, but there already exist such implementations (e.g. Microsoft) and demand for the feature from the market is strong.
- For ID tokens, the device authorization endpoint additionally supports the
acr_valuesparameter, which follows the
acr_valuesparameter of the backchannel authentication request of CIBA (Client Initiated Backchannel Authentication).
Authlete is a certified implementation that supports OAuth 2.0, OpenID Connect, Financial-grade API, CIBA, and other specifications (Spec Sheet). And now, Authlete supports RFC 8628, the device flow. Please enjoy new specifications with Authlete!