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. Gives a visitor a persistent anon@<uuid>
identity plus a short-lived access token before they authenticate, with up to 1 KB of metadata attached at
creation. Framework-agnostic RWA core — mounts no routes and sets no cookies.
identifier, isolated from the authenticated _a0_session store. AnonymousSession never
exposes the raw session token to the caller.
Adds a token renewal ladder on get_token: fresh cached access token is returned;
expired access token is re-minted with the session token; an expired or invalid session
token silently creates a brand-new session, once, surfaced via
AnonymousSession.is_new. Metadata is lost and sub changes on that silent re-mint — this
never raises, since an anonymous pre-login 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.
Adds typed anonymous option/response models (AnonymousSession,
AnonymousTokenResponse, AnonymousSessionContext, AnonymousSessionIntrospection) and a
typed error hierarchy under AnonymousApiError, including five config subclasses
(AnonymousFeatureNotEnabledError, AnonymousClientNotEnabledError,
AnonymousClientNotSupportedError, AnonymousResourceServerError, AnonymousScopeError)
Enforces metadata safeguards client-side before any network call: rejects dangerous keys
(__proto__, constructor, prototype) and enforces a 1 KB (UTF-8 JSON) size cap.

Testing

As part of manual testing following flows have been completed:

Happy Path

Create — POST /anonymous/session mints an anon@<uuid> identity; returns session_token (opaque JWE, ANONYMOUS_SESSION_ prefix) + access_token (RS256 JWS, audience-bound).
Get token — GET /anonymous/session walks the renewal ladder: cached → re-mint via session_token → silent new session.
Login injection — GET /anonymous/login-url confirms session_token is auto-injected into /authorize (session_token_injected: true), no call-site change.
Logout — POST /anonymous/logout best-effort calls /anonymous/logout, then always clears local store; post-logout GET returns AnonymousTokenError (fail-closed). Issued access tokens self-expire (not
revoked).

Negative / Fail-Closed

#	Scenario	Expected result	Status
N1	invalid audience	`anonymous_resource_server_error`	✅
N2	ungranted scope	`anonymous_scope_error`	—
N3	non-string metadata value	`invalid_metadata` (local, pre-network)	✅
N4	dangerous key `__proto__`	`invalid_metadata`	✅
N5	metadata >1KB	`metadata_too_large`	✅
N6	no session	`AnonymousTokenError`	✅

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

+            try:
+                async with self._get_http_client() as client:
+                    await client.post(f"{base_url}/anonymous/logout", json=body)
+            except httpx.HTTPError:


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.

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.

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.

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

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 AI found potential problems Aug 14, 2026

View reviewed changes

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

try:

async with self._get_http_client() as client:

await client.post(f"{base_url}/anonymous/logout", json=body)

except httpx.HTTPError:

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 added 5 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

		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

Happy Path

Negative / Fail-Closed

Checklist

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!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

rmad17 commented Aug 14, 2026 •

edited

Loading

rmad17 Aug 19, 2026 •

edited

Loading