feat: add support for anonymous sessions by rmad17 · Pull Request #156 · auth0/auth0-server-python

rmad17 · 2026-08-14T01:59:47Z

Changes

Added

Adds ServerClient.anonymous for pre-login anonymous sessions: create_session, get_token, introspect, and logout. A visitor gets a persistent anon@ identity plus a short-lived access token before they authenticate, with up to 1 KB of metadata attached at creation. The core is framework-agnostic RWA: it mounts no routes and sets no cookies. Tokens live in the integrator's store under a dedicated _a0_anon identifier, isolated from the authenticated _a0_session store. AnonymousSession never exposes the raw session token beyond what the caller already stored.
Adds a token renewal ladder on get_token. A fresh cached access token is returned as-is. An expired access token is re-minted using the stored session token. An expired or invalid session token silently creates a brand-new session once. On that silent re-mint the metadata is lost and sub changes, and the returned AnonymousSession looks identical to a cached or re-minted one, so callers get no field-level signal that a new identity was issued. This path never raises, since a pre-login anonymous session carries no authorization.
Injects the anonymous session_token into start_interactive_login() automatically when a session is active, sourced only from the SDK's own encrypted store and bound into TransactionData under the existing state binding. Injection is skipped when Pushed Authorization Requests are enabled, since the parameters go to the PAR endpoint instead.
Adds typed anonymous option and response models (AnonymousSession, AnonymousTokenResponse, AnonymousCreateTokenResponse, AnonymousSessionContext, AnonymousSessionIntrospection) and a typed error hierarchy under AnonymousSessionApiError. The config subclasses (AnonymousSessionFeatureNotEnabledError, AnonymousSessionClientNotEnabledError, AnonymousSessionClientNotSupportedError, AnonymousSessionResourceServerError, AnonymousSessionScopeError) extend AnonymousSessionCreateError.
Enforces metadata safeguards client-side before any network call: rejects dangerous keys (proto, constructor, prototype) with code invalid_metadata, and enforces a 1 KB UTF-8 JSON size cap with code metadata_too_large.

Testing

Manual testing covered the following flows.

Happy path

Create - create_session mints an anon@ identity and returns a session_token plus an audience-bound access_token, both taken from the /anonymous/token response.
Get token - get_token walks the renewal ladder: cached, then re-mint via the session token, then a single silent new session.
Login injection - start_interactive_login() auto-injects the session_token into /authorize with no call-site change (skipped under PAR).
Logout - logout best-effort calls the server, then always clears the local store. A post-logout get_token raises AnonymousSessionTokenError (fail closed). Already-issued access tokens self-expire rather than being revoked.

Negative / fail-closed

#	Scenario	Expected result	Status
N1	invalid audience	anonymous_resource_server_error	verified
N2	ungranted scope	anonymous_scope_error	needs double checking
N3	non-string metadata value	invalid_metadata (local, pre-network)	verified
N4	dangerous key proto	invalid_metadata	verified
N5	metadata over 1 KB	metadata_too_large	verified
N6	no session	`AnonymousSessionTokenError`	verified

This change adds unit test coverage
This change adds integration test coverage
This change has been tested on the latest version of the platform/language or why not

Checklist

I have read the Auth0 general contribution guidelines
I have read the Auth0 Code of Conduct
All existing and new tests complete without errors

… validations for options params

yogeshchoudhary147

Reviewed against both the implementation and the SDK requirements doc. Inline comments below cover spec deviations, confirmed bugs, and test gaps. Two earlier findings have been retracted: the _normalize_url str.replace concern (false positive for real-world domain inputs) and the claim that httpx.HTTPError catches 4xx/5xx responses (it does not — those are only raised via raise_for_status(), which logout() never calls).

yogeshchoudhary147 · 2026-08-18T03:54:04Z

+# Anonymous Session Error Classes
+# =============================================================================
+
+class AnonymousApiError(Auth0Error):


Spec deviation — error class names diverge from the requirements doc.

The SDK requirements doc specifies:

class AnonymousSessionError(Auth0Error): ... class AnonymousSessionCreateError(AnonymousSessionError): ... class AnonymousSessionTokenExpiredError(AnonymousSessionError): ...

This implementation ships AnonymousApiError, AnonymousCreateError, AnonymousTokenError, etc.

If the JS SDKs use the spec names, Python's public error surface will be inconsistent across SDKs. Any shared developer-facing error-handling documentation will show different class names per platform. If the rename is intentional, the spec should be updated to reflect it.

This was intentionally done by following the practice MFA error classes.
MfaApiError's own action subclasses (MfaListAuthenticatorsError, MfaEnrollmentError, MfaChallengeError, MfaVerifyError) are flat — domain + action, no inserted noun.
However, on digging deeper found that there are exceptions like MfaTokenExpiredError/MfaTokenInvalidError where a noun - Token is added. Given that there is the presence of these exceptions I think it makes sense to keep the names consistent with JS names.
Exception is the base error which will be AnonymousSessionApiError instead of AnonymousSessionError to maintain consistency with other base errors in the SDK. Will update the doc spec with this exception.

yogeshchoudhary147 · 2026-08-18T03:54:05Z

+        super().__init__(code, message, cause)
+
+
+class AnonymousLogoutError(AnonymousApiError):


AnonymousLogoutError is dead code — it can never be raised.

_map_anonymous_error() maps operation == "logout" to this class, but logout() never calls _map_anonymous_error(). The except httpx.HTTPError in logout() catches only transport-level failures; non-2xx HTTP responses are silently ignored because the response object is never inspected at all. The only exception logout() can raise to a caller is ConfigurationError from _require_store().

Either:

logout() should check the response status, call _map_anonymous_error(), and re-raise on non-2xx (while still clearing local state), or

AnonymousLogoutError and the logout branch in _map_anonymous_error() should be removed.

logout() now checks response.status_code, maps non-2xx via _map_anonymous_error(), and raises AnonymousSessionLogoutError - but only after local state is cleared, so the session is always gone locally
regardless of whether the remote call succeeded.

session_expired/invalid_session_token on the logout call itself are still swallowed. This isn't the SDK doc's renewal carve-out applied literally - that carve-out is paired with a remint, which logout has no equivalent of. It's swallowed because the goal state (no active anonymous session) is already true, so raising would flag a non-failure. Everything else surfaces per "surface all other errors... do not swallow them."

yogeshchoudhary147 · 2026-08-18T03:54:05Z

