Encode JSON Web Token Assertion

The Encode JSON Web Token assertion creates a compact, URL-safe message as a JSON Web Token (JWT) that is represented using the JWS  or JWE Compact Serialization. Specifically, this assertion:
gateway83
The
Encode JSON Web Token
assertion creates a compact, URL-safe message as a JSON Web Token (JWT) that is represented using the JWS  or JWE Compact Serialization. Specifically, this assertion:
  • Takes any message as a payload from a context variable
  • Signs and or encrypts the content (in this order)
  • Stores the JWT in a context variable
Contents:
Support
  • Compact Serialization representation of the JSON Web Token is supported; JSON serialization is not.
  • You cannot dynamically encrypt/decrypt using a private key. However, you can decrypt using a static configuration.
  • Any message string type is supported (not only JSON Claims set string)
  • Supported Elliptic Curve Keys
    • Elliptic Curve – P-256
    • Elliptic Curve – P-383
    • Elliptic Curve – P-521
Both JSON Web Tokens and XML-formatted SAML Tokens are used for authentication. JWT is suited for mobile devices because of its simplified structure. Although SAML Tokens have many encryption and signature options, mobile devices cannot easily parse its XML-format and complex structure. If you are using OAuth2 and OpenID Connect for mobile implementations, JSON Web Tokens are the new standard.
 
Encoded JSON Web Token Examples
In the examples below, line breaks have been added for readability.
JWS Compact Serialization Example
eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9 . cGF5bG9hZA . j40K-NPxQCfwECQJp2a1_VQWpZTscq9sDp_hDRKo8tdo-SJr8Z07IcswHVuK3UYkk9Mk6r8TIc1dpGY5uCz2awOknQA15QrDg
Where:
BASE64URL(UTF8(JWS Protected Header)) || '.' || BASE64URL(JWS Payload) || '.' || BASE64URL(JWS Signature)
JWE Compact Serialization Example
eyJ0eXAiOiJKV1QiLCJjdHkiOiJKV1QiLCJhbGciOiJSU0EtT0FFUCIsImVuYyI6IkExMjhDQkMtSFMyNTYifQ . QoQsjC5WtYbOeaZa8NXaUtVNdwZJPIhZilG3qVzk6oB7ks9g_ZyYwLKlqVKLbm63C7GPCDGlN11wqTr6Vs7tGqD4vthPfo0xdkUv0DXwn32TbRHPff-j9sywn8zeJnyI4nD8ZrW69B6Do6zu3F1PoDVUWs2fVL_g . kLk14Z3EWiB7rAXQouRCSg . uaH8otrOcRt0_DmqIfg1bL8VVMvrBLVvCW0UnR-75lzK-yvMPeMTvgUw4FbNElmMiU3_3WE5w6Z_3KUs7twoXWITNwviijhLqOFwuNGevBnP-V6BQDBcJpUWDHaz81vicKbQjGsbQoKD2pC-z8pjyCBJa-VogDYN7E22ZK59pFA0H7tCgW . HDFVboSUFT8pDLMGwKPLcg
Where:
BASE64URL(UTF8(JWE Protected Header)) || '.' || BASE64URL(JWE Encrypted Key) || '.' || BASE64URL(JWE Initialization Vector) || '.' || BASE64URL(JWE Ciphertext) || '.' || BASE64URL(JWE Authentication Tag)
 
Context Variables
This assertion populates the following variable:
Variable
Description
$
{
<prefix>
.compact
}
Returns the compact representation of the JSON Web Token.
Cluster Properties
jwt.showAlgorithms
This property determines which algorithms are displayed. The default setting 'false' displays only tested signatures. Set this to 'true' to display to display
all
algorithms, including the untested ones.  
CA Technologies does not support the use of untested algorithms on the Gateway. Use at your own risk. You may need to install additional libraries to enable these algorithms.
JWS Signature Algorithms
  • RSASSA-PSS using SHA-256 and MGF1 with SHA-256
  • RSASSA-PSS using SHA-384 and MGF1 with SHA-384
  • RSASSA-PSS using SHA-512 and MGF1 with SHA-512
JWE
  • Key Management Algorithms
    :
    • Key wrapping with AES GCM using 128-bit key
    • Key wrapping with AES GCM using 192-bit key
    • Key wrapping with AES GCM using 256-bit key
  • Content Encryption Algorithms
    :
    • AES GCM using 128-bit key
    • AES GCM using 192-bit key
    • AES GCM using 256-bit key
If the above algorithms require additional third-party .jars, follow these steps to install them:
  1. Using SCP or SFTP, copy the necessary client libraries to the Gateway as the
    ssgconfig
    user.
  2. Open a privileged shell on the Gateway.
  3. Change the permissions and ownership of the client libraries with these commands:
    # chmod 444 /home/ssgconfig/*.jar
    # chown layer7.layer7 /home/ssgconfig/*.jar
  4. Move the client libraries from:
    /home/ssgconfig
    to:
    /opt/SecureSpan/Gateway/runtime/lib/ext
  5. Restart the Gateway.
Properties
Data is encoded based on the configuration of the tabs.
  • If JWS and JWE tabs are not configured (
    Sign Payload
    and
    Encrypt Payload
    check boxes are not selected), the result is a non-secure JWT.
  • When both JWS and JWE are configured, the payload is signed, then encrypted.
