JWT Creator

Official Content
This documentation is valid for:

Note: This is part of the GeneXus JWT Module and provides functions to create, verify, and retrieve useful information from a token..

Valid Key Formats

  • Encoded Base64 key PKCS8 formatted (.pem extension). It can contain a public key, private key or both.  
    • Encrypted .pem files are not admitted.
    • Encrypted PKCS8 private keys are admitted since GeneXus 17 Upgrade 2
    • Files with .key extensions are supported since GeneXus 16 Upgrade 11
  • DER certificate (.crt or .cer extension). It contains only public keys.
  • PKCS12 certificate or keystore (.p12 or .pfx or .jks extension). It contains only private keys or both.
    • JKS format (JavaKeyStore) is available only for Java implementation.
    • For PKCS12 certificates the file password is needed for both Java and .Net implementations.
    • .Net implementation does not use the PKCS12 alias; it takes the public key from the first certificate on the certificate chain and the first default private key listed on the file.
    • Files with .pkcs12 extensions are supported since GeneXus 16 Upgrade 11
  • Every certificate must implement the X509 standard.

Available signature algorithms:

  • Asymmetric
    • RSA with
      • SHA1
      • SHA256
      • SHA512
    • .Net implementation-specific: it does not support RSA key lengths shorter than 1024 bits.
  • Symmetric
    • HMACWithSha256
    • HMACWithSha512

DoCreate

Creates JWT tokens.

  • If a symmetric algorithm is provided, it will use the secret indicated in the options.
  • If an asymmetric algorithm is provided, it will use the PrivateKey and Certificate preloaded in the options. 
  • It adds all the Registered and Public Claims declared in the options.
DoCreate(algorithm, privateClaims, options)
  • Input algorithm: JWTAlgorithm domain data
  • Input pivateClaims: PrivateClaims type data
  • Input options: JWTOptions type data
  • Returns signed JWT with the algorithm indicated using keys from the options.

Example:

&token=&JWT.DoCreate(JWTAlgorithm.HS256, &PrivateClaims, &JWTOptions)

DoCreateFromJSON

This method is available since GeneXus 18

Creates JWT tokens using a JSON payload.

  • If a symmetric algorithm is provided, it will use the secret indicated in the options.
  • If an asymmetric algorithm is provided, it will use the PrivateKey and Certificate preloaded in the options. 
  • It adds all the Registered and Public Claims declared in the options.
DoCreateFromJSON(algorithm, payload, options)
  • Input algorithm: JWTAlgorithm domain data
  • Input payload: VarChar(9999) String JSON
  • Input options: JWTOptions type data
  • Returns signed JWT with the algorithm indicated using keys from the options.

Example:

&payload = '{"sub":"subject1","aud":"audience1","nbf":1594116920,"hola1":"hola1","iss":"GXSA","hola2":"hola2","exp":1909649720,"iat":1596449720,"jti":"0696bb20-6223-4a1c-9ebf-e15c74387b9c, 0696bb20-6223-4a1c-9ebf-e15c74387b9c"}'
&secret = &keyGen.DoGenerateKey(SymmetricKeyType.GENERICRANDOM, 256)
&JWTOptions.SetSecret(&secret)

&token=&JWT.DoCreateFromJSON(JWTAlgorithm.HS256, &payload, &JWTOptions)

DoVerify

Verifies JWT tokens.

  • Automatically verifies the revocation list if it exists in the options.
  • If a symmetric algorithm is provided, it will use the secret indicated in the options.
  • If an asymmetric algorithm is provided, it will use the Certificate preloaded in the options. 
  • It validates all the Registered and Public Claims declared in the options.
  • It validates the header parameters since GeneXus 16 Upgrade 11
DoVerify(token, algorithm, privateClaims, options)
  • Input token: VarChar(256) 
  • Input algorithm: JWTAlgorithm domain data (mandatory parameter auditioned since GeneXus 16 upgrade 10 as security measure)
  • Input pivateClaims: PrivateClaims type data. If the object is empty, it will not try to validate them and will return true if the other token information is valid.
  • Input options: JWTOptions type data
  • Returns: Boolean true if the token verifies the signature and other parameters indicated in the options.

Example:

&verifies=&JWT.DoVerify(&token, JWTAlgorithm.RS256, &PrivateClaims, &JWTOptions)

DoVerifySignature

This method is available since GeneXus 17

Verifies JWT tokens.

  • Automatically verifies the revocation list if it exists in the options.
  • If a symmetric algorithm is provided, it will use the secret indicated in the options.
  • If an asymmetric algorithm is provided, it will use the Certificate preloaded in the options. 
  • It does not verify Private claims or header parameters. It is up to you which ones to verify using your own verification method.
  • It does verify the token´s Registered Claims against the configured on the given JWTOptions.
DoVerifySignature (token, algorithm, options)
  • Input token: VarChar(256) 
  • Input algorithm: JWTAlgorithm domain data as a security measure.
  • Input options: JWTOptions type data
  • Returns: Boolean true if the token verifies the signature and Registered claims indicated in the options.

Example:

&verifies=&JWT.DoVerifySignature(&token, JWTAlgorithm.RS256, &JWTOptions)

DoVerifyJustSignature

This method is available since GeneXus 17

Verifies JWT tokens.

  • Automatically verifies the revocation list if it exists in the options.
  • If a symmetric algorithm is provided, it will use the secret indicated in the options.
  • If an asymmetric algorithm is provided, it will use the Certificate preloaded in the options. 
  • It does not verify any claims or header parameters. It is up to you which ones to verify using your own verification method.
  • As for Java implementation, the library forces the time validating claims against the machine´s current time. On .Net and Net Core implementation, none of the claims are validated.
DoVerifyJustSignature (token, algorithm, options)
  • Input token: VarChar(256) 
  • Input algorithm: JWTAlgorithm domain data as a security measure.
  • Input options: JWTOptions type data
  • Returns: Boolean true if the token verifies the signature.

Example:

&verifies=&JWT.DoVerifyJustSignature(&token, JWTAlgorithm.RS256, &JWTOptions)

GetPayload

Returns the payload content in a JSON formatted string.

GetPayload(token)
  • Input token: VarChar(256)
  • Returns VarChar(256) string JSON

Example:

&payload=&JWT.GetPayload(&token)

GetHeader

Returns the header content in a JSON formatted string.

GetHeader(token)
  • Input token: VarChar(256)
  • Returns VarChar(256) string JSON

Example:

&header=&JWT.GetHeader(&token)

GetTokenID

Returns the GUID alphanumeric token identification from the jti registered claim.

GetTokenID(token)
  • Input token: Character(100)
  • Returns VarChar(256) alphanumeric GUID

Example:

&id=&JET.GetTokenID(&token)

Security tips

  • When assigning file paths, do not use user input concatenations or sanitize user entries to avoid path traversal or path manipulation vulnerability risks.