In this scenario, a user attempts to access a protected resource through a device client that lacks a browser or has limited user-input capabilities, such as a smart TV, digital picture frame, or printer. The OAuth device authorization grant type allows a user to grant authorization to the device client using a browser on a second device, such as a smart phone or computer. For more information about the grant type, see the OAuth 2.0 Device Authorization Grant specification.

OAuth device authorization grant
UserUserDeviceDevicePingFederate ASPingFederate ASRSRS1Device authorization request2Device authorization response3Displays URL and user code4Starts polling for authorization status5Browses to URL on second device and enters user code6Continues polling for authorization status7Access token8Request to access protected resources with the access token9Validates access token10Requested data

Processing steps

  1. The device sends a device authorization request to PingFederate, the authorization server (AS), at its device authorization endpoint.
  2. PingFederate returns a device authorization response. Among other parameters, the response contains a device code, a user code, a user authorization endpoint, and a user authorization endpoint with the user code in a query parameter.
  3. The device provides the user authorization endpoint with the user code in a query parameter, the user code, and instructions to the user, as in the following example.
    Using a browser on another device, visit:
    https://www.example.com/authorizeDevice
    
    Enter the code:
    HVF7-B4KW
  4. The device starts sending device access token requests to PingFederate at its token endpoint to poll whether the user has completed the authorization process.

    The device access 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 device access token request it receives, PingFederate returns a device access token response. The payload varies depending on the authorization status.

  5. The user completes the authorization process by performing the following actions:
    1. Goes to the user authorization endpoint on a second device that has a browser, such as a smartphone or a computer.
    2. Fulfills the authentication requirements.
    3. Enters the user code or confirms a pre-populated user code.
    4. Approves or denies the scope of permissions requested by the device.
  6. The device continues polling PingFederate for an authorization status.
  7. PingFederate validates the user code and provides the device with an access token in the device access token response.

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

  8. The device provides the access token to the RS to access protected resources.
  9. The RS validates the access token.
  10. The RS provides the requested data to the device.