jwtDecode()

Synopsis

string jwtDecode(string jwt, string key [, string algorithm] [, bool
                ignoreSignature = false]);

Parameters


Parameter	Description
jwt	The JWT token.
key	The key, which was used to sign the JWT token.
algorithm	The optional parameter specifying the expected signing algorithm used to decode the JWT. Decoding will only work if these algorithms match. Possible values and the default value are the same as for jwtEncode(). Similarly, the use of "RSxxx" values means that the key must contain the public RSA key matching the private RSA key used for signing.
ignoreSignature	Decides if the signature is used or not.

Details

The function returns the payload contained in the string "jwt", if it has been signed with "key" using the signing algorithm "HS256". In the event of problems (e.g.: invalid signature, wrong key, incorrectly encoded token), an empty string is returned. The error details can be read with getLastError().

If the parameter "ignoreSignature" is set to "true", the payload of the JWT token is returned even if the key is wrong (or just an empty string). If this flag is set, the function does not check whether the JWT token contains valid information or has been manipulated, so the information in the payload cannot be trusted.

"algorithm":

Although the JWT header contains the name of the algorithm that was used for signing, this alone is not sufficient to securely determine the signing algorithm used, because attackers could modify this information and create a token signed with a different algorithm. For backwards compatibility, all the following combinations of parameters are valid:

jwtDecode(jwt, key);
jwtDecode(jwt, key, ignoreSignature);
jwtDecode(jwt, key, algorithm);
jwtDecode(jwt, key, algorithm, ignoreSignature);

For "RSxxx" algorithms, a RSA public/private key pair is needed. These will normally be read from a file, e.g.:

string priKey, pubKey;
fileToString(getPath(DATA_REL_PATH, "jwt_private_key.pem"), priKey);
fileToString(getPath(DATA_REL_PATH, "jwt_public_key.pem"), pubKey);

string jwt = jwtEncode(payloadToEncode, priKey, "RS256");
string payload = jwtDecode(jwtToDecode, pubKey, "RS256");

CAUTION:

In a production system, the private key must not be stored within the project directory structure.

When using one of the RSxxx algorithms, jwtDecode() accepts the key parameter in these formats:

PKCS #8 (as before, typically PEM Base64 encoded)
JWK (JSON Web Key, as JSON string)
JWKS (JSON Web Key Set, one or more JWKs)

All key types are passed to the function as (possibly multiline) strings, which are recognized automatically. JWKS (JSON Web Key Set) is only accepted by jwtDecode(); the key ID (kid) in the JWT header must match one of the key IDs in the JWKS. There is one exception: if the JWKS contains only one key and the JWT header does not contain a key ID at all, this single key is used to verify the signature. However, if jwtEncode() is used with a JWK that contains a key ID, this key ID is added to the JWT's header. That key can then be identified correctly if it is part of a JWKS that is used to verify the signature.

Examples of valid key formats:

PKCS #8 (typically read from a key file):

-----BEGIN PUBLIC KEY-----
MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAu1SU1LfVLPHCozMxH2Mo
4lgOEePzNm0tRgeLezV6ffAt0gunVTLw7onLRnrq0/IzW7yWR7QkrmBL7jTKEn5u
...
(some lines omitted)
...
mwIDAQAB
-----END PUBLIC KEY-----

JWK

{

  "kty": "RSA",
  "e":   "AQAB",
  "use": "sig",
  "kid": "sig-1665752894",
  "alg": "RS256",
  "n":   "tvnUdVJWqlH4GczqUsXD  ...(part of n omitted)...  Nz89cDoFdM0dNAw",
  "d":   "Nz89cDoFdM0dNAw       ...(part of d omitted)...  tvnUdVJWqlH4GczqUsXD"
}

JWKS

{
  "keys": 
  [
    {
      "kty": "RSA",
      "e":   "AQAB",
      "use": "sig",
      "kid": "sig-1665752894",
      "alg": "RS256",
      "n":   "tvnUdVJWqlH4GczqUsXD  ...(part of n omitted)...  Nz89cDoFdM0dNAw",
      "d":   "Nz89cDoFdM0dNAw       ...(part of d omitted)...  tvnUdVJWqlH4GczqUsXD"
    },
    {
      ...(next JWK)...
    }
  ]
}

"e" and "n" are mandatory for all key types, "d" is mandatory for private keys and is not part of a public key. All other fields are optional.

Assignment

File function

Availability

UI