auth0-api-python 1.0.0b7__tar.gz → 1.0.0b9__tar.gz

{auth0_api_python-1.0.0b7 → auth0_api_python-1.0.0b9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: auth0-api-python
-Version: 1.0.0b7
+Version: 1.0.0b9
 Summary: SDK for verifying access tokens and securing APIs with Auth0, using Authlib.
 License: MIT
 License-File: LICENSE
@@ -41,7 +41,8 @@ This SDK provides comprehensive support for securing APIs with Auth0-issued acce
 
 ### **Core Features**
 - **Unified Entry Point**: `verify_request()` - automatically detects and validates Bearer or DPoP schemes
-- **OIDC Discovery** - Automatic fetching of Auth0 metadata and JWKS
+- **Multi-Custom Domain (MCD)** - Accept tokens from multiple Auth0 domains with static lists or dynamic resolvers
+- **OIDC Discovery** - Automatic fetching of Auth0 metadata and JWKS with per-issuer caching
 - **JWT Validation** - Complete RS256 signature verification with claim validation
 - **DPoP Proof Verification** - Full RFC 9449 compliance with ES256 signature validation
 - **Flexible Configuration** - Support for both "Allowed" and "Required" DPoP modes
@@ -235,6 +236,92 @@ except ApiError as e:
 
 More info: https://auth0.com/docs/authenticate/custom-token-exchange
 
+#### On Behalf Of Token Exchange
+
+Use `get_token_on_behalf_of()` when your API receives an `Auth0` access token for itself and needs
+to exchange it for another `Auth0` access token targeting a downstream API while preserving the
+same user identity. This is especially useful for `MCP` servers and other intermediary APIs that
+need to call downstream APIs on behalf of the user.
+
+The following example verifies the incoming access token for your API, exchanges it for a token for the downstream API, and then calls the downstream API with the exchanged token.
+
+```python
+import httpx
+
+async def handle_calendar_request(incoming_access_token: str):
+    await api_client.verify_access_token(access_token=incoming_access_token)
+
+    result = await api_client.get_token_on_behalf_of(
+        access_token=incoming_access_token,
+        audience="https://calendar-api.example.com",
+        scope="calendar:read calendar:write"
+    )
+
+    async with httpx.AsyncClient() as client:
+        downstream_response = await client.get(
+            "https://calendar-api.example.com/events",
+            headers={"Authorization": f"Bearer {result['access_token']}"}
+        )
+
+    downstream_response.raise_for_status()
+
+    return downstream_response.json()
+```
+
+The OBO wrapper reuses the existing RFC 8693 exchange support and fixes both token-type parameters
+to Auth0 access-token exchange. In the current implementation, the SDK forwards the incoming access
+token as the `subject_token` and relies on Auth0 to handle any DPoP-specific behavior for that token.
+The OBO result only includes access-token-oriented fields. It does not expose `id_token` or
+`refresh_token`.
+
+#### Inspecting Delegation After Token Verification
+
+When a downstream API or `MCP` server receives an access token that may have been issued through
+delegation, it can verify the token first and then inspect the `act` claim to identify the current
+actor for authorization and the full delegation chain for logging or audit.
+
+```python
+import logging
+
+from auth0_api_python import (
+    ApiClient,
+    ApiClientOptions,
+    get_current_actor,
+    get_delegation_chain,
+)
+
+logger = logging.getLogger(__name__)
+
+api_client = ApiClient(ApiClientOptions(
+    domain="<AUTH0_DOMAIN>",
+    audience="<AUTH0_AUDIENCE>",
+))
+
+async def authorize_delegated_request(access_token: str):
+    claims = await api_client.verify_access_token(access_token=access_token)
+
+    current_actor = get_current_actor(claims)
+    delegation_chain = get_delegation_chain(claims)
+
+    if current_actor != "mcp_server_client_id":
+        raise PermissionError("unexpected actor")
+
+    logger.info(
+        "delegated request",
+        extra={
+            "user_sub": claims["sub"],
+            "current_actor": current_actor,
+            "delegation_chain": delegation_chain,
+        },
+    )
+
+    return claims
+```
+
+Only the outermost `act.sub` represents the current actor and should be used for authorization
+decisions. Nested `act` values represent prior actors in the delegation chain and are better suited
+for logging, audit, or attribution.
+
 #### Requiring Additional Claims
 
 If your application demands extra claims, specify them with `required_claims`:
@@ -250,9 +337,6 @@ If the token lacks `my_custom_claim` or fails any standard check (issuer mismatc
 
 ### 6. DPoP Authentication
 
-> [!NOTE]  
-> This feature is currently available in [Early Access](https://auth0.com/docs/troubleshoot/product-lifecycle/product-release-stages#early-access). Please reach out to Auth0 support to get it enabled for your tenant.
-
 This library supports **DPoP (Demonstrating Proof-of-Possession)** for enhanced security, allowing clients to prove possession of private keys bound to access tokens.
 
 #### Allowed Mode (Default)
@@ -303,6 +387,50 @@ api_client = ApiClient(ApiClientOptions(
 ))
 ```
 
+### 7. Multi-Custom Domain (MCD) Support
+
+If your Auth0 tenant has multiple custom domains, or you're migrating between domains, the SDK can accept tokens from any of them:
+
+#### Static Domain List
+
+```python
+from auth0_api_python import ApiClient, ApiClientOptions
+
+api_client = ApiClient(ApiClientOptions(
+    domains=[
+        "tenant.auth0.com",
+        "auth.example.com",
+        "auth.acme.org"
+    ],
+    audience="https://api.example.com"
+))
+
+# Tokens from any of the three domains are accepted
+claims = await api_client.verify_access_token(access_token)
+```
+
+#### Dynamic Resolver
+
+For runtime domain resolution based on request context:
+
+```python
+from auth0_api_python import ApiClient, ApiClientOptions, DomainsResolverContext
+
+def resolve_domains(context: DomainsResolverContext) -> list[str]:
+    # Determine allowed domains based on the request
+    return ["tenant.auth0.com", "auth.example.com"]
+
+api_client = ApiClient(ApiClientOptions(
+    domains=resolve_domains,
+    audience="https://api.example.com"
+))
+```
+
+For hybrid mode (migration scenarios), resolver patterns, error handling, and caching configuration, see the full guides:
+
+- **[Multi-Custom Domain Guide](docs/MultipleCustomDomain.md)** - Configuration modes, resolver patterns, migration, error handling
+- **[Caching Guide](docs/Caching.md)** - Cache tuning, custom adapters (Redis, Memcached)
+
 ## Feedback
 
 ### Contributing
@@ -336,3 +464,4 @@ Please do not report security vulnerabilities on the public GitHub issue tracker
 <p align="center">
   This project is licensed under the MIT license. See the <a href="https://github.com/auth0/auth0-api-python/LICENSE"> LICENSE</a> file for more info.
 </p>
+

{auth0_api_python-1.0.0b7 → auth0_api_python-1.0.0b9}/README.md

@@ -17,7 +17,8 @@ This SDK provides comprehensive support for securing APIs with Auth0-issued acce
 
 ### **Core Features**
 - **Unified Entry Point**: `verify_request()` - automatically detects and validates Bearer or DPoP schemes
-- **OIDC Discovery** - Automatic fetching of Auth0 metadata and JWKS
+- **Multi-Custom Domain (MCD)** - Accept tokens from multiple Auth0 domains with static lists or dynamic resolvers
+- **OIDC Discovery** - Automatic fetching of Auth0 metadata and JWKS with per-issuer caching
 - **JWT Validation** - Complete RS256 signature verification with claim validation
 - **DPoP Proof Verification** - Full RFC 9449 compliance with ES256 signature validation
 - **Flexible Configuration** - Support for both "Allowed" and "Required" DPoP modes
@@ -211,6 +212,92 @@ except ApiError as e:
 
 More info: https://auth0.com/docs/authenticate/custom-token-exchange
 
+#### On Behalf Of Token Exchange
+
+Use `get_token_on_behalf_of()` when your API receives an `Auth0` access token for itself and needs
+to exchange it for another `Auth0` access token targeting a downstream API while preserving the
+same user identity. This is especially useful for `MCP` servers and other intermediary APIs that
+need to call downstream APIs on behalf of the user.
+
+The following example verifies the incoming access token for your API, exchanges it for a token for the downstream API, and then calls the downstream API with the exchanged token.
+
+```python
+import httpx
+
+async def handle_calendar_request(incoming_access_token: str):
+    await api_client.verify_access_token(access_token=incoming_access_token)
+
+    result = await api_client.get_token_on_behalf_of(
+        access_token=incoming_access_token,
+        audience="https://calendar-api.example.com",
+        scope="calendar:read calendar:write"
+    )
+
+    async with httpx.AsyncClient() as client:
+        downstream_response = await client.get(
+            "https://calendar-api.example.com/events",
+            headers={"Authorization": f"Bearer {result['access_token']}"}
+        )
+
+    downstream_response.raise_for_status()
+
+    return downstream_response.json()
+```
+
+The OBO wrapper reuses the existing RFC 8693 exchange support and fixes both token-type parameters
+to Auth0 access-token exchange. In the current implementation, the SDK forwards the incoming access
+token as the `subject_token` and relies on Auth0 to handle any DPoP-specific behavior for that token.
+The OBO result only includes access-token-oriented fields. It does not expose `id_token` or
+`refresh_token`.
+
+#### Inspecting Delegation After Token Verification
+
+When a downstream API or `MCP` server receives an access token that may have been issued through
+delegation, it can verify the token first and then inspect the `act` claim to identify the current
+actor for authorization and the full delegation chain for logging or audit.
+
+```python
+import logging
+
+from auth0_api_python import (
+    ApiClient,
+    ApiClientOptions,
+    get_current_actor,
+    get_delegation_chain,
+)
+
+logger = logging.getLogger(__name__)
+
+api_client = ApiClient(ApiClientOptions(
+    domain="<AUTH0_DOMAIN>",
+    audience="<AUTH0_AUDIENCE>",
+))
+
+async def authorize_delegated_request(access_token: str):
+    claims = await api_client.verify_access_token(access_token=access_token)
+
+    current_actor = get_current_actor(claims)
+    delegation_chain = get_delegation_chain(claims)
+
+    if current_actor != "mcp_server_client_id":
+        raise PermissionError("unexpected actor")
+
+    logger.info(
+        "delegated request",
+        extra={
+            "user_sub": claims["sub"],
+            "current_actor": current_actor,
+            "delegation_chain": delegation_chain,
+        },
+    )
+
+    return claims
+```
+
+Only the outermost `act.sub` represents the current actor and should be used for authorization
+decisions. Nested `act` values represent prior actors in the delegation chain and are better suited
+for logging, audit, or attribution.
+
 #### Requiring Additional Claims
 
 If your application demands extra claims, specify them with `required_claims`:
@@ -226,9 +313,6 @@ If the token lacks `my_custom_claim` or fails any standard check (issuer mismatc
 
 ### 6. DPoP Authentication
 
-> [!NOTE]  
-> This feature is currently available in [Early Access](https://auth0.com/docs/troubleshoot/product-lifecycle/product-release-stages#early-access). Please reach out to Auth0 support to get it enabled for your tenant.
-
 This library supports **DPoP (Demonstrating Proof-of-Possession)** for enhanced security, allowing clients to prove possession of private keys bound to access tokens.
 
 #### Allowed Mode (Default)
@@ -279,6 +363,50 @@ api_client = ApiClient(ApiClientOptions(
 ))
 ```
 
+### 7. Multi-Custom Domain (MCD) Support
+
+If your Auth0 tenant has multiple custom domains, or you're migrating between domains, the SDK can accept tokens from any of them:
+
+#### Static Domain List
+
+```python
+from auth0_api_python import ApiClient, ApiClientOptions
+
+api_client = ApiClient(ApiClientOptions(
+    domains=[
+        "tenant.auth0.com",
+        "auth.example.com",
+        "auth.acme.org"
+    ],
+    audience="https://api.example.com"
+))
+
+# Tokens from any of the three domains are accepted
+claims = await api_client.verify_access_token(access_token)
+```
+
+#### Dynamic Resolver
+
+For runtime domain resolution based on request context:
+
+```python
+from auth0_api_python import ApiClient, ApiClientOptions, DomainsResolverContext
+
+def resolve_domains(context: DomainsResolverContext) -> list[str]:
+    # Determine allowed domains based on the request
+    return ["tenant.auth0.com", "auth.example.com"]
+
+api_client = ApiClient(ApiClientOptions(
+    domains=resolve_domains,
+    audience="https://api.example.com"
+))
+```
+
+For hybrid mode (migration scenarios), resolver patterns, error handling, and caching configuration, see the full guides:
+
+- **[Multi-Custom Domain Guide](docs/MultipleCustomDomain.md)** - Configuration modes, resolver patterns, migration, error handling
+- **[Caching Guide](docs/Caching.md)** - Cache tuning, custom adapters (Redis, Memcached)
+
 ## Feedback
 
 ### Contributing
@@ -311,4 +439,4 @@ Please do not report security vulnerabilities on the public GitHub issue tracker
 </p>
 <p align="center">
   This project is licensed under the MIT license. See the <a href="https://github.com/auth0/auth0-api-python/LICENSE"> LICENSE</a> file for more info.
-</p>
+</p>

{auth0_api_python-1.0.0b7 → auth0_api_python-1.0.0b9}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "auth0-api-python"
-version = "1.0.0.b7"
+version = "1.0.0b9"
 description = "SDK for verifying access tokens and securing APIs with Auth0, using Authlib."
 authors = ["Auth0 <support@auth0.com>"]
 license = "MIT"

auth0_api_python-1.0.0b9/src/auth0_api_python/__init__.py

@@ -0,0 +1,38 @@
+"""
+auth0-api-python
+
+A lightweight Python SDK for verifying Auth0-issued access tokens
+in server-side APIs, using Authlib for OIDC discovery and JWKS fetching.
+"""
+
+from .act import get_current_actor, get_delegation_chain
+from .api_client import ApiClient
+from .cache import CacheAdapter, InMemoryCache
+from .config import ApiClientOptions
+from .errors import (
+    ApiError,
+    ConfigurationError,
+    DomainsResolverError,
+    GetTokenByExchangeProfileError,
+)
+from .types import (
+    DomainsResolver,
+    DomainsResolverContext,
+    OnBehalfOfTokenResult,
+)
+
+__all__ = [
+    "ApiClient",
+    "ApiClientOptions",
+    "ApiError",
+    "CacheAdapter",
+    "ConfigurationError",
+    "DomainsResolver",
+    "DomainsResolverContext",
+    "DomainsResolverError",
+    "GetTokenByExchangeProfileError",
+    "get_current_actor",
+    "get_delegation_chain",
+    "InMemoryCache",
+    "OnBehalfOfTokenResult",
+]

auth0_api_python-1.0.0b9/src/auth0_api_python/act.py

@@ -0,0 +1,64 @@
+"""
+Helpers for working with the `act` claim on verified access token claims.
+"""
+
+from collections.abc import Mapping
+from typing import Any, Optional
+
+from .errors import VerifyAccessTokenError
+
+INVALID_ACT_CLAIM_MESSAGE = "Invalid act claim"
+
+
+def get_current_actor(claims: Mapping[str, Any]) -> Optional[str]:
+    """
+    Return the current actor from the outermost `act.sub`, if present.
+
+    Only the outermost `act.sub` should be used for authorization decisions.
+    Nested `act` values represent prior actors and are informational.
+    """
+    if not isinstance(claims, Mapping):
+        raise VerifyAccessTokenError(INVALID_ACT_CLAIM_MESSAGE)
+
+    act_claim = claims.get("act")
+    if act_claim is None:
+        return None
+
+    if not isinstance(act_claim, Mapping):
+        raise VerifyAccessTokenError(INVALID_ACT_CLAIM_MESSAGE)
+
+    sub = act_claim.get("sub")
+    if not isinstance(sub, str) or not sub.strip():
+        raise VerifyAccessTokenError(INVALID_ACT_CLAIM_MESSAGE)
+
+    return sub
+
+
+def get_delegation_chain(claims: Mapping[str, Any]) -> list[str]:
+    """
+    Return the delegation chain from newest actor to oldest actor.
+
+    The first entry is the current actor (outermost `act.sub`). Later entries are
+    prior actors from nested `act` values and are typically most useful for audit
+    and attribution.
+    """
+    if not isinstance(claims, Mapping):
+        raise VerifyAccessTokenError(INVALID_ACT_CLAIM_MESSAGE)
+
+    current = claims.get("act")
+    if current is None:
+        return []
+
+    chain: list[str] = []
+    while current is not None:
+        if not isinstance(current, Mapping):
+            raise VerifyAccessTokenError(INVALID_ACT_CLAIM_MESSAGE)
+
+        sub = current.get("sub")
+        if not isinstance(sub, str) or not sub.strip():
+            raise VerifyAccessTokenError(INVALID_ACT_CLAIM_MESSAGE)
+
+        chain.append(sub)
+        current = current.get("act")
+
+    return chain