JSON Web Token Create Service (com.ibi.edaqm.XDJWTCreateTokenAgent)

Syntax:

com.ibi.edaqm.XDJWTCreateTokenAgent

Description:

This service creates, and optionally, signs a JSON Web Token, which is a means of representing claims to be transferred between two parties. See the specification in RFC7519.

The token consists of the following three parts:

Headers. Gathered as members of a JSON object.
Claims. Encoded as members of a JSON object. The claims are also called the token payload.
Signature (optional). Signature over the claims is a byte array.

The service generates a token in compact form. The three parts are serialized and separately encoded in Base64url, and then concatenated together with separating periods (.).

The resulting value can be embedded in an HTTP response later, for example by creating a Set-Cookie header.

Parameters:

The following tables describe the JSON Web Token Create Service parameters.

Main

Parameter	Description
Output Register	Name of a special register where the generated token will be stored. The generated token is stored in a special register. The output document is the input document.

Parameter

Description

Output Register

Name of a special register where the generated token will be stored.

The generated token is stored in a special register. The output document is the input document.

Headers

Parameter	Description
Type	The "typ" (type) header is used by JWT applications to declare the media type of this token. The Type (typ) header is often left empty. It can be set to JWT to declare this is a JSON Web Token.
Content Type	The "cty" (content type) header is used to convey structural information about the token. The recommended value is empty for regular tokens and JWT for tokens with a nested JWT as the payload. The recommended value for the Content Type (cty) header is empty for tokens with claims encoded as members of a JSON object.
Key Id Source	Specifies how the "kid" (key id) header is computed. This header identifies the signature key. An application can use that header value to retrieve the key to validate the signature. A Key Fingerprint requires a public key. The Key Id Source parameter determines how the kid header is created. Selecting None does not create a kid header. Choosing Key Alias sets the kid header to the value of the Key Alias. Selecting Key Fingerprint sets the kid header to the fingerprint of the public key associated with the signature private key. The Key Fingerprint option is not applicable when the signature algorithm uses a symmetric secret key. Choosing Key Id Parameter sets the kid header to the value of the Key Id parameter.
Key Id	Value of the "kid" (key id) header when the Key Id Source is Key Id Parameter, otherwise it is ignored. The Key Id Source parameter determines how the kid header is created. Selecting None does not create a kid header. Choosing Key Alias sets the kid header to the value of the Key Alias. Selecting Key Fingerprint sets the kid header to the fingerprint of the public key associated with the signature private key. The Key Fingerprint option is not applicable when the signature algorithm uses a symmetric secret key. Choosing Key Id Parameter sets the kid header to the value of the Key Id parameter.
Header Namespace	Special register namespace from which token headers will be taken. The Header Namespace is a way to create custom headers. Each register in that namespace will create a header of the same name. For example, if the Header Namespace is ns, the special register named ns.hdr1 will create a header named hdr1.

Note: The alg header is always included automatically in the token. The value is taken from the signature Algorithm.

Claims

Parameter	Description
Input Document Claims	When enabled, the input document is a JSON document containing claims to include in the token. The Input Document Claims can be enabled to indicate the input document is a JSON object containing claims to be included in the token. Declaring claims in a JSON input document is a way to create custom claims, including claims with non-string values.
Issuer	The "iss" (issuer) claim identifies the principal that issued the token. The Issuer, Subject, Audience, and JWT Id properties create standard claims.
Subject	The "sub" (subject) claim identifies the principal that is the subject of the token The Issuer, Subject, Audience, and JWT Id properties create standard claims.
Audience	The "aud" (audience) claim identifies the recipients that the token is intended for. The Issuer, Subject, Audience, and JWT Id properties create standard claims.
Expires In	The "exp" (expiration time) claim identifies the expiration time on or after which the token MUST NOT be accepted for processing. The optional value is a duration indicating how long the token remains valid after the creation time specified in the Issued At claim. The format is [xxh][xxm]xx[s], for example 1m30s is 90 seconds after the Issued At time. The actual value of the exp claim will be the sum of Issued At and Expires In. The Expires In property specifies how long the token remains valid after the creation time. The actual value of the exp claim will be the sum of the creation time and the Expires In duration. If the creation time is unknown, the current time is used.
Not Before	The "nbf" (not before) claim identifies the time before which the token MUST NOT be accepted for processing. The optional value is a duration indicating how long after the creation time (specified in the Issued At claim) the token becomes valid. The format is [xxh][xxm]xx[s], for example 1m30s is 90 seconds after the Issued At time. The actual value of the nbf claim will be the sum of Issued At and the Not Before values. The Not Before property specifies how long after the creation time the token becomes valid. The actual value of the nbf claim will be the sum of the creation time and the Not Before duration. If the creation time is unknown, the current time is used.
Create Timestamp	When selected, generates an "iat" (issued at) claim identifying the current time as the time at which the token was issued. This claim can be used to determine the age of the token. When the Create Timestamp property is enabled, the service generates an iat (Issued At) claim indicating the current time as the creation time. When Create Timestamp is disabled, the creation time is taken from the iat claim in the input document or the claim namespace. This can be useful to create a token with a fixed creation time. The value of the iat claim is a long integer representing the number of seconds from 1970-01-01T0:0:0Z UTC.
JWT Id	The "jti" (JWT ID) claim provides a unique identifier for the token. The value is a case-sensitive string. The Issuer, Subject, Audience, and JWT Id properties create standard claims.
Claim Namespace	Special register namespace from which token claims will be taken. The Claim Namespace is another way to create custom claims. Each register in that namespace will create a claim of the same name. For example, if the Claim Namespace is ns, the special register named ns.claim1 will create a claim named claim1.

