Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Node.js, PHP and APIs

JWT::decode() says the kid is empty and cannot find the key

Error"kid" empty, unable to lookup correct key

Short answer

This message means you gave JWT::decode() an array of keys, but the token header has no kid to pick one with. For one secret or public key, pass a single Key object with its algorithm. For several keys, key the array by kid and make sure the issuer puts that kid in the token header.

  • Applies to firebase/php-jwt 6.x, PHP 8.3
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Decode only the header of the token (the first segment) and see whether it contains a kid at all.

    echo "$TOKEN" | cut -d. -f1 | tr '_-' '/+' | base64 -d 2>/dev/null; echo
  2. 2Match what you see, then jump to its fix

    1. 1The header printed by the first step has alg and typ but no kid, and the code calls JWT::decode($jwt, $keys)An array of keys is passed, but the token has no kidFix
    2. 2You decode with an array keyed by kid, and the issuing code is yoursThe token was signed without a key IDFix
    3. 3You fetched a JSON Web Key Set from the identity provider and passed the raw arrayThe keys come from a JWKS and were not convertedFix

What does the error look like?

  • "kid" empty, unable to lookup correct key
  • UnexpectedValueException

Cause 1 of 3

An array of keys is passed, but the token has no kid

1Check

Look at the second argument of decode(). If it is a plain array, the library tries to find the key by the kid in the token header, and an empty kid gives this exact error.

grep -rn "JWT::decode" src/ app/

2Fix

When you have one key, wrap it in a Key object together with the algorithm and pass that, not an array.

use Firebase\JWT\JWT;
use Firebase\JWT\Key;

$decoded = JWT::decode($jwt, new Key($secret, 'HS256'));

3Verify

Decode a fresh token; no exception should be thrown and the payload should come back.

php -r 'require "vendor/autoload.php"; var_dump(Firebase\JWT\JWT::decode($argv[1], new Firebase\JWT\Key(getenv("SECRET"), "HS256")));' "$TOKEN"

Confirmed by github.com

Did this fix it?

Cause 2 of 3

The token was signed without a key ID

1Check

Find where the token is created. The key ID is the fourth argument of JWT::encode(). If it is missing, the header gets no kid.

grep -rn "JWT::encode" src/ app/

2Fix

Pass the key ID when encoding, and use the same ID as the array key on the decoding side.

$jwt = JWT::encode($payload, $privateKey, 'RS256', 'kid1');

$decoded = JWT::decode($jwt, [
    'kid1' => new Key($publicKey, 'RS256'),
]);

3Verify

Run the header check from the first step on the new token; it should now list kid.

echo "$NEWTOKEN" | cut -d. -f1 | tr '_-' '/+' | base64 -d 2>/dev/null; echo

Confirmed by github.com

Did this fix it?

Cause 3 of 3

The keys come from a JWKS and were not converted

1Check

decode() needs Key objects, not the raw JSON. Check whether the keys went through JWK::parseKeySet().

grep -rn "parseKeySet\|CachedKeySet" src/ app/

2Fix

Convert the JWKS first. The result is an array that maps each kid to a Key object, which is exactly what decode() expects. A CachedKeySet can be passed straight to decode() as well.

use Firebase\JWT\JWK;

$keys = JWK::parseKeySet($jwks);
$decoded = JWT::decode($jwt, $keys);

3Verify

Decode a token from the provider; its kid must exist as a key in the converted array.

php -r 'require "vendor/autoload.php"; print_r(array_keys(Firebase\JWT\JWK::parseKeySet(json_decode(file_get_contents("jwks.json"), true))));'

Confirmed by github.com

Did this fix it?

How do I stop it coming back?

  • Always pass the algorithm inside the Key object, so the token cannot choose it.
  • Set a kid whenever you sign with more than one key, so rotation works.
  • Catch UnexpectedValueException around decode() and return 401, not a 500.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Back end

Fatal error: Class "Firebase\JWT\JWT" not found

Class 'Firebase\JWT\JWT' not found

PHP cannot find the class because the package is not installed, the Composer autoloader is never loaded, or the file lacks a use statement.

3 causes, each with a fix

Back end

Apache returns 403 when a URL contains %3F

a request like /page%3Fname=test is refused while /page?name=test works

Recent Apache httpd blocks a rewrite when the request contains an encoded question mark (%3F) and the rewritten target has a literal ?.

2 causes, each with a fix

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.