Skip to content
Trimble Identity

JWT concepts

A JSON Web Token, or JWT, is an open standard format used to transmit information, called claims, safely between two parties. In authentication, when the user successfully logs in using their credentials, a JWT will be returned.

JWTs consist of three parts:

  • Header
  • Payload
  • Signature

For examples of responses for access and ID token tokens please see JWT Definitions.

The header is a JSON string that contains information about the JWT’s encryption. Verifying algorithm used by Identity is RS256.

The header usually consists of:

  • type = JWT
  • alg = RS256
  • kty = {Algorithms used for signature key}(HMAC, SHA256, or RSA)

Example header

{
  "typ": "JWT",
  "alg": "RS256",
  "kid": "1"
}

Payload

The payload is the body of the request, which contains the claims. When a client application includes a JWT request to an API, APICloud Endpoints validate the JWT before sending it to the API backend.

The payload content can vary depending on the grant and token type.

Recommended values in a payload include:

  • iss = https://id.trimble.com
  • exp = {Expiration of Token as a UNIX timestamp}
  • sub = {Subject, whom this token refers to(the user)}
  • aud = {Recipient(s) for which the JWT is intended (clientids or application UUID)}
  • iat = {Time at which the JWT was issued}
  • application_name = {name of application}
  • scope = {openID, or application_name space separated string}
  • account_id = {Unique identifier of the account in IAM}

Account ID

Account ID is associated with a distinct user, device, or application, establishing a reference for that entity’s identity within the system facilitating the precise identification, management, and correlation of attributes, permissions, and activities pertaining to the associated entity.

It acts as the foundational key for all interactions and data linkages within the Identity framework, ensuring integrity and consistency across various identity-related processes such as authentication, authorization, auditing, and provisioning.

Payload example

{
  "iss": "https://id.trimble.com",
  "exp": 1683221341,
  "nbf": 1683217741,
  "iat": 1683217741,
  "jti": "1d60d20010714c7eaab91243c9a60d9b",
  "jwt_ver": 2,
  "sub": "6a9ff1c9-3c97-459d-95de-d0a4ae6e7c03",
  "identity_type": "user",
  "amr": [
    "password",
    "mfa",
    "sms_mfa"
  ],
  "auth_time": 1683217740,
  "azp": "8257991b-5f7d-4a7b-826e-3d4d92460806",
  "aud": [
    "8257991b-5f7d-4a7b-826e-3d4d92460806"
  ],
  "scope": "NextGenMyProfile",
  "data_region": "us",
  "account_id": "12345678-90ab-cdef-1234-567890abcdef"
}

Signature

The signature is used to verify the information that is being transmitted. The signature is created using:

  • Header (algorithm)
  • Payload (issuer, expiration)
  • Encryption Key (RS256)
  • The hashing algorithm being used (as specified in the header: HMAC, SHA256, or RSA)

Read more about JWT Validation.

Example signature

"keys": [
  {
    "alg": "RS256",
    "kty": "RSA",
    "use": "sig",
    "x5c": [
      "MIIC+DC..."
    ],
    "n": "yeNlz...",
    "e": "AQAB",
    "kid": "NjVBRj...",
    "x5t": "NjVBRj..."
  }
]