Note: You must always include at least one claim, otherwise the token creation fails.

Signature

Parameter	Description
Algorithm	Digital signature or MAC algorithm. The supported signature or MAC algorithms are: HS256 HMAC using SHA-256 HS384 HMAC using SHA-384 HS512 HMAC using SHA-512 RS256 RSASSA-PKCS1-v1_5 using SHA-256 RS384 RSASSA-PKCS1-v1_5 using SHA-384 RS512 RSASSA-PKCS1-v1_5 using SHA-512 ES256 ECDSA using P-256 and SHA-256 ES384 ECDSA using P-384 and SHA-384 ES512 ECDSA using P-521 and SHA-512 PS256 RSASSA-PSS using SHA-256 and MGF1 with SHA-256 PS384 RSASSA-PSS using SHA-384 and MGF1 with SHA-384 PS512 RSASSA-PSS using SHA-512 and MGF1 with SHA-512 none No digital signature or MAC performed
Secret Key	Symmetric key to use with one of the HMAC signature algorithms. The string is converted to bytes using UTF-8 encoding. The symmetric key can be specified in the Secret Key parameter when the signature algorithm is HMAC. The value is a string that will be converted to a byte array with the UTF-8 encoding. Make sure the resulting byte array is long enough compared to the algorithm length counted in bits. For example, HS256 requires at least 32 bytes. It is also possible to find the symmetric key in a keystore. See the examples for a sample keytool command. The Secret Key or KeyStore Provider name and Key Alias are required, unless the generated token is unsigned.
KeyStore Provider	Provider for the keystore containing the signature key. The Secret Key or KeyStore Provider name and Key Alias are required, unless the generated token is unsigned.
Key Alias	Alias of the signature key in the keystore. The Secret Key or KeyStore Provider name and Key Alias are required, unless the generated token is unsigned.
Key Password	Password for the signature key. If left blank, the password for accessing the keystore will be used.

Note: For public key signature algorithms, the private is retrieved from a keystore using the specified key alias.

Edges

The following table lists the available edges that are returned by the JSON Web Token Create service (com.ibi.edaqm.XDJWTCreateTokenAgent).

Edge	Description
success	Operation was successful.
fail_parse	An iFL expression could not be evaluated.
fail_operation	Operation could not be completed successfully.

Example 1

Example 1 creates a minimal token. You must always include at least one claim. This token is unsigned. Parameters not listed have their default value.

Parameter	Parameter Value
Subject	user1
Create Timestamp	false
Algorithm	none

The generated token in the jwt special register is:

eyJhbGciOiJub25lIn0.eyJzdWIiOiJ1c2VyMSJ9.

This token decodes to the following:

{
 "alg": "none"
}.
{
 "sub": "user1"
}.
[no signature]

Notice the alg header is always present in the result.

Example 2

Example 2 creates a token with a standard header and custom headers. This token is signed.

Parameter	Parameter Value
Type	JWT
Key Id Source	Alias
Header Namespace	hdms
Algorithm	RS256
KeyStore Provider	jwtks
Key Alias	rsakey

Assume the special register hdrns.hdr1 has value val1 and hdrns.hdr2 has value val2. Also, assume jwtks is a keystore provider pointing to a keystore that contains an entry with alias rsakey holding an RSA private key.

The generated token in the jwt register looks like the following:

