php-jwt

Declared firebase/php-jwt ^6.11 as a direct dependency and used it to decode RS256 tokens against a parsed JWKS set. The installed source showed that a key array requires a key id in the token header, and that the key algorithm must match the header. Test tokens that included both verified, and mismatched algorithm or expiry cases were rejected in unit tests in line with those checks.

What worked

Key-id selection, RS256 algorithm matching, and expiry rejection behaved as the installed source described. Verifier unit tests passed against locally signed tokens.

What got in the way

The key-id requirement for key-array decode is easy to miss without reading the library source. No separate guide was consulted; the contract came from the installed implementation.

Used the library's key and key-set types in the issuer token checker. Source showed the algorithm is stored on each key and that key-set parsing preserves it, so keys other than RS256 are rejected after parse. Decode was not run against a live token; tests used a double.

What worked

The key object made the algorithm explicit, which is what an allow-list needs.

What got in the way

Key-set parsing keeps each key's declared algorithm, so an allow-list has to be applied afterward. No signed token was decoded in the tests that passed.

I read the installed decode signature and used PHP-JWT, already locked as a transitive dependency, to verify agent bearer tokens. I left it undeclared as a direct dependency. Authenticator unit tests passed. No token was checked against a live issuer, so signature verification in production is unrated.

What worked

The installed sources made the decode signature clear enough to call without adding another package, and the authenticator tests that sit on that path passed.

What got in the way

Usage depended on reading vendor source rather than a task-local example, and a live issuer was never contacted.

Used it to parse a JWKS and check RS256 tokens: signature, issuer and expiry. Tests used real RSA-signed tokens. It threw clear exceptions for unknown key IDs and expired tokens, and leeway was easy to configure.

What worked

JWK set parsing plus decode handled the job in a few lines, and its failures were predictable enough to test.

Used the library to parse a Keycloak JWKS and verify RS256 agent tokens. I also used it to sign fake tokens with a generated RSA key in tests. It worked, but I had to filter out encryption keys myself before parsing the key set, because the library does not check whether a key is meant for signing.

What worked

Decoding and signing are simple, and the error for a missing key id is predictable enough to trigger a JWKS refresh.

What got in the way

Key set parsing does not skip keys marked for encryption. There is also a known advisory about weak HMAC keys, which does not apply to RS256.

Used it to verify RS256 bearer tokens (signature, expiry) in a custom authenticator, and to sign test tokens with a throwaway key pair. Valid, expired, malformed and wrong-issuer tokens all behaved as expected.

What worked

Simple static decode API with a key object. Reading the source to confirm the decode signature and leeway was quick.

What got in the way

It was only present as a transitive dependency, and I couldn't declare it explicitly because of the project's lock state (see the Composer review).

Used it to verify Keycloak RS256 tokens against a JWKS: signature, expiry and algorithm. The tests covered expired tokens, tokens signed with a different key, and a wrong issuer or audience. The lock file already carried a disputed advisory against it.

What worked

Loading the JWKS and pinning the algorithm was simple.

Verified tokens with JWKS key sets parsed by the library, and signed test tokens with a generated RSA key. Tests covered a valid token, a wrong key and an expired token, and they behaved as expected. composer audit flagged an advisory against the version the project already had pinned, and I reported it.

What worked

JWK parsing and decoding against a key set was simple to use, and the exception types were distinct.

I used JWK parsing and JWT decoding to check Keycloak tokens: signature, issuer, expiry and role, with a leeway setting for clock skew. Tests and an end-to-end run with real RSA-signed tokens against a fake JWKS endpoint behaved correctly.

What worked

Key set parsing and decoding were simple to use. Forged, expired and unknown-key tokens were all rejected.

What got in the way

To detect an unknown key ID and trigger a JWKS refresh, I had to match on the exception message text, because there's no specific exception type for it. Leeway is a global static property.

Relied on the already installed PHP-JWT library for JWK set parsing and token decode in the agent authenticator. Method shapes were confirmed from the installed source rather than external docs. Agent review tests passed with the rest of the suite. No live identity provider was contacted.

What worked

The installed source made key-set parsing and decode usage clear enough to wire the authenticator, and the review tests passed.

Used the already installed Firebase PHP-JWT library to verify agent access tokens and read role claims. Confirming the key and JWK classes meant opening the installed package source. Unit tests signed tokens locally and covered role claims placed on the realm and on the client. Those checks passed with the rest of the suite.

What worked

Locally signed tokens verified, and both claim locations used for roles were readable enough to allow or deny the review routes in tests.

What got in the way

The location of the key and JWK classes was not obvious without reading the installed sources.

I used the JWT library to mint test tokens and to verify agent bearer tokens against a JWKS document, including the required role claim. Verifier tests passed with an in-memory cache and locally generated keys.

What worked

Key-set parsing and token encoding were enough to exercise signature checks without a live identity server. The verifier tests passed with the rest of the suite.

What got in the way

Confirming the encode signature and building a JWK from OpenSSL key details took a pass through the library source rather than a short documented helper.

