Skip to content

feat: add server-side token storage with OBO caching - #136

Merged
kishore7snehil merged 7 commits into
mainfrom
feat/obo-token-storage
Oct 22, 2026
Merged

kishore7snehil merged 7 commits into
mainfrom
feat/obo-token-storage

Conversation

@kishore7snehil

Copy link
Copy Markdown
Contributor

📋 Changes

This PR adds pluggable server-side token storage to auth0-api-python and uses it to cache On Behalf Of exchanges. When a token store is configured, get_token_on_behalf_of() (already in main from a prior PR) reuses previously exchanged tokens instead of hitting the token endpoint on every call.

✨ Features

  • Pluggable Token Store: New AbstractTokenStore ABC for server-side token persistence, with JWE-at-rest encrypt and decrypt helpers built in. Subclasses implement get, set, and delete.
  • Scope-Indexed Store: New IndexedTokenStore variant that maintains a scope index, required for non-strict scope matching.
  • OBO Response Caching: get_token_on_behalf_of() now caches exchanged tokens when token_store is set.
  • Scope Matching Modes: New scope_matching option. "strict" reuses a cached token only on an exact scope match. "non_strict" reuses a cached token when its granted scopes cover the request, and requires an IndexedTokenStore.
  • At-Rest Encryption: New encryption.py module providing the JWE helpers used by the store.
  • Type Safety: New TokenSet and TokenIndexMember TypedDicts and a VerifiedToken dataclass.

🔧 API Changes

  • Added token_store (AbstractTokenStore, default None) to ApiClientOptions. When set, OBO exchanges are cached.
  • Added scope_matching (str, default "strict") to ApiClientOptions. Using "non_strict" without an IndexedTokenStore raises ConfigurationError.
  • New classes: AbstractTokenStore, IndexedTokenStore
  • New types: TokenSet (TypedDict), TokenIndexMember (TypedDict), VerifiedToken (dataclass)
  • New error: TokenStoreError (status 500), raised when the configured store backend fails
  • Newly exported at top level: GetTokenByExchangeProfileError

📖 Documentation

  • Added docs/TokenStorage.md covering the AbstractTokenStore contract, a Redis implementation example, and the scope matching modes
  • Updated README.md with a token storage section
  • Updated EXAMPLES.md with token storage and caching examples

🧪 Testing

  • This change adds test coverage
  • This change has been tested on the latest version of the platform/language

Contributor Checklist

Comment thread src/auth0_api_python/api_client.py Fixed
Comment thread src/auth0_api_python/api_client.py Fixed
@kishore7snehil
kishore7snehil marked this pull request as ready for review October 6, 2026 06:46
@kishore7snehil
kishore7snehil requested a review from a team as a code owner October 6, 2026 06:46
Comment thread src/auth0_api_python/errors.py Resolved
Comment thread EXAMPLES.md Resolved
Comment thread docs/TokenStorage.md Resolved
Comment thread src/auth0_api_python/api_client.py Resolved
Comment thread src/auth0_api_python/token_store.py Resolved
@kishore7snehil
kishore7snehil force-pushed the feat/org-policy-enforcement branch from 8f87351 to f4b287d Compare October 8, 2026 04:07
@kishore7snehil
kishore7snehil force-pushed the feat/obo-token-storage branch from 42680cd to d57457d Compare October 8, 2026 04:07
@kishore7snehil
kishore7snehil force-pushed the feat/org-policy-enforcement branch from f4b287d to ae99659 Compare October 8, 2026 04:22
@kishore7snehil
kishore7snehil force-pushed the feat/obo-token-storage branch from d57457d to 75faa2d Compare October 8, 2026 04:22
nandan-bhat
nandan-bhat previously approved these changes Oct 22, 2026
Base automatically changed from feat/org-policy-enforcement to main October 22, 2026 06:48
@kishore7snehil
kishore7snehil dismissed nandan-bhat’s stale review October 22, 2026 06:48

The base branch was changed.

Add pluggable server-side token storage and use it to cache On Behalf Of
exchanges. When a token_store is configured, get_token_on_behalf_of()
reuses previously exchanged tokens instead of hitting the token endpoint
on every call.

- AbstractTokenStore ABC with JWE at-rest encryption helpers
- IndexedTokenStore for non-strict scope matching
- OBO cache wiring in get_token_on_behalf_of()
- scope_matching option: strict (exact match) or non_strict (coverage)
- TokenSet, TokenIndexMember TypedDicts and VerifiedToken dataclass
- TokenStoreError (status 500) for backend failures
- Remove TokenStoreError, store failures are logged and treated as a cache miss
- Use module loggers instead of the root logger
- Stop the index lookup at the first failed store read
- Treat a whitespace-only scope as unscoped and compute the current time once per lookup
- Fall back to a hash fingerprint when the token payload is not a JSON object
- Require a token_store subclassing IndexedTokenStore for scope_matching='non_strict'
- Require a token store secret of at least 32 characters
- Clarify get_token_on_behalf_of docs and pass verified claims in the OBO caching example
- Clamp the Redis example ttl to at least 1 second
@kishore7snehil
kishore7snehil merged commit d6bc468 into main Oct 22, 2026
7 checks passed
@kishore7snehil
kishore7snehil deleted the feat/obo-token-storage branch October 22, 2026 07:16
@kishore7snehil kishore7snehil mentioned this pull request Nov 11, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants