JWT validation

When Trimble Identity returns an ID token to an application, the application must validate the signature to prove the token authenticity and validate a few claims in the token to verify its validity.

Identity uses JSON Web Key to distribute public keys to verify JSON Web Tokens (JWTs). The API endpoint allows clients to retrieve a JWKs, so clients can select an appropriate key for whatever JWTs are presented to them.

The verifying algoritm used by Trimble Identity is RS256.

How it works

1. Retrieve the JSON Web Key Set
2. Verify the Token’s Signature
3. Match JWKS to Verify JWTs

Retrieve the JSON web key set

Below are the endpoints to retrieve the JSON Web Key Sets (JWKS) for Identity. Your application should have JWKS cached for verification. Here are the endpoints: Production | Stage

Verify the token’s signature

Once you have Identity’s JWKS cached, you verify an ID token’s signature by matching the key used against one of Trimble Identity’s JWKS. Each public key is identified by a Key Identifier attribute, or kid, which corresponds with the “kid” claim in the ID token header.

If the kidclaim does not match, it is possible that the signing keys have changed. Try retrieving the keys again from Identity from one of these environments: Production or Stage

Example of the JWKS from Trimble Identity

Parameters from Trimble Identity’s JWK

• alg = Identifies the specific algorithm
• kty = Identifies the family of algorithms used with the key
• kid = Key Identifier used to identify the expected key (JWK) used to sign the JWT
• use = Represents usage – ‘sig’ for signing keys, ‘enc’ for encryption keys
• x5t = X.509 Certificate Thumbprint – Used to identify specific certificates
• x5c = X.509 chain of certificates used for verification. The first entry in the array is always the cert to use for token verification
• n = The modulus value of the public key
• e = The exponent value of the public key

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

Match JWKS to verify JWTs

From the JWKS, match the collected parameters to get the public Key ‘x5c’ parameters from the list. Use the found public key for signature verification; if the key is not found try refreshing the JWKS URI list.

Example:

{
  "keys": [
    {
      "kty": "RSA",
      "n": "yrALP...",
      "e": "AQAB",
      "kid": "rsa1",
      "use": "sig",
      "x5t": "YmE3Mz...",
      "alg": "RS256",
      "x5c": ["MIICCz..."]
    },
    {
    "kty": "RSA",
    "n": "yrALP...",
    "e": "AQAB",
    "kid": "YmE3Mz...",
    "use": "sig",
    "x5t": "YmE3Mz...",
    "alg": "RS256",
    "x5c": ["MIICCz..."]
    }
 ]
}