Device code grant type

If the grant type is device_code, PingOne returns an activation code in the response to the POST /{{envID}}/as/device_authorization request. This authorize endpoint is used only with device authorization grant flows. It starts a flow that gives OAuth enabled devices such as smart TVs the ability to complete user authorization and access protected resources.

Unlike the PingOne as/authorize request, which returns a 302 Location header in the response, the /as/device_authorization endpoint returns a 200 OK successful operation message. The response body returns the user_code property value (the activation code) as well as the verification URI (a short web address) that end users visit on another device to enter (or confirm) the activation code.

The steps below outline the device authorization grant flow.

Authorization for a device authorize grant request

The POST /{{envID}}/as/device_authorization request takes all configuration paramaters in the endpoint’s request body. Parameters and their values are Form Serialized by adding the parameter names and values to the entity body of the HTTP request and specifying the Content-Type: application/x-www-form-urlencoded request header.

Step 1: Send an authorize request to the PingOne authorization server using POST.

curl --location --request POST '{{authPath}}/{{envID}}/as/device_authorization' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'client_id={{deviceAppID}}' \
--data-urlencode 'scope=openid'

The request requires the following properties:

client_id: The application ID for an application that specifies the device_code grant type.
scope: The permissions that specify accessible resources.

The response returns a 200 OK message with the following properties:

{
    "device_code": "96624b82-1469-46a9-a4f8-544970b62c37",
    "user_code": "GKHF-JQBC",
    "verification_uri": "https://auth.pingone.com/abfba8f6-49eb-49f5-a5d9-80ad5c98f9f6/device",
    "verification_uri_complete": "https://auth.pingone.com/abfba8f6-49eb-49f5-a5d9-80ad5c98f9f6/device?user_code=GKHF-JQBC",
    "expires_in": 600,
    "interval": 5
}

Step 2: Start the flow using GET {{authPath}}/{{envID}}/device/{{appIdentifier}} or GET {{authPath}}/{{envID}}/device.

The endpoint’s {{appIdentifier}} value is set on the application configuration. This ID can be the PingOne application ID or another unique secondary identifier. When using the /device endpoint for a device authorization grant flow without the application identifier, the flow uses the environment’s default sign-on policy.

The response returns a Location HTTP header that specifies the URL for the sign-on screen and the flow ID.

Step 3: The sign-on flow calls the POST /{{envID}}/flows/{{flowID}} flow orchestration endpoints to prompt the end user to complete the actions required by the sign-on policy, and perform the following two device code actions: (1) confirm the device activation code, and (2) accept device authorization grant consent.

This flow action confirms the activation code:

curl --location --request POST '{{authPath}}/{{envID}}/flows/{{flowID}}' \
--header 'Content-Type: application/vnd.pingidentity.deviceAuthGrant.userCode.verify+json' \
--data-raw '{
    "userCode": "{{userCode}}"
}'

This flow action accepts consent:

curl --location --request POST '{{authPath}}/{{envID}}/flows/{{flowID}}' \
--header 'Content-Type: application/vnd.pingidentity.deviceAuthGrant.consent+json' \
--data-raw '{
	"accept": true
}'

Step 4: Call the token endpoint to exchange the device code for a token. Note that the grant_type parameter in the request body uses the IETF-specified syntax to identify the device code grant type (urn:ietf:params:oauth:grant-type:device_code).

curl --location --request POST '{{authPath}}/{{envID}}/as/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'grant_type=urn:ietf:params:oauth:grant-type:device_code' \
--data-urlencode 'device_code={{deviceCode}}' \
--data-urlencode 'client_id={{deviceAppID}}'

In the token request above, the application’s configuration has the tokenEndpointAuthMethod set to NONE. In this case, no Authorization header is required.

For more information about the endpoints used in a device authorization grant flow, refer to Device Authorization Grant and Device Authorization Grant Flows in the PingOne Platform Auth APIs.

PingOne Platform APIs

Device code grant type

Authorization for a device authorize grant request