Using the device flow¶

The device flow is an alternative flow for a client to obtain Access Tokens and/or ID tokens. The Device Authorization Grant is specified in OAuth 2.0 Device Authorization Grant.

Configuration¶

To start using the device flow, it must be enabled on the token service, and exposed through an oauth-device-authorization endpoint on the service.

To enable the device flow capability on the token service, visit the token service configuration’s Client Capabilities section, and enable the Device Flow.

Once enabled on the token service, individual clients can be configured to be allowed to use this flow.

Make sure to add the endpoint to the token service, and add it to a deployed Service instance.

Endpoints¶

The following URL’s are in play for the device flow. Given the Device Endpoint is mapped to $DEVICE_ENDPOINT, these can be found:

the Device Authorization endpoint that is called by the client, on $DEVICE_ENDPOINT/device

the UserCode Verification endpoint that the user visits to verify a UserCode, on $DEVICE_ENDPOINT/ (this location can be overridden by configuring an alias)

the oauth-token endpoint that the client uses to get tokens from.

Hint

If the oauth-device-authorization is mapped to the /device-path, and the server is deployed on https://server.com`, then the Device Authorization endpoint is at https://server.com/device/device and the UserCode Verification endpoint is at https://server.com/device.

Device Authorization¶

The Device Authorization endpoint must be called by the client through a POST-request, and accepts the following parameters through application/x-www-form-urlencoded encoding:

Parameter	Required	Default value	Description
client_id	Yes	None	The client id of the requestor.
scope	No	empty scope	The scopes, space separated, to include in the token. If `openid` is included, an ID token will be returned. Must be a subset of the scopes configured on the client.
nonce	No	None	An optional `nonce` value that is included in the issued ID token.

Note that the Device Authorization endpoint requires the client to authenticate, as explained in Client Authentication. When providing client credentials through the Authorization request header, make sure that the client_id in that header is the same as the client_id in the post body. The request will fail if they do not match.

The response will include both a user_code as well as a device_code value. The device must show the user_code to the user, with the instruction that it needs to visit the verification_uri and enter it there. Optionally, a qr_code is returned, that contains the data:image/png;base64,.... value of a QR-code image that encodes the verification_uri_complete value. The device_code is meant for the device client to use, and should not be exposed by the device client.

Also returned from the request are the parameters interval, which indicates the time between polling attempts that the device client should consider, and the parameter expires_in. This is indicates the number of seconds before which the issued device_code and user_code must be consumed.

Tip

When the returning of a QR-code is enabled, the response includes the qr_code parameter. The value encodes the actual data of a PNG-image that can be shown inside an HTML-page like this <img src="$qr_code" /> (where $qr_code must be substituted for the response value of the qr_code parameter)

Note

As of version 4.0.0, the previously authorization response parameters verification_url and verification_url_complete have been deprecated and will be removed in a future release, replaced by verification_uri and verification_uri_complete to align with the draft.

UserCode Verification¶

The UserCode Verification endpoint is returned as verification_uri. This is the URL that the user must visit to verify the returned UserCode. It is derived from the path that the oauth-device-authorization endpoint is mapped on in the configuration. Instead of a derived endpoint, it is possible to configure an alias that is used to return the value of verification_uri.

For convenience, the response of the initial Device Authorization request also returns a verification_uri_complete parameter, which appends the user_code=USERCODE as querystring to the verification_uri.

A UserCode must always be POSTed to the verification endpoint to be accepted. Once accepted, the user will be authenticated using the device client’s user authentication configuration. Finally, the user must explicitly allow access to the device client. Once this access is granted, the device client can redeem the device_code for the requested token or tokens through the token endpoint.

Token Endpoint¶

The device flow relies on the standard oauth-token endpoint. This means that access to this endpoint must be authenticated by the client (see Client Authentication), and it must be a POST-request where the parameters are encoded through application/x-www-form-urlencoded encoding. The following parameters are accepted:

Parameter	Required	Default value	Description
grant_type	Yes	N/A	Must be provided and for device flow have the value `urn:ietf:params:oauth:grant-type:device_code`
device_code	Yes	N/A	Must contain the `device_code` value that was returned from the initial device authorization request (step 1)
client_id	Yes	None	Must be provided and have the value of rhe client id of the requestor

Once the device client has made the initial request to the device authorization endpoint, it can start polling this endpoint using the received device_code, with a suggested polling frequency as indicated by the interval parameter from the device authorization response.

After the user has verified the UserCode, and until the device_code expires, it makes sense for the client to make a polling request using the device flow grant type. The presented device_code is either accepted or not. In case it is _not_ accepted, the standard OAuth error invalid_grant is returned as error, otherwise the request to the token endpoint with the device_code will result in the issuance of an Access Token, Refresh Token and/or an ID token.

Once the device_code has been redeemed for tokens, it is no longer valid for anything. If the device_code were to be used once more to try and get tokens, the tokens that were issued based on that device_code will actually be revoked, as that could be the result of a security breach.

Token Procedures¶

The device flow issues tokens or nonces on multiple steps of the process. There are two occasions that can be customized through a token procedure:

Once the UserCode is verified, and properties are assigned to the DeviceCode (oauth-device-authorization)

Once the DeviceCode is presented to the token endpoint, and Access Tokens, a Refresh Token and/or an ID token are issued (oauth-token-device-code)

More details on writing these procedures can be found in the section Token procedures.

Templates¶

The user interaction of the process that verified the UserCode, results in three view templates that will be rendered. The three templates are:

enter-usercode where the user is asked to enter the usercode that was given to the user by the device

confirm-usercode that is shown to the user after authenticating, and where the user is asked whether the device should be allowed access, as it requested, and

usercode-confirmed that is shown to the user when the usercode is confirmed and the verification process ends

These templates can be found in the views/oauth path of the appropriate template area. For more information on template customization, see the chapter Front-End Development.