Orchestration SDKs

Authenticating devices with the Device Authorization Grant

PingOne PingOne Advanced Identity Cloud PingAM Android iOS

The Orchestration SDK implements the OAuth 2.0 Device Authorization Grant (RFC 8628) that lets you authenticate users on devices that have limited input capabilities or no embedded browser, such as smart TVs, IoT devices, or lobby kiosks.

The flow involves two devices:

The requesting device

The constrained device running your app. It starts the flow, displays the code, and polls the server until it receives tokens.

The approving device

A browser-capable device, such as the user’s phone or computer, where the user navigates to the authorization server and authenticates.

The app on the requesting device obtains a short-lived code from the authorization server, displays it to the user, and polls in the background while the user completes authentication on the separate, browser-capable approving device.

Requesting deviceAuthorization serverApproving device..Auth journey . flow....App....Authorization server....Auth journey . flow....User..AppOidcDeviceClientAppOidcDeviceClientAuthorization serverPingOne / AIC / PingAMAuthorization serverPingOne / AIC / PingAMAuth journey / flowAuth journey / flowUserBrowser or native appUserBrowser or native app..Auth journey . flow..1)POST device authorization endpoint(client_id, scope)2)device_code,user_code,verification_uri,intervalApp displaysuser_codeandverification_uri(or QR code) to the user.3)POST/token(device_code)4)authorization_pendingApp polls at theintervalrate until the user approves.5)Navigate toverification_uri,enteruser_code6)Start authentication7)Authenticate user(journey or DaVinci flow)8)Authentication success9)POST/token(device_code)10)access_token,id_token,refresh_token
Figure 1. Summary of the device authorization grant flow

The overall authentication flow is as follows:

  1. The requesting app calls OidcDeviceClient.deviceAuthorization(), causing the Orchestration SDK to send a POST request to the device authorization endpoint.

  2. The server returns a device_code, a short human-readable user_code, a verification_uri, an optional verification_uri_complete parameter, and a polling interval.

    The requesting app now displays the user_code and verification_uri to the user, so they can complete authentication on a separate, more capable device.

    Options for displaying the values include:

    • Plain text, so the user can visit the URL and type the code manually.

    • A QR Code the user can scan that has the URI, and the user code as a query parameter. When the user scans it on the approving device, the browser opens the authorization server’s UI with the code pre-filled, so the user does not need to type it.

  3. The requesting app begins polling the server’s token endpoint, including the device_code, to check if the authentication has been completed.

  4. The server returns authorization_pending, indicating the user has not yet authenticated. The requesting app waits for the interval duration and polls again.

  5. On the approving device, the user navigates to the verification_uri and enters the user_code.

  6. The authorization server starts an authentication journey or DaVinci flow.

  7. The user completes authentication on the approving device, stepping through the journey or flow.

  8. On successful authentication, the server updates the status for the relevant device_code.

  9. The requesting app is still polling the token endpoint with the device_code.

  10. This time, the server returns an access_token, id_token, and optional refresh_token. Authentication is complete.

Get Started

Android

Configure an Android app to authenticate using the Device Authorization Grant.
iOS

Configure an iOS app to authenticate using the Device Authorization Grant.