eyJoZHIyIjoidmFsMiIsImhkcjEiOiJ2YWwxIiwidHlwIjoiSldUIiwia2lkIjoicnNha2V5Ii
wiYWxnIjoiUlMyNTYifQ.eyJpYXQiOjE1ODAxNzIxMTl9.oU_-
mYjMMetT9vU5cmjFzXaBSxsOSMq3zCpuD7kM_d5-
c9cVkbzkVIl3_LVumwwu81Ma5ekDNC5pDwrdBstPlXPkGKu1pAM21BiNIlfMvWz
w-jdHXng9Z-
s7SVhwssRVgI_7Zm4AXKM_xdnDiYwWmaNnxXONW7bphNsYXEtYS61PrWRp
06P-ePZB_crLnZ6zwkMemVlEKjmVDh9jO6mNp0bnBv-
HfDjll6jEvHJSlx8fuGgN3P3NtFWGifM5kqSs_Lu4l1yXNkdsKoJRa44VKaO036DP
pzpBS_vqZvJ50agDFNx43UIuiRgbdllpvMTjNX1Ug-MP9qWebAMNCHfUew.

This token decodes to the following:

{
 "hdr2": "val2",
 "hdr1": "val1",
 "typ": "JWT",
 "kid": "rsakey",
 "alg": "RS256"
}.
{
 " iat": 1580172119
}.
[signature]

Notice the kid header value is the key alias and the iat claim is the current time.

Example 3

Example 3 creates a token with some standard claims and custom claims coming from the input JSON document.

Parameter	Parameter Value
Input Document Claims	true
Issuer	org1
Subject	user1
Expires In	3600
Not Before	120
Algorithm	ES256
KeyStore Provider	jwtks
Key Alias	es256key

Assume jwtks is a keystore provider pointing to a keystore that contains an entry with alias es256key, holding an ECDSA private key.

Assume the input document is:

{"claim1":1,"claim2":true}

The generated token in the jwt register looks like the following:

eyJhbGciOiJFUzI1NiJ9.eyJjbGFpbTEiOjEsImNsYWltMiI6dHJ1ZSwiaXNzIjoib3Jn
MSIsInN1YiI6InVzZXIxIiwiaWF0IjoxNTgwMTc0Mjc0LCJleHAiOjE1ODAxNzc4Nz
QsIm5iZiI6MTU4MDE3NDM3NH0.Om11JE_7uSJlODcpiSY8x67957kwRSW-
YnYYyuMqWYu7BedB-_fMSKfwpRD8MXgvJxp5jnq2QvMjXjau_0oSeg

This token decodes to the following:

{
 "alg": "ES256"
}.
{
 "claim1": 1,
 "claim2": true,
 "iss": "org1",
 "sub": "user1",
 "iat": 1580174274,
 "exp": 1580177874,
 "nbf": 1580174374,
}.
[signature]

This token becomes valid in two minutes and expires 1h from now. Notice the custom claims in the input document do not have to be strings.

Example 4

Example 4 creates a token with some claims coming from the Claim Namespace. The symmetric key for the HMAC algorithm is specified with a passphrase in the Secret Key parameter. The output is in a different special register than the default.

Parameter	Parameter Value
Output Register	jwttoken
Claim Namespace	claimns
Algorithm	HS256
Secret Key	mySecretPassphrase12345678901234

Assume the special register claimns.subject has value user1 and claimns.claim1 has value val1.

The generated token in the jwttoken special register looks like the following:

eyJhbGciOiJIUzI1NiJ9.eyJzdWJqZWN0IjoidXNlcjEiLCJjbGFpbTEiOiJ2YWwxIiwi
aWF0IjoxNTgwMjIxODM3fQ.7w9S63MCDmAUB2146Z6PhAkSsa4TnlhbqntP_47
3-go

This token decodes to the following:

{
 "alg": "HS256"
}.
{
 "subject": "user1",
 "claim1": "val1",
 "iat": 1580175501,
}.
[signature]

Claims created from special registers are always strings.

Example 5

Example 5 shows sample commands to create various keys with keytool.

For the HS256 algorithm (adjust the keysize to 384 for HS384 or 512 for HS512):

keytool -genseckey -alias hs256key -keyalg HmacSHA256 -keysize 256 -
keystore jwt.p12 -storetype PKCS12

For all RSA algorithms (RS256, RS384, RS512, PS256, PS384, and PS512), the minimum keysize is 2048:

keytool -genkeypair -alias rsakey -keyalg RSA -keysize 2048 -validity 730 -
keystore jwt.p12 -storetype PKCS12

For the ES256 algorithm (adjust the keysize to 384 for ES384 and 521 for ES512, notice for ES512 the key size is 521 not 512):

keytool -genkeypair -alias es256key -keyalg EC -keysize 256 -validity 730 -
keystore jwt.p12 -storetype PKCS12