CA API Gateway 9.1

9.4 9.1

Decode JSON Web Token Assertion

The Decode JSON Web Token Assertion decodes a JSON Web Token by verifying the signature of a JWS, and/or decrypting a JWE message.
gateway83
The
Decode JSON Web Token Assertion
 decodes a JSON Web Token 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.
Output from the Create JSON Web Key Assertion cannot be used to decrypt a JSON Web Token.
Contents:
Assertion Logic
By design, the Decode JSON Web Token assertion does not stop or fail on detection of an invalid JWT signature. Rather, the verification results are recorded in the
$<prefix>.valid
 context variable (true/false) and policy processing continues. If you intend for the policy to fail, place a Compare Expression Assertion immediately after the Decode JSON Web Token assertion to check
${prefix}.valid
. Then, add logic to terminate the policy if that variable returns "false".
For a detailed description on implementing this workaround, see "Decode JSON Web Token Assertion Unaffected by Invalid JWT Signature" in Known Issues.
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
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: ${ }.

Content feedback and comments