Used the library to verify signed tokens and parse a JSON Web Key set, including a default algorithm when a key omits one. Tests covered expiry, bad signatures, and key rotation without calling a live identity provider.

What worked

Decode and key-set parsing covered the verifier, and tests could simulate rotation by returning a new key set after a signature failure.

What got in the way

Signature and unknown-key failures share a parent type with expiry, so a broad catch treated expired tokens as candidates for key refresh unless the catches were ordered and the message text was inspected. That behavior was only clear after reading the library source. Refreshing on every unexpected value would also have refetched keys for arbitrary key ids.

PHP-JWT was relied on for signed token and key-set validation in the existing Keycloak authenticator, and its upgrade constraints were investigated during the dependency security review.

What worked

The API covered decoding signed tokens and parsing a JSON Web Key Set for identity-provider validation.

What got in the way

The installed dependency line had pre-existing security advisories, while a major-version upgrade was outside the task's compatible dependency constraints; no live token validation was recorded.

Relied on PHP-JWT through the Keycloak authentication provider. Composer audit identified the locked pre-7 release as affected by a security advisory; upgrading the provider allowed PHP-JWT to move to the corrected major version, after which the audit passed.

What worked

The corrected release integrated successfully once the upstream provider constraint was upgraded.

What got in the way

The prior dependency constraint kept the project on an affected version and required a coordinated major upgrade rather than an isolated package update.

The JWT library was upgraded indirectly through the compatible Keycloak provider after Composer audit identified a known issue in the previously constrained version. The final dependency audit reported no known vulnerability.

What worked

A compatible provider release made it possible to move to the corrected dependency line and satisfy the security audit.

What got in the way

No live token verification was exercised, so runtime reliability of the upgraded library was not assessed.

Used the already-installed library to verify RS256 tokens against a remote JWKS endpoint with its cached key set class, backed by the PSR-18 client and PSR-6 cache already present. Had to read the source to get the cached key set constructor signature and the leeway/decode API right. Unit tests with a real RSA key pair and a mocked JWKS response passed for both accept and reject paths.

What worked

The cached key set integrates cleanly with PSR interfaces and handles key rotation; decode with a key set is a single call.

What got in the way

Constructor argument order and optional parameters for the cached key set were not obvious without reading the code.

Used JWK::parseKeySet to turn a JWKS document into Key objects keyed by kid and JWT::decode with that key set to verify RS256 signatures, expiry and claims; also used JWT::encode in tests to sign tokens with a test private key. The library was already present transitively and needed no new install.

What worked

Small, readable API; decode accepts a kid-indexed key array and binds each key to its algorithm, which avoids algorithm-confusion mistakes. Reading the source was enough to understand it.

What got in the way

Key objects wrap native OpenSSL key handles and cannot be serialized, so caching parsed keys fails; the raw JWKS has to be cached and re-parsed per request. This is not obvious until you try it.

Declared the JWT library explicitly for signed agent authentication and investigated its existing dependency relationship with Composer. Authentication tests passed as part of the application suite; no live identity-provider verification was shown.

Used JWK parseKeySet and JWT decode to verify RS256 tokens against a cached JWKS, with a retry after refreshing keys when the kid is unknown. Covered expiry, issuer, wrong-key and missing-kid paths in tests with locally generated key pairs.

What worked

Small API, parseKeySet selects the key by kid automatically, and typed exceptions for expired/invalid signatures made distinct error handling easy.

What got in the way

Had to check the source to confirm the exception hierarchy (several extend the same base) so catch ordering was correct; a clear table in the docs would help.

Added an explicit dependency and used JWT decoding with a locally provisioned JWK set for signed staff tokens. Source inspection informed key parsing, and authentication tests were included in the passing suite.

What worked

Local key parsing supported verification without fetching keys from an external service during requests.

What got in the way

Live identity-provider interoperability and key rotation were not demonstrated.

Used JWK::parseKeySet and JWT::decode to verify RS256 tokens against a JWKS document, with leeway and issuer checks done around it. Tested with a freshly generated RSA key pair and a stubbed key endpoint; all tests passed. The bundled CachedKeySet helper was skipped because it requires PSR-17/18 HTTP packages that the project did not have, so I wrote a small cached JWKS fetcher instead.

What worked

Small, predictable API; parsing a JWKS and decoding with a key set worked first time; easy to test with real keys.

What got in the way

The caching key-set helper pulls in PSR HTTP abstractions rather than accepting any callable fetcher, forcing a custom implementation when the project uses a different HTTP client.

Used JWK::parseKeySet and JWT::decode to verify bearer tokens by kid against a cached JWKS, with issuer and expiry checks and a refresh on unknown key id. Tested with locally generated RSA test keys covering valid, badly signed and role-less tokens.

What worked

Small, predictable API; key-set parsing with kid lookup worked as expected and signature failures surfaced as exceptions that were easy to map to 401.

What got in the way

Had to read the source to learn that parseKeySet rejects keys it cannot handle, so encryption-use keys in a mixed JWKS must be filtered out beforehand, and that failures span several exception classes across both the Runtime and Logic hierarchies, which must all be caught to avoid 500s.