feat: implement Token Family system and optional blacklist cache #913

juanbailon · 2025-05-20T00:55:44Z

Hi,

This PR introduces a system based on the Token Family concept, which enables tracking the lineage of issued refresh tokens(and access tokens if enabled) and detecting improper reuse. If a reused refresh token is detected, the entire associated family is revoked. This approach effectively stops the attack, though it requires the legitimate user to re-authenticate.

In addition, optional caching support has been integrated to optimize the performance of blacklist checks for families and refresh tokens .

The motivation behind this implementation is outlined in this Auth0 blog post, which explains how a token family enhance security in the case of a refresh token reuse detection.

Furthermore, IETF RFC 9700, Section 4.14 highlights that refresh tokens are a valuable target for attackers, as they allow minting access tokens with full scope. Replay attacks using a stolen refresh token can result in unauthorized access. This implementation offers a mechanism to detect and respond to such replay attempts.

Beyond the replay attacks, the token family system also enables session-level tracking and revocation. Since each session corresponds to a unique token family, it's now possible to isolate and invalidate all tokens tied to a compromised session. This approach also touches on concerns raised in Issue #697.

This PR also includes a fix for Issue #911 .

To facilitate adoption and understanding, a preview of the updated documentation, detailing how to enable and configure these features, is available here: link.

Thank you for your time, and I hope you find this contribution useful for the library.

- Added for handling blacklisted refresh tokens. - Introduced to indicate missing token family setup.

- Introduced TOKEN_FAMILY_ENABLED to toggle token family functionality. - Added TOKEN_FAMILY_LIFETIME to define family expiration duration. - Added TOKEN_FAMILY_CHECK_ON_ACCESS to include family claims in access tokens and perform validations for the token family on the access token. - Added TOKEN_FAMILY_BLACKLIST_ON_REUSE to enable blacklisting of the token family if a refresh token reuse is detected. - Defined TOKEN_FAMILY_CLAIM and TOKEN_FAMILY_EXPIRATION_CLAIM for token structure. - Set TOKEN_FAMILY_BLACKLIST_SERIALIZER.

- Introduced FamilyMixin to manage token families. - Made RefreshToken inherit from FamilyMixin to track family claims and support blacklisting entire token families. - Updated access_token method in RefreshToken to optionally include family claims based on the setting TOKEN_FAMILY_CHECK_ON_ACCESS. - Modified AccessToken.verify to validate token family status when TOKEN_FAMILY_CHECK_ON_ACCESS is enabled. - Updated BlacklistMixin.check_blacklist to raise RefreshTokenBlacklistedError instead of TokenError for better error differentiation.

…sh token handling - Added FamilyMixin checks to TokenVerifySerializer for family expiration and blacklist validation. - Implemented TokenFamilyBlacklistSerializer to support blacklisting entire token families. - Refactored TokenRefreshSerializer to use _get_refresh_token, ensuring proper handling of token family blacklisting on reuse.

… and add abstract workaround - Renamed TokenFamilyBlacklist to BlacklistedTokenFamily to align with the existing naming convention used in the token_blacklist app (BlacklistedToken model). - Updated all references to TokenFamilyBlacklist in the codebase to reflect the new model name. - Added 'abstract' attribute to the token_family app models to match the pattern used in the token_blacklist models.

…e database

…ers, and models - Added test_token_family.py with: - TestTokenFamilyModels - TestTokenFamilyInRefreshTokens - TestTokenFamilyInAccessTokens - TestFlushExpiredTokenFamiliesCommand - Added tests for token family behavior in serializers and views - Updated conftest.py, urls.py, and test_integration.py to support token family tests

- SJWT_CACHE_NAME: selects the Django cache alias - CACHE_BLACKLISTED_REFRESH_TOKENS and CACHE_BLACKLISTED_FAMILIES: toggle caching - TTL and key prefix settings added for each blacklist type

…and families

…lies - Added cache check for blacklisted refresh tokens in TokenVerifySerializer - Enhanced BlacklistMixin and FamilyMixin to support caching for blacklisted tokens and families.

- Added test_cache.py. - Updated conftest.py and test_integration.py.

…models

- Included token_family app in conf.py - Added family_app.rst for token family details - Documented related family settings in settings.rst - Linked family_app in index.rst toctree

- Added cache_support.rst - Updated 'index.rst' to include the new page in the toctree - Documented related cache settings in settings.rst

…eturn values, and TokenVerifySerializer check. resolves jazzband#911

for more information, see https://pre-commit.ci

Andrew-Chen-Wang

This is a huge PR, and I wish the blacklist cache was split into two PRs so it could be more easily reviewable.

Please also generate the i18n locale. There is a script.

Andrew-Chen-Wang · 2025-10-02T16:00:35Z

...simplejwt/token_family/migrations/0002_rename_tokenfamilyblacklist_blacklistedtokenfamily.py

+            old_name="TokenFamilyBlacklist",
+            new_name="BlacklistedTokenFamily",


