Skip to content
Trimble Identity

Store third-party tokens with user context

Purpose

Third-party access tokens enable Trimble applications to manage third-party sessions for users. This reduces the number of sign ins a user sees when using applications that leverage third-party integrations.

For example, a Trimble application utilizes third party map data from Esri, and Trimble desires to reduce double sign in to Trimble and Esri every session.

Process

With this process, you will use the OpenID and OAuth 2.0 authorization code flows to authenticate and get access tokens from the third-party target Identity Provider (IdP) to access a user’s resources.

For each external IdP, Trimble Identity creates a client application in the developer portal offered by the respective target IdP and through that client application, Trimble Identity authenticates the users and retrieves the access token.

Once the user is authenticated with the target IdP the first time, Trimble Identity stores the user’s refresh token. The refresh token is used later to create new access tokens when needed so that the user does not need to sign in to the third-party IdP again.

When it comes time for a Trimble application to call third-party resources on behalf of the user, the Trimble application calls a dedicated end-point for retrieving the access token from an external IdP.

A second sign in may be required again if the user’s refresh token is no longer valid. In this case the user has to be authenticated again to get the access token and, in the same process, obtain a new refresh token.

  • Scenario 1: the Trimble Identity user is already authenticated with external IdP through Trimble Identity’s external IdP integration and the refresh token obtained during the last authentication is still active/valid.
  • Scenario 2: Trimble Identity user is accessing this external integration for the first time, or the user’s refresh token is no longer active.

Registering a third-party IdP with Trimble Identity

Prerequisites

All users must be Trimble Identity users. The TID Trimble Identity - see identity user access token is used when initiating this workflow.

  • The third-party IdP must use the standard OAuth 2.0 Authorization Code flow.
  • Provide the endpoints used in the authorization code flow:
  • Provide the Auth URL
  • Provide access token URL.
  • Provide the refresh token URL.

The lifetime of access and refresh tokens may differ from system to system.

An application or client must be registered with the third-party system. Provide the following details to Trimble-support@trimble.com:

  • Integration Identifier
  • Customer Name
  • Trimble Application Identifier
  • environment
  • Integration URL
  • Integration Client ID
  • Integration Client Secret

Process

When registering a client in the third party IdP, you must configure the following redirect URIs:

Example Endpoints

“/integrations/Token” endpoint

Example

{
"esri": "{access token}",
"expires_in_seconds": 1800,
"integration_url": "https://www.arcgis.com/sharing/rest/oauth2",
"client_id": "{client_id}"
}

  • Else:

    • Status code 303
    • Header:Location={Authorize API}&{Token State}

Example

https://id-pub-dev11-us.dev.id.trimblecloud.com/integrations/authorize?state={state as a guid}

Authorize endpoint

  • Format https://{region ex. eu, us,ap-us, etc.}.id.trimble.com/integrations/authorize?state={token state}&client_id={client_id}&redirect_url={redirect_url}

  • HTTP Method: Get

    • Requires

    • Additional URL Query Parameters

      • State

        • Given by Token as part of payload

      • Registered TID application

        • Client ID
        • Redirect URL

  • Returns

    • Authorize url as a redirect url

      • Authorize state

      • Oauth parameters for integration

        • Requires registration of redirect url to API.

Example

https://www.arcgis.com/sharing/rest/oauth2/authorize/?client_id={integration _client_id}&response_type=code&redirect_uri={code_exchange_url}

Code exchange

  • Format https://{region ex., eu, us,ap-us, etc.}.id.trimble.com/integrations/code_exchange?code={code}&state={authorize state}

  • HTTP Method: GET

  • Called directly from the third-party integration idp.(No action necessary from development)

  • Returns

    • A redirect back to the registered integration redirect url.

      • URL parameter if successful.

        • {registered integration application redirect url}/integration_exchange_request_successful/

Revoke third-party token