Skip to content
Trimble Identity

Implement device authorization grant support

Trimble Identity supports the implementation of device authorization, an OAuth 2.0 grant type, which allows users to sign in to input-constrained devices such as Hololens™ or Oculus™, that cannot handle are not capable of handling the UI workflows associated with authenticating the user with Trimble Identity.

Use case

A technician in the field needs to use a Trimble device to manage their project and access data from Trimble APIs/resource servers, but their device is input-constrained. Device authorization allows them to complete the sign-in workflow using that device and a primary device for verification.

Requirements

Users

  • A user must create an application in Trimble Cloud Console and configure it to use the device grant API

Devices

  • The device making these API calls needs a connection to the internet and a way to perform HTTP requests.

How the device makes the HTTP call and displays the user code varies depending on how it is built by the individual integrator.

Process

A user wants to use a Trimble device (primary device) for managing data/resources in the field. The device connects to Trimble Identity and initiates the workflow to access the user’s data. The workflow follows these steps:

  1. The client application calls the /device_authorization end-point in Identity with a request to access user’s data/resources.

  2. Identity validates whether the client_id and the list of scopes are valid.

  3. Identity generates a unique pair of codes {device_code, user_code}, which are valid only for a limited period of time. Then this pair is attached with the list of scopes and request_uri.

    • {device_code, user_code} status: pending

    • The list of scopes forms the base for the content in the consent dialog box (to be shown to the user).

      Both of these endpoints expect requests in application/x-www-form-urlencoded format

  4. On their secondary device with the required UI capabilities, the user visits the Trimble Identity Device Activation page and enters the user code.

    For the user’s convenience, the secondary device should be easy to type on

    • The user must first be signed into TID Trimble Identity - see identity to enter the code. The user can also choose to directly select verification_uri_complete and in this case, the page displays/highlights the user code, so that user can verify whether it matches with the user code displayed on the primary device, and then submits the request.

  5. The application on the primary device calls the /token end-point from Identity to get the access token. The client device repeats this token call until the user authorizes the client application to access the resources on the user’s behalf using the secondary device.

    • If the user grants access by accepting the consent, then Identity logs the respective pair {device_code, user_code} as access_granted, so this information can be utilized later when the application on the input-constrained device calls the /token end-point to get the access_token.
    • If the user denies the request, then Identity marks the respective pair {device_code, user_code} as access_denied.

  6. Once the token is provided, the application on the primary device can call the Trimble APIs (the access token’s subject is the user who gave the consent) to access the resources on the user’s behalf.

Example

The client application on the primary device directly interacts with the authorization server with the list of scopes to get the device_code and the user_code:

  • POST /device_authorization

    • client_id: (REQUIRED) The client identifier of the application on the input-constrained device.
    • scope: (REQUIRED) Multiple scopes may be space delimited, and this identifies the set of resources that the application (on the device) could access on user’s behalf.

Example response

Success

If the request is valid in terms of the given client and scope, then Identity sends a response with an HTTP 200 status code and include the following.

  • device_code: (REQUIRED) The device verification code (from the unique pair).

  • user_code: (REQUIRED) The end-user verification code (from the unique pair).

  • verification_uri: (REQUIRED) The end-user verification URI on the authorization server.

  • verification_uri_complete: (OPTIONAL) A verification URI that includes the user_code designed for non-textual transmission. This can be used by the device to represent this complete URI in a QR code so that user can directly scan and access the URI.

  • expires_in: (REQUIRED) The lifetime in seconds of the device_code and user_code.

  • interval: (OPTIONAL) The minimum time in seconds that the client should wait between polling requests to the token endpoint. If no value is provided, clients must use five as the default.

Fail

If the request is not valid, then Trimble Identity sends a response with an HTTP 400 (Bad Request) status code and includes the following

  • error

    • invalid_client

      • if the client is invalid

    • invalid_scope

      • if one of the scopes mentioned in the request is invalid

Validation workflow

The application on the input-constrained device periodically polls the /token end-point to get the access token:

  • POST /token

  • grant_type

    • REQUIRED. Value must be set to urn:ietf:params:oauth:grant-type:device_code.

  • device_code

    • REQUIRED. The device verification code that was sent as the response to /device_authorization request.

Upon receiving the request, Identity authenticates the caller of this API and includes the client_id in the request body.

  • Identity verifies the pair {device_code, user_code} using the device_code, and checks the status of the pair/request:
  • The status is access_granted: Identity sends a response with an HTTP 200 code and includes the following:
  • access_token
  • refresh_token (optional)
  • expires_in
  • id_token (optional)

The sub claim in the access_token would be uuid of the user who has approved consent.

  • The status is pending: Identity sends a response with an HTTP 400 code (specifically HTTP 428) and with the error authorization_pending indicating the user hasn’t yet completed the access confirmation request.
  • The status is pending: Identity informs the client to slow down the request, in the scenario where the pair {device_code, user_code} is in a pending state for a longer time. The response has an HTTP 400 code (specifically HTTP 403), and the client on the device should slow down by increasing the interval by five seconds (+5) for the subsequent token calls/requests.
  • The status is access_denied: Identity sends a response with an HTTP 400 code (specifically HTTP 403) and with the error access_denied.
  • The device_code pair has expired: Identity sends a response with an HTTP 400 code and the error expired_token. The client on the device is required to initiate a new device authorization request.

The other standard errors for /token calls would also be applicable. Example: invalid_client, and unsupported_grant_type.

  • To decode and verify the TID JWT Token, refer to Decode JWT