Could this migration file be combined with the 0001

Andrew-Chen-Wang · 2025-10-02T16:00:48Z

rest_framework_simplejwt/token_family/__init__.py

@@ -0,0 +1,4 @@
+from django import VERSION
+
+if VERSION < (3, 2):


We don't support <3.2

Andrew-Chen-Wang · 2025-10-02T17:46:44Z

tests/test_cache.py

+from tests.utils import override_api_settings
+
+
+class TestBlacklistCache(TestCase):


The BlacklistCache should be read-through such that, if there's a cache miss (e.g. due to eviction or a dev adds this, then they won't be confused), you should check the database, and if there's a hit on the database, then you can update the cache. We already know that the JWTs are validated in the serializer before all the I/O bound checks commence, so I believe the cache miss and database combo should be minimal.

Andrew-Chen-Wang · 2025-10-02T17:52:10Z

rest_framework_simplejwt/cache.py

+
+
+# Singleton instance for centralized cache management
+blacklist_cache = BlacklistCache()


What if the user wants to use their own BlacklistCache implementation? I don't think monkeypatching this file directly would work because it's already been imported in our library's files everywhere. Can we have a setting for the creation of the cache and use the simplejwt settings as a way to grab this singleton instance?

Andrew-Chen-Wang · 2025-10-02T17:53:14Z

rest_framework_simplejwt/tokens.py