General Tab
The General tab configures the basics of the encoding: source and destination variables, behavior of the header.
Option
What you should know...
Source Payload
Message/data to be signed and or encrypted. Enter an actual string value, or an existing context variable holding the message/data to be signed and or encrypted.
Headers
Use Generated Header
: Use the headers created by the assertion.
  • JWS generated header fields: "typ" and "alg"
  • JWE generated header fields: "typ" and "alg" and "enc"
  • Nested JWT generated header fields: "typ" and "cty" and "alg" and "enc"
Merge to Generated Header
: Merge the headers created by the assertion with any headers specified in the adjacent field. If you specify a header that is a duplicate of an existing header, the existing header is overwritten. Accepts a JSON string as the new input or from a context variable. For example, {"cty":"text/plain"}.
Replace Generated Header
: Replace the headers created by the assertion with any headers specified in the adjacent field. Accepts a JSON string as the new input or from a context variable. For example, {"cty":"text/plain"}.
When you use replacements values, the algorithms for the header are abbreviated. See the JWT specification documentation for help. When you replace a Header with an algorithm that does not match the selected algorithm, the value in the header always takes precedence and overwrites the existing value.
Destination Variable Prefix
A prefix that is added to the context variables populated by this assertion.
JWS Tab
The JWS tab configures the signing of the payload.
Option
What you should know...
Sign Payload
Sign/do not sign the payload.
Output from the Create JSON Web Key Assertion cannot be used to sign the payload.
Signature Algorithm
Select the algorithm to use to sign the payload.
CA Technologies strongly recommends using HMAC or ECDSA algorithms whenever possible. Use the RSASSA algorithms only when absolutely necessary for interoperability.
Key lengths for HMAC algorithms:
  • HMAC Using SHA-256
    : Use a key of equal length of 256 bits or greater (32 characters in UTF-8)
  • HMAC Using SHA-384
    : Use a key of equal length of 384 bits or greater (48 characters in UTF-8)
  • HMAC Using SHA-512
    : Use a key of equal length of 512 bits or greater (64 characters in UTF-8)
Secret
Available when an HMAC signature is selected. A secret can contain actual input or a context variable.
If you specify a context variable for a secret pointing to a password stored in Stored Password Properties.
Show Secret
Make the secret visible onscreen.
Is Base64 Encoded
Select this if the secret is Base64 encoded.
Private Key
When this option is available, use it to select a private key to use for signing..
Key From Context Variable
Select this option to specify a JWK (JSON Web Key) or JWKS (JSON Web Key Set). Valid inputs:
  • Raw JSON string input for a JWK or JWKS
  • Context variable that contains the JWK or JWKS
If using HMAC signature algorithms, specify a context variable that contains a JWK/JWKs formatted shared key. If using anything other than HMAC signature algorithms (asymmetric algorithms), enter a context variable that contains a JWK/JWKs formatted private key.
Key Type
The type of key being used:
JSON Web Key
or
JSON Web Key Set
.
Key ID
The key ID when using a JWKS.
JWE Tab
The JWE tab is used to configure the encryption of the payload.
Option
What you should know...
Encrypt Payload
Select to encrypt the payload. If not encrypting, then all controls in this tab are disabled.
You can use output from the Create JSON Web Key Assertion to encrypt the payload.
Key Management Algorithm
The key management mode for the JWE. Used as the value for the "alg" header. The generated "alg" header contains the name of the selected Key Management Algorithm.
Secret
Available when a symmetric key algorithm is selected. A secret can contain actual input or a context variable.
If you specify a context variable for a secret pointing to a password stored in Stored Password Properties.
Show Secret
Make the secret visible onscreen
Key From Context Variable
The source with the public key for encrypting the data. Valid inputs:
  • Context variable pointing to a PEM Base64 encoded public key
  • Context variable pointing to an X.509 Certificate (for example, when used with Look up Trusted Certificate assertion)
  • Actual JSON string that represents a JSON Web Key or JSON Web Key Set
  • Context variable pointing to a JSON Web Key or JSON Web Key Set
  • If using
    Direct use of a shared symmetric key as the Content Encryption Key (CEK)
    , enter a context variable pointing to a JWK/JWKs formatted shared key.
  • If using an algorithm other than Direct use of a shared symmetric key as the Content Encryption Key (CEK), enter a context variable pointing to a JWK/JWKs formatted public key.
Key Type
Specify the type of recipient public key:
Certificate
,
JSON Web Key
, or
JSON Web Key Set
.
Key ID
The JSON Web Key Set ID when using a JWKS.
Content Encryption Algorithm
Encryption algorithm that is used as the value for the "enc" header. The generated "enc" header value contains the name of the selected Content Encryption Algorithm.
If you select 
Direct use of a shared symmetric key as the Content Encryption Key (CEK)
as the Key Management Algorithm, these keys have the following requirements:
  • AES 128 CBC HMAC SHA-256:
    key exactly equal to 256 bits long is required (32 characters in UTF-8) 
  • AES 256 CBC HMAC SHA-512:
    key exactly equal to 512 bits long is required (64 characters in UTF-8)