PingOne

Device authorization

The OAuth device authorization grant type allows a user to grant authorization to the device client using a browser on a second device, typically a smartphone or computer.

This grant type is typically used to access a protected resource through a device that lacks a browser or has limited user input capabilities, such as a smart TV or appliance.

The device authorization grant process takes place between the user, device, PingOne authorization server, and the Resource Server (RS). For more information about the grant type, see the OAuth 2.0 Device Authorization Grant specification.

Diagram detailing the steps of the device authorization process

  1. The device sends a device authorization request to PingOne, the authorization server at its device authorization endpoint.

  2. PingOne returns a device authorization response. Among other parameters, the response contains a device code, a user code, and a verification URI.

  3. The device provides the verification URI in a query parameter and instructions to the user, as in the following example:

    Using a browser on another device, visit:
https://www.example.com
Enter the code:
HVF7-B4KW

  4. The device starts sending token requests to PingOne to poll whether the user has completed the authorization process.

    The token request must include the device authorization grant type, urn:ietf:params:oauth:grant-type:device_code, the device code, and the user code.

    For each token request it receives, PingOne returns a response. The payload varies depending on the authorization status.

  5. The user completes the authorization process by:

    1. Going to the verification URI on a second device that has a browser, such as a smartphone or a computer.

    2. Fulfilling the authentication requirements.

    3. Entering the user code or confirming a prepopulated user code.

    4. Approving or denying the scope of permissions requested by the device.

  6. The device continues polling PingOne for an authorization status.

  7. PingOne validates the user code and provides the device with an access token (and an ID token if applicable) in the token response.

    If the user denies the scope of permissions, PingOne provides the device with a relevant error message in the token response.

  8. The device provides the access token to the resource server to access protected resources.

  9. The resource server validates the access token.

  10. The resource server provides the requested data to the device.

Sample browser redirect flow

The user turns on their smart TV and starts a streaming app called ShowMe for the first time.

  1. The ShowMe app sends a device authorization request to PingOne.

  2. PingOne returns a device authorization response to the ShowMe app.

    The device authorization response includes the verification URI, the user code (activation code), and the device code, among other response parameters.

The ShowMe app then:

  1. Presents the user code and verification URI through a QR code, a short URL, or both.

  2. Prompts the user to scan the QR code to open the verification URI or enter the short URL on a smartphone, tablet, or computer.

  3. Starts polling PingOne at the token endpoint with the device code it received from PingOne. PingOne returns an authorization pending message to the ShowMe app in the token responses until the user completes the next step.

The user:

  1. Opens the verification URI on their smartphone, tablet, or computer.

  2. Completes the authentication process.

  3. Confirms the activation code that’s shown on the smart TV.

  4. Authorizes the request.

When the user authorizes the request, PingOne returns security tokens to the ShowMe app the next time it sends a token request.

Sample user interactions

When the user opens the verification URI on the smartphone, tablet, or computer, the short URL redirects the browser to PingOne. PingOne prompts the user to complete the authentication process.

If the user completes the authentication process successfully, PingOne prompts the user to enter the activation code.

Screen capture of the prompt requesting the user’s activation code.

If the user enters the correct code shown by the streaming app on the smart TV, PingOne then prompts the user to authorize the request. The Application Consent page shows the name of the application and the authenticated user.

Screen capture of the prompt requesting that the user approve the ShowMe app request to access their account

If the user approves the request, PingOne shows a message stating that the request is authorized. The user can then close the browser.

Screen capture displaying the successful authorization request.

The next time the ShowMe app polls PingOne at the token endpoint, PingOne returns an access token and ID token if it’s requested.