+            - Assigns a family expiration timestamp if `TOKEN_FAMILY_LIFETIME` is set.
+            - Saves the token family information in the database.
+            """
+            token = super().for_user(user)  # type: ignore


Why are there so many type: ignore?

Andrew-Chen-Wang · 2025-10-02T17:54:28Z

rest_framework_simplejwt/tokens.py

+                raise RefreshTokenBlacklistedError(_("Token is blacklisted"))

-        def blacklist(self) -> BlacklistedToken:
+        def blacklist(self) -> tuple[BlacklistedToken, bool]:


I don't see anywhere in this PR where this signature change is needed. This would technically be a breaking change.

Andrew-Chen-Wang · 2025-10-02T17:57:06Z

rest_framework_simplejwt/serializers.py


        return data

+    def _get_refresh_token(self, token_str: str) -> RefreshToken:


This is a breaking behavior change. We should avoid raising errors on instantiation for blacklist to be compatible with previous behavior. Why would this not happen in the token class itself?

Andrew-Chen-Wang · 2025-10-02T18:00:21Z

rest_framework_simplejwt/serializers.py

        return {}


+class TokenFamilyBlacklistSerializer(serializers.Serializer):


Shouldn't we be able to combine this with TokenBlacklistSerializer

Andrew-Chen-Wang · 2025-10-02T18:02:07Z

rest_framework_simplejwt/tokens.py

+            if not family_id:
+                user_id = token.get(api_settings.USER_ID_CLAIM)
+                logger.warning(
+                    f"Token of user:{user_id} does not have a family_id. Skipping family blacklist check."


Suggested change

f"Token of user:{user_id} does not have a family_id. Skipping family blacklist check."

f"Token of user: {user_id} does not have a family_id. Skipping family blacklist check."

Why is this log helpful? Shouldn't new tokens if a dev includes the token family app be migrating the tokens forward?

Andrew-Chen-Wang · 2025-10-02T18:08:08Z

Attaching this PR from Ory that could be helpful as a reference: ory/hydra#2022 and ory/hydra#2383

Andrew-Chen-Wang

I'm noticing how complicated this is becoming. Is the reason to create a second app instead of combining the token blacklist app with the family blacklist app because of the token blacklist tables?

So long as the user has the token blacklist app not installed and the setting is turned off, it should be fine to just migrate with those tables and not touch them since they take near 0 space in a database anyways. I feel like the functionalities are pretty similar, and having so many installed apps seems weird? I'd rather use settings to determine if the blacklist app is enabled and check a configuration if someone wants to use the token blacklist app rather than having 4 conditions, each app doing 2 conditions for checking installed apps and if the settings are enabled.

I'm also not noticing E2E tests of when both the token blacklist app and the token family app are both utilized. How does the blacklisting work when they're both in use?

Andrew-Chen-Wang · 2025-10-02T18:11:54Z

docs/family_app.rst

+Family app
+===========
+
+The **Token Family** system provides a way to group refresh and access tokens into logical families,


A reference to the original Auth0 post could be helpful

Andrew-Chen-Wang · 2025-10-02T18:12:19Z

docs/family_app.rst

+:doc:`/blacklist_app`.
+
+By organizing tokens into families, you gain finer control over user sessions and potential compromises.
+For example, when the settings ``BLACKLIST_AFTER_ROTATION`` and ``TOKEN_FAMILY_BLACKLIST_ON_REUSE`` are


What happens if you don't have the token blacklist app on?

Andrew-Chen-Wang · 2025-10-02T18:14:20Z

docs/family_app.rst

+which will delete any families from the token family list and family blacklist that have
+expired. The command will not affect families that have ``None`` as their expiration.
+You should set up a cron job on your server or hosting platform which
+runs this command daily.


What is the recommended pattern for migrating to this new family token system? I noticed that we silently allow tokens without the family, but is the recommended approach to force invalidate all tokens without family?

I understand the code silently allows the tokens without the family claim, but it should be noted somewhere here in the docs

Andrew-Chen-Wang · 2025-10-02T18:14:59Z

docs/family_app.rst

+
+  urlpatterns = [
+    ...
+    path('api/token/family/blacklist/', TokenFamilyBlacklistView.as_view(), name='token_family_blacklist'),


Why would we want to use a different view for token family blacklist? Shouldn't this simply replace the need for the Blacklist url itself?

Andrew-Chen-Wang · 2025-10-02T18:16:55Z

tests/test_integration.py

@@ -1,11 +1,15 @@
 from datetime import timedelta
+from importlib import reload


dangling import

juanbailon added 23 commits October 1, 2025 14:59

feat: initialize token_family app structure

3d26e19

feat: add token_family app initialization and configuration

f17d862

feat: add models for token_family app

371c01d

migration: add initial migrations for token_family models

db58cdb

feat: add custom exceptions for token family support

771a3ef

- Added for handling blacklisted refresh tokens. - Introduced to indicate missing token family setup.

feat: add TokenFamilyBlacklistView

0893e65

feat: validate token family settings on app startup in TokenFamilyConfig

987ad32

migration: rename TokenFamilyBlacklist model to BlacklistedTokenFamily

76412d4

feat: add management command to delete expired token families from th…

d0341a8

…e database

feat: add default blacklist cache related settings

47451fa

- SJWT_CACHE_NAME: selects the Django cache alias - CACHE_BLACKLISTED_REFRESH_TOKENS and CACHE_BLACKLISTED_FAMILIES: toggle caching - TTL and key prefix settings added for each blacklist type

feat: add cache.py for handling caching logic for blacklisted tokens …

09215d6

…and families

feat: integrate caching logic for blacklisted refresh tokens and fami…

e488fac

…lies - Added cache check for blacklisted refresh tokens in TokenVerifySerializer - Enhanced BlacklistMixin and FamilyMixin to support caching for blacklisted tokens and families.

test: add tests for blacklist cache functionality

aa17342

- Added test_cache.py. - Updated conftest.py and test_integration.py.

feat: add admin interface for TokenFamily and BlacklistedTokenFamily …

14da7e7

…models

docs: add token family feature documentation

2805617

- Included token_family app in conf.py - Added family_app.rst for token family details - Documented related family settings in settings.rst - Linked family_app in index.rst toctree

docs: add cache support documentation

17eef74

- Added cache_support.rst - Updated 'index.rst' to include the new page in the toctree - Documented related cache settings in settings.rst

docs: include token_family and cache.py in Sphinx build-docs

afb06dd

fix: update blacklist() type hint, blacklist_family() type hint and r…

d691bc6

…eturn values, and TokenVerifySerializer check. resolves jazzband#911

juanbailon force-pushed the feature/token-family-and-cache branch from 1a79ec7 to d691bc6 Compare October 1, 2025 20:49

[pre-commit.ci] auto fixes from pre-commit.com hooks

5c6814d

for more information, see https://pre-commit.ci

Andrew-Chen-Wang reviewed Oct 2, 2025

View reviewed changes

Andrew-Chen-Wang added the enhancement label Oct 2, 2025

Andrew-Chen-Wang requested changes Oct 2, 2025

View reviewed changes

		old_name="TokenFamilyBlacklist",
		new_name="BlacklistedTokenFamily",

		@@ -0,0 +1,4 @@
		from django import VERSION

		if VERSION < (3, 2):

		from tests.utils import override_api_settings


		class TestBlacklistCache(TestCase):



		# Singleton instance for centralized cache management
		blacklist_cache = BlacklistCache()


		return data

		def _get_refresh_token(self, token_str: str) -> RefreshToken:

		return {}


		class TokenFamilyBlacklistSerializer(serializers.Serializer):

	f"Token of user:{user_id} does not have a family_id. Skipping family blacklist check."
	f"Token of user: {user_id} does not have a family_id. Skipping family blacklist check."

		@@ -1,11 +1,15 @@
		from datetime import timedelta
		from importlib import reload

feat: implement Token Family system and optional blacklist cache #913

Are you sure you want to change the base?

feat: implement Token Family system and optional blacklist cache #913

Uh oh!

Conversation

juanbailon commented May 20, 2025

Uh oh!

Andrew-Chen-Wang left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Andrew-Chen-Wang commented Oct 2, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Andrew-Chen-Wang left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Andrew-Chen-Wang left a comment •

edited

Loading

Andrew-Chen-Wang commented Oct 2, 2025 •

edited

Loading