Skip to content
CA API Gateway - 9.3
Documentation powered by DocOps

Decode JSON Web Token Assertion

Last update March 25, 2019

The Decode JSON Web Token Assertion decodes a JSON Web Token (JWT) by verifying the signature of a JWS, and/or decrypting a JWE message.

For a nested JWT (both signed and encrypted), use one Decode JSON Web Token assertion to decrypt, then pass the resulting payload ${<prefix>.plaintext} to a second Decode JSON Web Token assertion.

For more details, see the JWT specification.

Note: Output from the Create JSON Web Key Assertion cannot be used to decrypt a JSON Web Token.

Contents:

Context Variables

Stored with a variable prefixed as defined in field, Destination Variable Prefix.

  • ${<prefix>.valid}
  • ${<prefix>.type}
  • ${<prefix>.header.names}
  • ${<prefix>.header.XXX}

Set if JSON Web Token is a JWS:

  • ${<prefix>.payload}
  • ${<prefix>.signature}

Set if JSON Web Token is a JWE:

  • ${<prefix>.encrypted_key}
  • ${<prefix>.initialization_vector}
  • ${<prefix>.cipher_text}
  • ${<prefix>.authentication_tag}
  • ${<prefix>.plaintext}

Cluster Properties

None

Properties

Setting What You Should Know...
Source Payload Message/data to be signed and or decrypted. Enter an actual string value, or existing context variable holding the message/data to be signed and or decrypted. If there is a nested JWT (for example, signed and encrypted) the context variable is ${<prefix>.plaintext}.
Validation Method

Determines JWT validation:

  • None: No validation. The JWT is parsed to its individual parts.
  • Using Secret: Validate the JWT using the specified secret.
  • Use Recipient Key From List: Validate using a private key selected from the Recipient List. Use this option when decrypting with a Private Key.
  • Using Recipient Key From Context Variable: Validate using a key from a context variable. Use this option when validating signature with a Public Key.
  • Recipient Key Context Variable: Context variable holding the recipient key. Valid inputs:
    • Context variable pointing to a Base64 encoded public certificate

    • Context variable pointing to an X.509 Certificate (for example, when used together with Look up Trusted Certificate assertion)

    • Context variable pointing to a JSON Web Key or JSON Web Key Set

    • Actual JSON string that represents a JSON Web Key or JSON Web Key Set

  • Fail on invalid signature: Select this option to fail the assertion upon an invalid JWT signature. Clear this option to note the validation result in the ${<prefix>.valid} variable and then continue processing.

    Note: The "Fail on invalid signature" setting is available as of v9.2 CR3. Beginning with this release, new policies with the Decode JSON Web Token assertion have this option enabled by default. However policies created prior to v9.2 CR3 have this option disabled by default. If you expect the assertion to fail when an invalid JWT signature is detected, be sure to select this option for all previous policies. 

IMPORTANT: Validate against an expected algorithm to avoid JWT security vulnerabilities. For more information, see this article: https://connect2id.com/products/nimbus-jose-jwt/vulnerabilities

Key Type

Key type of the Recipient Key Context Variable: Certificate, JSON Web Key, or JSON Web Key Set.

This field is enabled when the Validation Method is "Using Recipient Key From Context Variable".

Key ID

The "kid" (key ID) parameter is used to match a specific key from the JSON Web Key Set. For more information, refer to RFC-7517.

This field is enabled when the Key Type is "JSON Web Key Set".

Example:

Using googleapis.com as an example, their "https://www.googleapis.com/oauth2/v3/certs" endpoint returns a JSON payload containing a JSON Web Key Set (JWKS).

{
  "keys": [
  {
    "kty": "RSA",
    "alg": "RS256",
    "use": "sig",
    "kid": "3405d0ec4edf60539acf73be64604d49a097189a",
    "n": "vBNfb9rmZLTwVpjoeT9lsLvzwl5rAVWGius9n2AFdibXlTaA_o...",
    "e": "AQAB"
  },
  {
    "kty": "RSA",
    "alg": "RS256",
    "use": "sig",
    "kid": "ac7ebbdff9e77669785f4c530fe2d4a6408bc98d",
    "n": "1L2jYqXcdvdxtY10zT3PTZyTxG_gIScRcSheHYsuRMfdsh40x...",
    "e": "AQAB"
  },
  {
    "kty": "RSA",
    "alg": "RS256",
    "use": "sig",
    "kid": "1838c3d30929ad5f8a84b124538d467dc612cd4f",
    "n": "sblvLT44RjceIc7_sxgOfKmy3Ddm81n4qtjzlFO-VZtampq...",
    "e": "AQAB"
  },
  {
    "kty": "RSA",
    "alg": "RS256",
    "use": "sig",
    "kid": "978ca4118bf1883b316bbca6ce9044d9977f2027",
    "n": "qpe-lPi7HVP8_SRqodC19iWDcYJ-5-wZbBxxxgszoPbphgN8...",
    "e": "AQAB"
  }
  ]
}


To verify the signature of a signed JSON Web Token (JWT) from Google:

  1. Extract the "kid" value from the header of the JWT header.
  2. Use it to identify the signing key from the JWKS. The key in the JWKS that matches the 'kid' of your JWS is used to verify the signature of the JWS.
Destination Variable Prefix Variable prefix for storing the resulting data. Variable name accepts any alphanumeric character. Do not enclose the variable with the standard context variable format: ${ }.
Was this helpful?

Please log in to post comments.