NewYour coding agent can read the release notes before it upgrades.Set up the MCP server →
Packagist · #1056 most downloaded on Packagist
Implements a refresh token system over Json Web Tokens in Symfony
Last release 2 months ago
05 Aug 2026
Release timing varies
gaps range from 2 weeks to 1.2 years
Rarely documented
notes for 13 of 54 stable releases
Nothing withdrawn
no release was ever pulled
11 years old
59 releases · first in 2015
Symfony 8, PHP 8.4 and LexikJWTAuthenticationBundle 3.
Symfony 8, PHP 8.4 and LexikJWTAuthenticationBundle 3.
This release needs a schema change before the application will run. Refresh tokens gained family and family_valid columns, and Doctrine reads every mapped field.
php bin/console doctrine:migrations:diff
php bin/console doctrine:migrations:migrateRead UPGRADE-3.0.md first, and UPGRADE-RECTOR.md if you are coming from further back than 2.2.
If you are on Symfony 6.4 or 7.x, stay on 2.2. It is maintained, and Symfony 7.4 is supported until November 2028.
Refresh tokens belong to a chain. A token issued in place of another carries the family of the one it replaced, so a login and every refresh descending from it share one value — which is what makes a session addressable. Without it, "end this session" can only mean "delete this one token", and with single_use that token has usually already been replaced.
Everything below is built on that, and all of it is off by default.
reuse_detection — recognises a spent token being presented again and revokes the whole chain. Rotation on its own leaves a stolen token working until the legitimate client happens to refresh, and nobody learns why it broke. It cannot tell theft from a client racing itself, so it revokes either way and dispatches an event for the judgement it cannot make.max_session_lifetime — a ceiling on how long a chain may go on for, whatever ttl says.block_jwts_on_revocation — refuses the JWTs already issued to a user when revokeAllForUser() takes their refresh tokens away. Lexik's blocklist is keyed by jti and cannot do this; what is recorded instead is when the revocation happened.SessionLister — the "where you are signed in" screen and the button next to each row, grouped by chain rather than by token.rate_limiter — consumed before the token is looked at, so a refusal costs no query and its timing says nothing about whether the token exists.cache_pool — stores the tokens in a PSR-6 pool, where expiry is the pool's job. It implements only what a pool can honour and says so about the rest.ttl, single_use and the rest on the refresh_jwt authenticator, which is the longest-standing thing this bundle could not do.check_path is required on refresh_jwtRefreshEvent takes the request, and $firewallName loses its defaultdbal_columns, when configured, has to name the id columnfinal; the token models and repositories are deliberately notThe full list is in the changelog.
One column per quarter.
See UPGRADE-3.0.md for what to check before upgrading, and UPGRADE-RECTOR.md if you are coming from further back than 2.2.
This release needs a schema change before the application will run. Refresh tokens gained
family and family_valid columns, and Doctrine reads every mapped field.
Model\FamilyAwareRefreshTokenInterface and Model\RefreshTokenFamilyTrait, separate from RefreshTokenInterface so a token class of your own is untouched. Model\FamilyRefreshTokenManagerInterface::revokeFamily() revokes a whole chainreuse_detection, which recognises a single use refresh token being presented after it was spent and revokes the chain it belonged to. Rotation alone leaves a stolen token working until the legitimate client happens to refresh, and nobody learns why it broke; a spent token is deleted, so a replay is indistinguishable from any other unknown token unless spent ones are remembered. Off by default, refused without single_use, and it dispatches RefreshTokenReuseDetectedEvent because the bundle cannot tell theft from a client racing itselfmax_session_lifetime, a ceiling on how long a chain of refreshes may go on for, whatever ttl says. A ttl that starts over on every rotation means a session never ends. The deadline is set when a chain starts and carried along it unchangedblock_jwts_on_revocation, which refuses the JWTs already issued to a user when revokeAllForUser() takes their refresh tokens away. Lexik's blocklist cannot do this — it is keyed by jti, so it withdraws a token you are holding, and these are in clients — so what is recorded is when the revocation happened, per user, and any JWT issued at or before it is refused on decoderate_limiter, bounding how often the refresh endpoint will answer. Consumed before the token is looked at, so a refusal costs no query and its timing says nothing about whether the token exists. Refused requests answer 429 with Retry-After. Keyed by IP or by token, which is a trade-off rather than a detail. Needs symfony/rate-limiterSession\SessionLister, for showing a user where they are signed in and letting them end one. Grouping by chain is what turns findAllForUser() from a list of moments into a list of sessions. end() checks the chain belongs to the caller, since a session list is exactly where such an identifier gets handed outcache_pool, storing the tokens in a PSR-6 pool instead of a database. Expiry is then the pool's job, so nothing has to be scheduled to clear them. It implements only what a pool can honour, and max_tokens_per_user and reuse_detection are configuration errors alongside it rather than options that quietly do nothingttl, ttl_update, token_parameter_name, single_use, single_use_ttl_update, max_session_lifetime, max_tokens_per_user, return_expiration and return_expiration_parameter_name on the refresh_jwt authenticator. Every one defaults to null, meaning "whatever the bundle says", which is not the same as defaulting to its current value. Cookie settings stay globalblock_previous_jwt, which blocks the JWT a refresh replaces through LexikJWTAuthenticationBundle 3's blocklist, so refreshing no longer leaves the previous JWT usable for the rest of its lifetime. A request carrying no JWT, and a JWT that no longer parses, are left alone: an expired one is refused everywhere already. Off by default, and reported at compile time when Lexik's blocklist_token is not onrector/sets, with the upgrade path in UPGRADE-RECTOR.md. Only the 1.5 to 2.0 set rewrites anything; the other three are empty and say whycheck_path is required on the refresh_jwt authenticator. It defaulted to /login_check, Lexik's login path, which is never right for a refresh endpoint: left alone the authenticator took no requests and the router reported the refresh route as having no controllerRefreshEvent takes the request the refresh was made with, and $firewallName loses its default. Listeners gain getRequest(); only code constructing the event is affectedquoteIdentifier() and setPrimaryKey()dbal_columns, when configured, has to name the id column. A map without one produced a table whose expired tokens could never be revoked: batches are deleted by identifier, so with none to delete by, gesdinet:jwt:clear read the same batch foreverfinal. The token models, AbstractRefreshToken and the two repositories are deliberately left extendable, being the documented way to bring your ownstrict_types, so the calls this bundle makes pass their arguments without coercionrector.php and .php-cs-fixer.php now keep it that way. rector/rector had been a development dependency for a long time with nothing configured to run itUNIQ_REFRESH_TOKEN, IDX_USERNAME and IDX_VALID were fixed whatever the table was called, and index names are scoped to the schema on PostgreSQL and to the whole database on SQLite — so a second table managed by the bundle could not be created, and the error named an index rather than anything identifying this bundle. Existing tables are untouched, since the schema is only built when absentSession\SessionLister keys chains by array-key rather than string. A family is 32 hex characters, and PHP turns one that happens to be all digits into an integer keyRefreshTokenFamilyTrait that stopped psalm's taint analysis reasoning about where a family came from, and four array shapes that were sealed promises about keys the method never looks at. The rest are by design or belong to Symfony, Doctrine and API Platform, and are suppressed in psalm.xml.dist scoped to the files they concern, each with the reason2.2.1 did not actually fix #431 for everyone. If you are on Symfony 7.0, 7.1, 7.2 or 7.3, or on a patch of 6.4 older than 6.4.37 or of 8.0 older than
2.2.1 did not actually fix #431 for everyone. If you are on Symfony 7.0, 7.1, 7.2 or 7.3, or on a patch of 6.4 older than 6.4.37 or of 8.0 older than 8.0.9, upgrade to this instead.
The check on ttl was moved from a validate() closure to min(), because NumericNode skips min() while it is handling the placeholder an environment variable stands in as.
It does — in symfony/config 6.4.37, 7.4.9, 8.0.9 and 8.1 onwards. That skip was backported to the maintained branches only, and 7.0 through 7.3 are end of life, so they never received it and never will. On any of those, 2.2.1 rejected %env(int:...)% exactly as 2.2.0 did.
Neither ttl nor max_tokens_per_user is validated in the configuration tree any more.
On the affected versions there is no check that can tell the sample value of 0 — which Symfony substitutes to see whether the configuration would accept the variable — from a 0 written by hand. Refusing to boot an application that reads its ttl from the environment is the worse of the two failures, so the check is gone rather than made conditional.
A ttl of 0 or less is therefore accepted again, as it was in 2.1.0 and earlier. It still produces a token that has expired by the time it is handed over, so it is worth not writing one.
gesdinet_jwt_refresh_token:
ttl: '%env(int:JWT_REFRESH_TOKEN_LIFETIME_IN_SECONDS)%'works on every Symfony this release supports.
Fixes a regression in 2.2.0, reported by @dennismetz in #431 .
Fixes a regression in 2.2.0, reported by @dennismetz in #431.
ttl and max_tokens_per_user from an environment variablegesdinet_jwt_refresh_token:
ttl: '%env(int:JWT_REFRESH_TOKEN_LIFETIME_IN_SECONDS)%'failed to compile with:
Invalid configuration for path "gesdinet_jwt_refresh_token.ttl":
The "ttl" must be a positive number of seconds, and 0 is not.
An environment variable is a placeholder at compile time, and Symfony compiles the configuration a second time with a sample value of the declared type in its place, to check it would be accepted. For an integer that sample is 0, and the check added in 2.2.0 rejects anything below 1 — so it rejected every integer environment variable, whatever the variable held.
NumericNode skips min() and max() while it is handling a placeholder. A validate() closure is not skipped, which is why the built-in constraint is now used for both nodes. The validation itself is unchanged: 0 and negative values are still rejected when written literally.
2.1.0 is not affected — the ttl check did not exist before 2.2.0.
Only ttl and max_tokens_per_user were affected. default_invalid_batch_size already used min(), and cookie.same_site was fixed for the same underlying reason in 2.2.0.
ttl and max_tokens_per_user can be read from an environment variable again. Both were checked with a validate() closure, which rejects every %env(int:...)% put in front of them: the container is compiled a second time with a sample value of the declared type in place, and for an integer that sample is 0. min() is skipped while a placeholder is being handled and a closure is not, so the built-in constraint is used instead. Reported as #431 against 2.2.0, where the ttl check was introduced; 2.1.0 has no such check and is unaffectedTwo features for keeping refresh tokens under control, one for documenting them, and a fix that made the recommended configuration work as written.
Two features for keeping refresh tokens under control, one for documenting them, and a fix that made the recommended configuration work as written.
See UPGRADE-2.2.md before upgrading. One configuration is now rejected; everything else is additive or a correction.
With jwt and refresh_jwt on the same firewall, the JWT authenticator was reached first and rejected the expired token before the refresh authenticator saw it — so the configuration in the README did not work as written, and the advice given for years, to reorder them on the firewall, could never have helped. Symfony orders authenticators by the priority each factory declares, not by the file. This one now sits above Lexik's.
Nothing to change. Applications that split the refresh endpoint into its own firewall to get around it can collapse it back.
gesdinet_jwt_refresh_token:
hash_tokens:
enabled: trueA refresh token gets its holder back into an account without a password, so a copy of the table was a copy of everybody's credentials, next to the passwords that are hashed for exactly that reason. What is stored is now sha256$ and the hash, and a leaked table cannot be used.
Off by default, and turning it on signs nobody out: tokens already stored are taken as they are and rewritten hashed the first time they are used. getRefreshToken() then returns the stored hash, which is worth reading about in the upgrade guide first.
gesdinet_jwt_refresh_token:
max_tokens_per_user: 5Every login stores a token, deliberately, so that a user's devices are separate sessions. Nothing bounded how many accumulated. Signing in beyond the limit revokes the session that has gone longest without being refreshed, expired ones first.
gesdinet_jwt_refresh_token:
api_platform:
enabled: trueLexik documents the login endpoint, but its response schema only carries the JWT, because the refresh token beside it is added by this bundle. The refresh endpoint was documented by nobody, being a firewall authenticator rather than a controller. Both are covered now, from the bundle's own configuration — so with the cookie replacing the body, no refresh_token field is promised that never arrives.
dbal_connection) storing tokens through a plain connection, with no object manager and no unit of work.refresh_token_manager naming a manager of your own, wiring none of the bundle's storage, so the tokens can live in a PDO repository or anywhere else and Doctrine need not be installed at all.single_use_ttl_update: false so a token issued in place of a single use one inherits the expiry of the one it replaced, bounding the chain.ListRefreshTokenManagerInterface::findAllForUser() and revokeAllForUser() for showing a user their sessions and ending them.^7.2 while the rest allowed ^7.0, and Composer resolves the intersection.Content-Type, delete() reporting the rows it actually removed, and cookie.same_site from an environment variable.The issue tracker is empty as of this release: 64 issues were reviewed and closed, several of them fixed here.
Released 2026-08-04. See UPGRADE-2.2.md for what to check before upgrading.
jwt and refresh_jwt on the same firewall. Symfony orders authenticators by the priority their factories declare rather than by the order written on the firewall, and this one sat below the JWT authenticator, which rejected the expired token before the refresh authenticator was reached. Reordering them in security.yaml never had any effect. It now sits above it, and since it only takes over requests matching its check_path, nothing else changesobject_manager naming a service that does not exist is reported as such, with the object managers there are, rather than as Symfony being unable to replace an alias with a definition. The usual cause is giving the name an entity manager is configured under instead of its service id, which the message now saysfetch() does when given none, or a proxy that strips it, was answered as though no token had been supplieddelete() reports what the storage actually deleted rather than one row after reading the token back. Two callers racing for the same token were both told they had deleted it, which is the answer a single use token needs to tell them apartgesdinet:jwt:clear reports how many tokens it revoked and lists them only with -v. A run clearing a backlog revokes thousands, and listing them all buried the countttl of 0 or less is rejected. It describes a token that has expired by the time it is handed over, so every refresh made with one fails, and it is what an application reaching for a token that never expires tends to try firstcookie.same_site can be read from an environment variable. It accepted a fixed list of words, and an environment variable is checked at compile time against an empty sample value of its type, so every variable put in front of it was rejected whatever it held. It now accepts what Symfony\Component\HttpFoundation\Cookie itself documents: the three values in any case, or an empty one to leave the attribute off the cookiettl from when it was set. The two only ever agreed because the token was issued with a full ttl, which single_use_ttl_update no longer guaranteesconfig/services.php also defined it, naming a class it never imported and an object manager the DBAL backend does not have, which went unnoticed only because both backends overwrote itsingle_use_ttl_update, on by default, which keeps a token issued in place of a single use one starting its ttl over. Turned off, the replacement expires when the one it replaced would have, so refreshing cannot be chained indefinitely and the user signs in again a ttl after the first token was issueddbal_connection, storing the tokens through a plain connection rather than the ORM or the ODM. The table and its columns are named with dbal_table_name and dbal_columns, and dbal_auto_create_table creates the table on the first request when a migration is not practicalRevokeRefreshTokenManagerInterface, aliased to the manager so it can be injected by type, whose revokeAllForUser() revokes every refresh token issued to a user, for a password reset or an account being disabled, and returns how many were revoked. It is deleted by the database, so no token is hydrated and no life-cycle event is raisedDeleteRefreshTokenRepositoryInterface::deleteByUser() backs it. Both are separate interfaces, so an existing manager or repository keeps working without themListRefreshTokenManagerInterface::findAllForUser(), which returns every refresh token issued to a user, the one expiring last first, for showing somebody the sessions they have open. Expired ones are included, since they are still rows, and isValid() tells them apartRevokeRefreshTokenManagerInterface and ListRefreshTokenManagerInterface are aliased to the manager for every backend, the DBAL one included. Revoking by user was only offered to the ORM and the ODMhash_tokens, which stores sha256$ and the hash of a refresh token rather than the token, so a copy of the database cannot be used to refresh. Off by default. Turning it on signs nobody out: tokens already stored are taken as they are and rewritten hashed the first time they are used, until accept_stored_in_the_clear is turned off. Note that getRefreshToken() then returns the stored hash, since that is what is storedmax_tokens_per_user, a limit on how many refresh tokens a user may hold at once, which is a limit on signed-in devices since each login stores one. Signing in beyond it revokes the session that has gone longest without being refreshed, expired tokens first. Unlimited when not setRevokeRefreshTokenManagerInterface::revokeAllButNewestForUser() and DeleteRefreshTokenRepositoryInterface::deleteAllButNewestForUser() back itapi_platform.enabled, which documents the refresh token in the OpenAPI specification API Platform generates: the refresh_token Lexik's login schema was missing, and the refresh endpoint nobody documented, one path per firewall the authenticator is on. It follows the bundle's own configuration, so the cookie replacing the body is documented as such rather than promising a field that never arrives. Off by default, since an application documenting it by hand would end up with it twicerefresh_token_manager, naming a service of your own, which replaces the manager the bundle would build and wires none of its storage, so the tokens can live in a PDO repository or anywhere else and Doctrine need not be installed at all. RefreshTokenManagerInterface is now held to the same test suite from outside the bundle, so it stays implementableFixes across the batch revocation, the MongoDB ODM and the values read from the request. Nothing has to be changed in an application using the bundle
Fixes across the batch revocation, the MongoDB ODM and the values read from the request. Nothing has to be changed in an application using the bundle through its configuration and its services: see UPGRADE-2.1.md for the return values an application may be reading.
revokeAllInvalidBatch() returned the last batch read, which is empty once the loop ends, so it always returned an empty array and gesdinet:jwt:clear reported that there was nothing to revoke after deleting tokensrevokeAllInvalidBatch() looped forever with the MongoDB ODM, as its condition tested the repository result with empty(), which is never true for the iterator the ODM returnsrevokeAllInvalidBatch() skipped expired tokens: each batch is deleted before the next is read, so the remaining tokens shift down and the offset has to stay where it isQuery::getIterator(), so they are the iterable the interface promisesdelete() returns 0 when the token is not in storage, which the ODM reported as 1 regardlessInvalidTokenException instead of a TypeError while building the passportrefresh_token_class reports a configuration error when the class cannot be loaded, instead of a TypeError while building the containergesdinet:jwt:clear rejects a --batch-size that is not a positive number, which read no tokens and reported success while leaving every expired token in placeAuthenticationSuccessHandler::onAuthenticationSuccess() is typed ?Response, matching the handler it decorates. What is returned at runtime has not changedRefreshTokenRepositoryInterface documents, through a @method tag, that findOneBy() takes an optional $orderBy argumentphp constraint is written as ^8.2, the same minimum without claiming support for a future PHP 9Test coverage is at 98%, PHPStan runs at level 10 and the security scan runs the project's own Psalm. The suite supports PHPUnit 10.5, 12 and 13.
Full Changelog: v2.0.0...v2.1.0
revokeAllInvalidBatch() returned the last batch read, which is empty once the loop ends, so it always returned an empty array and gesdinet:jwt:clear reported that there was nothing to revoke after deleting tokensrevokeAllInvalidBatch() looped forever with the MongoDB ODM, as its condition tested the repository result with empty(), which is never true for the iterator the ODM returnsrevokeAllInvalidBatch() skipped expired tokens: each batch is deleted before the next is read, so the remaining tokens shift down and the offset has to stay where it isQuery::getIterator(), so they are the iterable the interface promisesdelete() returns 0 when the token is not in storage, which the ODM reported as 1 regardlessInvalidTokenException instead of a TypeError while building the passportrefresh_token_class reports a configuration error when the class cannot be loaded, instead of a TypeError while building the containergesdinet:jwt:clear rejects a --batch-size that is not a positive number, which read no tokens and reported success while leaving every expired token in placePostRefreshTokenAuthenticationToken checks the serialized state it is givenAuthenticationSuccessHandler::onAuthenticationSuccess() is typed ?Response, matching the handler it decorates. What is returned at runtime has not changedRefreshTokenRepositoryInterface documents, through a @method tag, that findOneBy() takes an optional $orderBy argumentphp constraint is written as ^8.2, the same minimum without claiming support for a future PHP 9See UPGRADE-2.1.md for the details.
Adjust setup for the ORMTestCase to avoid some deprecations with ORM 3.4 by @mbabker in #399
Full Changelog: v1.5.0...v2.0.0
Gesdinet\JWTRefreshTokenBundle\EventListener\LogoutEventListener service definition; if needed, an abstract gesdinet_jwt_refresh_token.security.listener.logout definition replaces it and does not have a kernel.event_listener taglogout_firewall config node default value is now nulllogout_firewall config node, the invalidate_token_on_logout option should be set on the refresh_jwt authenticatordoctrine/persistence 4.0Adjust setup for the ORMTestCase to avoid some deprecations with ORM 3.4 by @mbabker in #399
Full Changelog: v1.5.0...v2.0.0-beta
This is a pre-release as non-production ready for testing. Bugs or testing is welcome
gesdinetclear crashed with array_map(): Argument #2 ($array) must be of type array, Doctrine\ODM\MongoDB\Iterator\CachingIterator given when using the
gesdinet:jwt:clear crashed with array_map(): Argument #2 ($array) must be of type array, Doctrine\ODM\MongoDB\Iterator\CachingIterator given when using the MongoDB ODM.
The ORM repository returns an array, but the ODM one returns a CachingIterator, and RefreshTokenManager::revokeAllInvalid() passed it straight through to the command. It now always returns the RefreshTokenInterface[] documented by RefreshTokenManagerInterface, whatever the repository returns.
Reported in #424 by @melkamar.
Full Changelog: v1.5.0...v1.5.1
Fix Deprecation Notice in RefreshTokenAuthenticator::start Method by @gzim324 in #389
Full Changelog: v1.4.0...v1.5.0
Dropped support for Symfony 4.4
Added support for partitioned cookies
Nothing published for this version
Added support for LexikJWTAuthenticationBundle 3.0
LexikJWTAuthenticationBundle 3.0Nothing published for this version
Nothing published for this version
Nothing published for this version
Deprecated not configuring the request path to check in the refresh_jwt authenticator
refresh_jwt authenticatorrefresh_jwt authenticatorNothing published for this version
Dropped support for MongoDB ODM 1.x
Added Gesdinet\JWTRefreshTokenBundle\Doctrine\RefreshTokenRepositoryInterface
Gesdinet\JWTRefreshTokenBundle\Doctrine\RefreshTokenRepositoryInterfaceGesdinet\JWTRefreshTokenBundle\Doctrine\RefreshTokenManager now requires all object repositories implement Gesdinet\JWTRefreshTokenBundle\Doctrine\RefreshTokenRepositoryInterfaceNothing published for this version
Added Gesdinet\JWTRefreshTokenBundle\Request\Extractor\ExtractorInterface as an interface for extracting the refresh token from the request, implement
Gesdinet\JWTRefreshTokenBundle\Request\Extractor\ExtractorInterface as an interface for extracting the refresh token from the request, implementations provided by this bundle include:
Gesdinet\JWTRefreshTokenBundle\Request\Extractor\ChainExtractor - Calls all registered extractors to find the request token (by default, this extractor is aliased to the interface in the DI container)Gesdinet\JWTRefreshTokenBundle\Request\Extractor\RequestBodyExtractor - Decodes a JSON request body and loads the token from itGesdinet\JWTRefreshTokenBundle\Request\Extractor\RequestParameterExtractor - Loads the refresh token by calling $request->get()Gesdinet\JWTRefreshTokenBundle\Request\RequestRefreshToken class, a Gesdinet\JWTRefreshTokenBundle\Request\Extractor\ExtractorInterface implementation should be used insteadGesdinet\JWTRefreshTokenBundle\Model\RefreshTokenInterface now extends Stringable, refresh token models now require a __toString() methodNothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Your coding agent can read these notes before it upgrades. Set up the MCP server →