Syntax:
com.ibi.edaqm.XDJWTVerifyTokenAgent
Description:
This service decodes and verifies 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:
The service expects a token in compact form, which consists of three parts encoded in Base64url encoding separated with periods (.).
Parameters:
The following tables describe the JSON Web Token Verify Service parameters.
Main
|
Parameter |
Description |
|---|---|
|
Token |
Token to validate. |
|
Output Document |
Output Document can be the input document, the payload parsed as JSON, or the flat payload. |
|
Required Issuer |
When present, the issuer that must appear in the iss claim, otherwise the token validation fails When the Required Issuer is present, the service checks that the iss header contains the same value, otherwise the validation fails. Leave the value empty to ignore that check. |
|
Header Namespace |
Special register namespace into which token headers will be saved. The Header Namespace is a special register namespace into which token headers will be saved. For example, if the Header Namespace is hdrns and there is a header named alg with value RS256, this will create a special register named hdrns.alg with value RS256. When the Header Namespace is absent, the headers are not accessible. |
|
Claim Namespace |
Special register namespace into which claims will be saved. This is the only way to access the claims if the Output Document is the Input Document. The Claim Namespace is a special register namespace into which claims will be saved. For example, if the Claim Namespace is claimns and there is a claim named sub with value user1, this will create a special register named claimns.sub with value user1. When the Claim Namespace is absent, the claims are not saved in special registers, but they may be accessible in the output document depending on the Output Document parameter. |
|
Clock Skew |
Sets the amount of clock skew in seconds to tolerate when verifying the local time against the exp and nbf claims. The Clock Skew is the number of seconds to tolerate when verifying the local time against the exp (Expiration) and nbf (Not Before) claims. |
Signature Validation
|
Parameter |
Description |
|---|---|
|
Accepted Algorithms |
Comma-separated list of acceptable signature algorithms. The verification will fail if the value of the token alg header is not in this list. This can enforce the use of more secure algorithms with longer key sizes, and very importantly, reject unsigned tokens when none is not in the list. 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 |
|
Key Resolver |
Specifies how the validation key is resolved. Secret Key always uses the same symmetric key specified with the Secret Key parameter. Fixed always uses the same key specified with the Validation Key Alias. Key Alias uses the alias in the kid header to retrieve the key from the keystore. Key Fingerprint uses the fingerprint in the kid header to retrieve the matching key from the keystore. None does not define a Key Resolver and therefore can only verify unsigned tokens. The Key Resolver property specifies how the validation key is resolved. None does not define a Key Resolver and therefore can only verify unsigned tokens. Select Secret Key to always use the same symmetric key specified with the Secret Key parameter. Select Fixed to always use the same key specified with the Validation Key Alias. The remaining two options select the validation key depending on the value of the kid (Key Id) header in the token. This is useful if the token generation uses different keys depending on the service being secured or the partner receiving the token. Select Key Alias if the value of the kid header is the alias of the key in the keystore. Select Key Fingerprint to retrieve the public key with the matching fingerprint in the keystore. |
|
Secret Key |
Secret key to use as the fixed symmetric validation key. The string is converted to bytes using UTF-8 encoding. For symmetric algorithms like HMAC, the validation key is the same secret key used for signing. For asymmetric algorithms like RSA and ECDSA, the validation key must resolve to a public key. This can be a trusted certificate entry in the keystore, or a private key entry, as long as that entry also contains the corresponding certificate. |
|
KeyStore Provider |
Provider for the keystore containing the validation key. |
|
Validation Key Alias |
Alias of the validation key in the keystore when the Key Resolver is Fixed. |
|
Validation Key Password |
Password for the validation key. If left blank, the password for accessing the keystore will be used. |
Edges
The following table lists the available edges that are returned by the JSON Web Token Verify service ( com.ibi.edaqm.XDJWTVerifyTokenAgent).
|
Edge |
Description |
|---|---|
|
success |
Token validated successfully. |
|
fail_parse |
An iFL expression could not be evaluated. |
|
fail_operation |
Operation could not be completed successfully. |
|
fail_verify |
Token validation failed. |
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 |
|---|---|
|
Token |
_sreg(jwttoken) |
|
Output Document |
json |
|
Accepted Algorithms |
HS256 |
|
Key Resolver |
secretkey |
|
Secret Key |
mySecretPassphrase12345678901234 |
Assume the special register jwttoken has the value:
eyJhbGciOiJIUzI1NiJ9.eyJzdWJqZWN0IjoidXNlcjEiLCJjbGFpbTEiOiJ2YWwxIiwi aWF0IjoxNTgwMjIxODM3fQ.7w9S63MCDmAUB2146Z6PhAkSsa4TnlhbqntP_47 3-go
The service returns these parsed claims in the output document:
{
"subject": "user1",
"claim1": "val1",
"iat": 1580175501,
}The token headers are not accessible since the Header Namespace is not defined.
Example 2
Example 2 validates a signed token, using a fixed validation key.
|
Parameter |
Parameter Value |
|---|---|
|
Token |
_sreg(jwttoken) |
|
Output Document |
json |
|
Header Namespace |
hdms |
|
Accepted Algorithms |
RS256 |
|
Key Resolver |
fixed |
|
KeyStore Provider |
jwtks |
|
Key Alias |
rsakey |
Assume jwtks is a keystore provider pointing to a keystore that contains an entry with alias rsakey. This can be a trusted certificate entry for an RSA public key or a private key entry holding an RSA private key and its associated certificate.
Assume the special register jwttoken has the following value:
eyJhbGciOiJSUzI1NiJ9.eyJzdWIiOiJ1c2VyMSJ9.AlEH- FXPWteGNk3nOeHmBYCE_1j3OPIyQ9zlYLAjnFkCr_kPoXp1N9EdwSiTtYDK7P ECvy4V6eozVllOvXklLA_azeew7A9P0lVnFAude5bK_4O2gI6h63QhIk3SFUOx5 4O2gI6h63QhIk3SFUOx5NFc7W7Hn_Xlb7c8qyNPoo6WqyFsbB- aBWXcvFutEm9TQb1PpkAiPCgNXA0MwPNWKBvl4tpM6OI- EURHDJhekcj_QhTSEq8S0k7yLdFg1zeWuBDGSWhu4AwqnVFttN6XexO9Pbv4 V2eK1OSyaMInSaoHWTNXCPjFBQLXvhv- mqLAVvRciep6HJfkZuOWj5VvCsXJaPQMJj1FI27zNvt2KA
The service returns these parsed claims in the output document:
{
"sub": "user1"
}The special register hdrns.alg will be assigned the value RS256. Since the validation key is hardcoded, the kid (Key Id) header can be absent.
Now assume the special register jwttoken has the following value:
eyJhbGciOiJub25lIn0.eyJzdWIiOiJ1c2VyMSJ9
The service returns an error document and follows the fail_verify edge because the token is unsigned.
Example 3
Example 3 validates a signed token using a Key Resolver accepting only ECDSA algorithms.
|
Parameter |
Parameter Value |
|---|---|
|
Token |
_sreg(jwttoken) |
|
Output Document |
input |
|
Required Issuer |
org1 |
|
Header Namespace |
hdms |
|
Claim Namespace |
claimns |
|
Accepted Algorithms |
ES256, ES384, ES512 |
|
Key Resolver |
alias |
|
KeyStore Provider |
jwtks |
Assume jwtks is a keystore provider pointing to a keystore that contains the validation keys. Since this example only accepts ECDSA signatures, the entries must be trusted certificate entries for ECDSA public keys and/or private key entries holding ECDSA private keys with their associated certificates.
Assume the special register jwttoken has the value:
eyJhbGciOiJFUzI1NiJ9.eyJpc3MiOiJvcmcxIiwic3ViIjoidXNlcjEifQ.7dImMsWunbF kZkfWC3dZhG-z9fruQEsudFxmQxJvjDaz3dlW6B6l-RE9FYq48Ley6wsR- ohqfqvRb1MldK8MaQ
The service returns the contents of the input document in the output document, but otherwise ignores it.
These special registers will be assigned the following values:
hdms.kid - es256key
hdrns.alg - ES256
claimsns.iss - org1
claimsns.sub - user1
The value of the iss claim is accepted because it is equal to the Required Issuer.
The service interprets the value of the kid (Key Id) header as a key alias and it resolves the validation key by retrieving the entry with alias es256key in the keystore.
Example 4
Example 4 validates a signed token with a plaintext payload, using a fingerprint Key Resolver.
|
Parameter |
Parameter Value |
|---|---|
|
Token |
_sreg(jwttoken) |
|
Output Document |
flat |
|
Header Namespace |
hdms |
|
Accepted Algorithms |
RS256, RS384, RS512, PS256, PS384, PS512 |
|
Key Resolver |
fingerprint |
|
KeyStore Provider |
jwtks |
Assume jwtks is a keystore provider pointing to a keystore that contains the validation keys. Since this example only accepts RSA signatures, the entries must be trusted certificate entries for RSA public keys and/or private key entries holding RSA private keys with their associated certificates.
Assume the special register jwttoken has the following value:
eyJraWQiOiIxYjhhYWE0N2JhNzE4MDVmOTc2NzU1MGRjMzc5ODkzOTI4MTM 5Mzg4IiwiYWxnIjoiUlMyNTYifQ.VGhpcyBpcyBhIHBsYWludGV4dCBjbGFpbQ0K. XIyb1XPzLQVJJQX501RxVN-haRpF2ANsHQ3CTGG3DwsyOh3tpO-b2B0Fz- uMzek2rPrqqzc_ZC7ONOdxhYsPKbLABlpVdE728Ow1XUE1WFZn1MBhdnnOLl muC5M7TyMtfU3N- CeYQ_yf3_brb5hMeEndZHSVp_ThFTPXxqsTAA_CrxdprvQRS9eat1- bPGdf7R72DTt8Iw6aYrR3YyELDFgF8-PcKQsEm- 3t3ZjxOps9R1zFF91b0alSG2FUgO97fFBlYusJsq5NIaOZ78j- QuUYNp1eUXe5Uh9Zlk8nNJsAtm_prCdI7tmom2RVUH2kyBj1gKA- 4EKSNlIKAmDLbA
The output document will be the flat data:
This is a plaintext claim
These special registers will be assigned the following values:
hdms.kid - 1b8aaa47ba71805f9767550dc379893928139388
hdrns.alg - RS256
The service interprets the value of the kid (Key Id) header as a key fingerprint. It enumerates the entries in the keystore until it finds a public key with a matching fingerprint.