Skip to content
Trimble Identity

Grant types

OAuth 2.0 is a standard protocol by the Internet Engineering Task Force (IETF) standards organization for managing authorization. Trimble Identity utilizes OAuth for improved security and interoperability. OAuth provides a number of ‘grant types’ that enable Authorization based on different use cases.

Grants determine the way the application retrieves an Access Token without exposing credentials. The configuration of an application with Identity is done following a particular grant flow. OAuth grant flows determine the exact sequence of steps that are involved in the OAuth process, and affects how the client application communicates with the OAuth service at each stage. The application type and the programming language is written in are the best criteria for selecting the grant type you follow.

OAuth Roles

There are four roles in the OAuth process flow:

  • Client - The term client refers to your application. The terms client and application can be used interchangeably. Your application can be a web app based on a server, a single app that executes on a browser, or a desktop app on a mobile device.
  • Resource owner - An entity capable of granting access to a protected resource. This is usually a user.
  • Resource server - A server-side entity that handles authenticated requests after applying an access token via OAuth tokens. These tokens are issued by the authorization server, typically to a client application. The resource server validates the token before serving a resource to a client.
  • Authorization server - Trimble Identity is the authorization server, which authenticates and authorizes users depending on the grant types.

Grant types

Below are the currently used grant types and how you can use them with Identity.

If you are currently using an Implicit Grant flow, please use the Authorization Code with PKCE flow.

Which grant should I use? User vs. Application context

Client Credentials: When user context is not required

Let’s begin with the simpler case. When user context is not required to access API resources, the use case is most likely solved by the common OAuth grant type called Client Credentials. Client Credentials are just as the name suggests: a client id and client secret—essentially an identifier and password—that represent an application and are used to authenticate the application. Client Credentials can easily be used in short- or long-running automated workflows when a user is not present, and user context is not required.

Client Credentials examples:

  1. An application needs to access resources such as map data from a map data server, and the map data is not scoped to a user, e.g. map tile services.
  2. An application needs to run a long-running (minutes to hours) data transformation, perhaps on an automated schedule where a user is not present.

Authorization Code Flow: When user context is required, and a user is present

There are many workflows where API resources are scoped to a user, and a user initiates the API through a graphical user interface (GUI). This is supported by another well-known OAuth grant type called Authorization Code Flow. In the Authorization Code Flow, a user is authenticated by entering their username and password within Trimble Identity, and a client application uses the access token scoped to that user to access API resources in the context of that user.

Authorization Code Flow examples:

  1. A user makes a comment within an application. The ‘Comment API’ uses the user context to know who created the comment. There is traceability to the user.

Refresh Token: When user context is required, but a user is not present

Handling refresh tokens can greatly improve user experience. When access tokens expire, refresh tokens can be used to get a fresh access token without requiring the user to sign in again.

Refresh Token examples:

  1. A user initiates a long-running data processing workflow that takes hours to complete. By the end of the process, the user access token is required to store the final deliverables in the user’s online storage location.
  2. An application wants to run a regularly scheduled action at midnight every night on behalf of the user. The user cannot (should not) be asked to sign in before every night.

Token Exchange: When a user context is required, but the user is not present, and downstream services need to take action on the user’s behalf

In distributed environments (like microservice architectures), one service may need to access resources in another downstream service on a user’s behalf, but without the user present. A client credentials grant type enables the machine-to-machine communication, but loses the user context. An access token received via token exchange maintains an record of delegated authority (via one or more act claims), so receiving services can perform additional authorization checks.

Exchange Token examples:

  1. A user makes a request to a work management API, called API-W, with her user access token. API-W needs to coordinate with another backend service, API-B, to fulfill the user’s request. API-W requests TID exchange the user’s token for a new token, which includes the necessary claims for API-W to make requests to API-B. This new token maintains the original user context, and claims about delegated authority, so API-B knows on whose behalf the request has been made.

Endpoints, response types, and token types

For the /authorize endpoints, three response_types are supported. These values can show up alone or in any combination.

  • code = returns oauth_code
  • id_token = returns id_token
  • token = returns access_token

The /token endpoint is supported by four grant types and responses:

  • client_credentials = will return access_token
  • refresh_token = will return access_token, or id_token
  • authorization_code = will return access_token, or id_token
  • on behalf/token exchange = will return access_token

For more information on authorization with the SDK we recommend starting with our SDK page.