+
+    def __init__(
+        self,
+        domain,


domain parameter is untyped.

Every sibling client (MfaClient, MyAccountClient) types this as Union[str, Callable]. This is the only one that leaves it bare. Inconsistency will surface under type checkers and makes the parameter contract invisible to IDE users.

Valid point.

yogeshchoudhary147 · 2026-08-18T03:54:05Z

+                raise AnonymousCreateError(
+                    f"metadata key '{key}' is not allowed", code="invalid_metadata"
+                )
+            if not isinstance(value, str):


Metadata value restriction is narrower than the spec and should be confirmed against the actual API.

The requirements doc defines metadata as Record<string, unknown> (any JSON value). This implementation rejects non-string values client-side. If the Auth0 API actually accepts non-string values, this check incorrectly blocks valid callers. If the API only accepts strings in practice, the spec is wrong and needs updating.

Consequently, AnonymousSessionContext.metadata is typed Optional[dict[str, Any]] (any value), while creation only permits dict[str, str]. The type annotation does not express the constraint, so the model's round-trip deserialization of a stored context containing an integer value would silently succeed at the Pydantic level.

yogeshchoudhary147 · 2026-08-18T03:54:05Z

+
+        now = int(time.time())
+        new_context = AnonymousSessionContext(
+            session_token=token_response.session_token or context.session_token,


or idiom silently swallows empty strings for Optional[str] fields.

session_token=token_response.session_token or context.session_token, sub=token_response.sub or context.sub, session_id=token_response.session_id or context.session_id,

"" or context.X falls back to the stale context value, so if the API ever returns an empty string for any of these, the old value is silently persisted. Prefer explicit None-checks:

session_token=token_response.session_token if token_response.session_token is not None else context.session_token,

This is consistent with how session_expires_in is handled two lines below.

yogeshchoudhary147 · 2026-08-18T03:54:05Z

+                    "Failed to parse anonymous introspection response"
+                ) from e
+
+    async def logout(self, store_options: Optional[dict[str, Any]] = None) -> None:


logout() never raises AnonymousLogoutError — see the comment on error/__init__.py:392.

Additionally, there is no test covering the branch at line ~693 where _decrypt_context raises _AnonymousSessionExpired (sets context = None and skips the server call). That path clears local state correctly but is untested.

Both the points are addressed in ee70a38 and 15e4732

yogeshchoudhary147 · 2026-08-18T03:54:05Z

+    access_token: str
+    token_type: str = "Bearer"
+    expires_in: int
+    session_token: Optional[str] = None


session_token is Optional here but effectively required on the create path.

_create_session_at() validates the response with this model and then immediately does:

if not token_response.session_token: raise AnonymousCreateError("Anonymous token response missing required fields")

The Optional typing exists to accommodate the re-mint path (where the server may not return a new session token). Consider a separate narrow model for the create response, or at minimum a Pydantic validator that enforces presence, so the constraint is expressed in the type rather than in a manual post-validation check.

Addressed via 6304af8 and 61d727e

yogeshchoudhary147 · 2026-08-18T03:54:05Z

            domain=origin_domain,
            redirect_uri=auth_params.get("redirect_uri"),
            organization=resolved_org,
+            session_token=anonymous_session_token,


Question: should complete_interactive_login() promote session_token from TransactionData into StateStore?

The auth0-server-js section of the requirements doc says:

completeInteractiveLogin() — on callback, read the session token back from TransactionStore and promote it into StateStore as part of the authenticated session.

The Python section does not mention this step. The session token is saved into TransactionData here but nothing reads it back during the callback. If auth0-fastapi (GA) will need to reconstruct the anonymous session after login, this plumbing would need to exist in auth0-server-python first. Please confirm the omission is intentional for EA scope.

This is out of EA scope and will be picked up when auth0-fastapi is worked upon.

yogeshchoudhary147 · 2026-08-18T03:54:05Z

+# =============================================================================
+
+
+class _OneSlotStore:


_OneSlotStore is duplicated — identical class exists as OneSlotStore in test_anonymous_client.py:41.

The explanatory comment about why AsyncMock is insufficient (identifier-as-salt, not location key) exists in both files. Moving it to conftest.py as a shared fixture would eliminate the duplication and keep the explanation in one place.

yogeshchoudhary147 · 2026-08-18T03:54:05Z

+SECRET = "test-secret-long-enough-for-encryption"
+
+
+class OneSlotStore:


Two test coverage gaps in introspect():

No test for what happens when the stored context is corrupted (invalid JWE) — introspect() should raise AnonymousIntrospectError, but this branch is untested. Compare to the equivalent test in TestGetToken.test_corrupted_stored_token_triggers_silent_new_session.

The TestLogout class has no test for the context = None branch (corrupted/missing context skips the server call but still clears local state).

…s to match the spec

…t None checks instead of or

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

… auth and remint replay

# Conflicts: # README.md # src/auth0_server_python/auth_server/__init__.py # src/auth0_server_python/auth_server/server_client.py # src/auth0_server_python/auth_types/__init__.py

+        with patch("httpx.AsyncClient", fake_http):
+            await client.get_token()
+        _, url, _ = fake_http.calls[0]
+        assert url.startswith("https://tenant-b.auth0.local")


rmad17 added 3 commits August 11, 2026 11:21

Added Anonymous Session Support Changes

796c9ed

docs: clean up, formatting improvement and docs content update

a2a0afe

chore: renaming of classes to bring consistency, adding fallback with…

4c1a173

… validations for options params

github-advanced-security Bot found potential problems Aug 14, 2026

View reviewed changes

Comment thread src/auth0_server_python/auth_server/anonymous_client.py Fixed

rmad17 added 3 commits August 14, 2026 09:45

chore: trimmed comments

118b25d

docs: Optimized example docs

5d6f511

docs: Updated docs to remove semicolon

c5d5cff

rmad17 marked this pull request as ready for review August 14, 2026 06:11

rmad17 requested a review from a team as a code owner August 14, 2026 06:11

Merge branch 'main' into feat/anonymous-sessions

29e6e0f

yogeshchoudhary147 reviewed Aug 18, 2026

View reviewed changes

rmad17 and others added 13 commits August 19, 2026 22:03

fix: rename Anonymous Session errors to add Session in the error name…

cfb000a

…s to match the spec

fix: Resolved logout error correctly

ee70a38

fix: make AnonymousClient domain typed

3b25bcf

fix: widened metadata types

307ba7d

fix: session_token, sub, session_id in _remint now use explicit is no…

c3e6fd9

…t None checks instead of or

fix: seperate response structures for session token in create and remint

6304af8

test: extract shared OneSlotStore fake into store_fakes

edeb3d1

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

fix: run anonymous session domain-mismatch check in static mode too

bc40a56

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

test: cover corrupted anonymous context in introspect and logout

15e4732

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

fix: drop sub,session_id from anonymous sessions response, fix logout…

61d727e

… auth and remint replay

fix: remove is_new from AnonymousSession, unused signal never in spec

ead816f

docs: remove is_new from AnonymousSession field list

090b798

Merge branch 'main' into feat/anonymous-sessions

9364261

# Conflicts: # README.md # src/auth0_server_python/auth_server/__init__.py # src/auth0_server_python/auth_server/server_client.py # src/auth0_server_python/auth_types/__init__.py

github-advanced-security Bot found potential problems Aug 25, 2026

View reviewed changes

Comment thread src/auth0_server_python/tests/test_anonymous_client.py

with patch("httpx.AsyncClient", fake_http):

await client.get_token()

_, url, _ = fake_http.calls[0]

assert url.startswith("https://tenant-b.auth0.local")

		super().__init__(code, message, cause)


		class AnonymousLogoutError(AnonymousApiError):

		# =============================================================================


		class _OneSlotStore:

		SECRET = "test-secret-long-enough-for-encryption"


		class OneSlotStore:

Uh oh!

Conversation

rmad17 commented Aug 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Changes

Testing

Checklist

Uh oh!

Uh oh!

yogeshchoudhary147 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

rmad17 Aug 19, 2026 • 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!

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!

3 participants

rmad17 commented Aug 14, 2026 •

edited

Loading

rmad17 Aug 19, 2026 •

edited

Loading