Skip to content
Trimble Identity

TID / OAuth IDP Integration – Authorization & Redirection Flow

Overview

This guide explains how to integrate your application with TID (Trimble Identity) or any OAuth-compliant IDP, focusing on authorization, redirection, and secure handling of application-specific context.

TID (Trimble Identity) or any OAuth-compliant Identity Provider (IDP) is responsible only for user authentication and authorization. In a federated scenario, the federation partner (external IDP) authenticates the user. After successful authentication, the response is sent to TID, which validates the IDP response and performs Just-In-Time (JIT) user provisioning. Once JIT provisioning is complete, TID issues the response (access & ID tokens) to the application.

TID is not aware of and not responsible for the application’s second or subsequent steps, which are entirely application-specific and driven by business requirements.

Once the IDP completes authentication and returns the authorization code and state, all further processing must be handled by the application.

Key Principle

  • The IDP’s responsibility ends after returning:

    • authorization code
    • state

  • Any additional workflow, navigation, or business logic is controlled by the application.

  • The state parameter is the recommended mechanism to carry application-specific context across the OAuth flow.

High-Level Authorization Flow

  1. Application initiates the OAuth authorization request to TID.
  2. User authenticates by the IDP.
  3. IDP redirects back to the registered application redirect URI with:
    • code
    • state
  4. Application extracts the values and continues with business-specific logic.

Sequence Diagram

TID IDP Integration Sequence Diagram

Using the state Parameter

The state parameter is used to preserve application-specific context across the OAuth authorization flow. It can include dynamic key-value pairs (such as redirection paths, workflow IDs, or action types) that the application will use after authentication. This approach is commonly used in integrations like Jira and Bitbucket.

Typical use cases include:

  • Post-login redirection paths
  • Workflow identifiers
  • Action or source identifiers (e.g., Jira, Bitbucket)

Note: The state value must be URL encoded before being sent in the authorize request.

Example (Before Encoding)

{
  "redirect": "/projects/12345/dashboard",
  "workflow": "fieldDataSync",
  "action": "openProject"
}
  • redirect: The path or module in your Trimble app to redirect the user after authentication.
  • workflow: The business process or workflow being resumed (e.g., field data sync).
  • action: The specific action to perform after login (e.g., open a project).

The authorization request should:

  • Use a registered redirect URI
  • Include dynamic, application-specific values encoded in the state parameter

Sample Authorize Call

https://id.trimble.com/oauth/authorize?
client_id=<client_id>&
redirect_uri=<registered_endpoint_that_exchanges_code>&
response_type=code&
state=<URL_encoded_dynamic_action_strings>&
scope=<scopes>

Handling the IDP Response

After successful authentication, the IDP redirects the user back to the application:

<redirect_uri>?code=<authorization_code>&state=<state_value>

Application Responsibilities

  • Extract the code and state parameters
  • Decode and validate the state value
  • Initiate the second-step business logic
  • Exchange the authorization code for tokens (if applicable)

Token Usage After Exchange

After exchanging the authorization code for tokens, the application uses the access token to call protected APIs on behalf of the user. If a refresh token is issued, it can be used to obtain new access tokens without requiring the user to log in again. The application should store these tokens securely and use them according to its business needs.

Handling the Second-Step URL

If the second-step URL is also responsible for:

  • Processing the authorization code
  • Interpreting the state parameter

Then that URL:

  • Can be registered directly in the API Cloud / IDP console
  • Can be used as the redirect_uri in the authorize request

This approach simplifies the flow and avoids unnecessary internal redirections.

Security Considerations

  • Always validate the state parameter to protect against CSRF attacks
  • Use HTTPS-only redirect URIs
  • Register all redirect URIs explicitly in the IDP console
  • Do not place sensitive information in plaintext within the state value

Summary

  • TID / IDP handles authentication and authorization only
  • The application controls all post-authentication steps
  • The state parameter carries application-specific context
  • Redirect URIs can be aligned with processing steps for cleaner and simpler integration

References