Skip to content
Trimble Identity

Authorization code

In the Authorization Code flow, a code is returned to the client through a browser redirect after the user (resource owner) gives consent to Identity (authorization server). The client subsequently exchanges the authorization_code for an access_token. Users’ credentials are never exposed to the application (client).

The Authorization Code grant type is intended to be used by user-facing web applications with a server-side component. When the user grants authorization, the Identity authorization endpoint provides the client with a short-lived authorization code.

How it works:

  • The application opens a browser to send the user to the authorization server
  • The user authorizes the app’s request
  • The user is redirected with the Authorization Code in the query string
  • Trimble Identity returns an ID token to an application which validates the signature
  • The application exchanges the Authorization Code for an access token

The following diagram describes the Authorization Code flow:

Authorization request

The first request is a GET to the authorization endpoint (/authorize) performed in a web browser. The /authorize endpoint supports three response_types: code,id_token, token. If code is present in your parameters, JWTs are not needed for authorization.

If the request contains the OpenID, scope it is also considered an authentication (OpenID Connect) request, and an ID token is issued.

  • API CALL:

    • GET {``baseURL``}/oauth/authorize

  • PARAMETERS:

    • state: This field is used to return data (like a return URL) after sign-in with an access code.

    • client_id = Application ID registered for the application (UUID)

    • response_type = code

    • scope = openid and applicationname (Scope is space delimited)

    • redirect_uri = {Redirect URL registered with Identity}

    • ui_locales = {String locale value. This specifies locale language Identity v4 UI will display. This value is optional.}

      If the exact locale is unavailable, the display will fall back to the locale base language before reverting to the user’s browser preference.

    • prompt = {Details for each value below. This value is optional.}

      • none = Trimble Identity will not display any UI, if there is no SSO session the /authorize call will redirect to the caller with a error e.g. /callback?error=login_required&error_description=Authentication%20required
      • login - Trimble Identity will always display the sign in UI, regardless of whether an SSO session exists.
      • create = Trimble Identity will display the sign up page rather than the sign in page.

    • login_hint - {Allows an application to specify the email address for use in the sign in or sign up page if you are using prompt=create. This value is optional.}

    • Identity_provider - {Allows an application to declare a specific federated identity provider should be used to authenticate e.g. okta_trimble. This value is optional. For more information on federation, see the Federation documentation.}

The value of id_token is only returned if id_token was included in the response_type of the original /authorize request.

Example Request

https://id.trimble.com/oauth/authorize?scope=openid processing&response_type=code&redirect_uri=http%3A%2F%2Flocalhost%3A8080%2Fplayground%2Foauth2client&client_id=WCD9D...

Once this endpoint is hit, the user’s browser is redirected to the login screen based on the configured sign-in mechanism.

Authorization Response

Once the user provides the username and password, the user is redirected back to the redirect URL provided in the above URL with the Authorization Code.

The code is valid for 10 minutes.

Example Response

http://localhost:8081/authorization_code-0.0.1-SNAPSHOT/home.jsp?code=ac5d5...

Token Request

After acquiring the authorization code, you exchange an authorization code for an access token through the resource server.

  • API CALL:

    • POST {``baseURL``}/oauth/token

  • HEADER:

    • Authorization: Basic <Base64 encoded “ClientID:ClientSecret”>
    • Accept: application/json

  • REQUEST BODY:

    • grant_type= authorization_code
    • code= {given authorization_code}
    • client_id= {Application ID registered for the application}
    • redirect_uri= {Redirect URL registered with Identity}

Example Request

POST: /oauth/token
Host: stage.id.trimblecloud.com
Accept: application/json
Authorization: Basic VmNqWUx0VWs4R3dCRHhpakNVbjNfTks1TDNvYTpoVkdERjNFdnp1VU9kaU1ra1ozaVU5d2ZZc0lh
Content-Type: application/x-www-form-urlencoded
Cache-Control: no-cache


grant_type=authorization_code&code=ac5d5...&redirect_uri=http%3A%2F%2Flocalhost%3A8081%2Fauthorization_code-0.0.1-SNAPSHOT%2Fhome.jsp&client_id=VcjYLtUk8GwBDxijCUn3_NK5L3oa

Token Response

If the token request succeeds, the server responds with a 200 response code.

A JSON response that is received includes the following values:

  • access_token
  • refresh_token
  • expires_in
  • id_token

Example Response

{
"token_type"   : "bearer",
"expires_in"   : 3600,
"refresh_token": "eyJhbG...<JWT truncated for brevity>",
"id_token"     : "eyJhbG...<JWT truncated for brevity>",
"access_token" : "eyJhbG...<JWT truncated for brevity>"
}
  • To decode and verify the TID JWT Token, refer to Decode JWT

The access token received with this can be used for further API calls. Your application must keep the access token and the refresh token secret at all times. Access token and refresh token should not be visible to any user, including the account user.