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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: auth0-api-python
-Version: 1.0.0b8
+Version: 1.0.0b9
 Summary: SDK for verifying access tokens and securing APIs with Auth0, using Authlib.
 License: MIT
 License-File: LICENSE
@@ -236,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`:
@@ -378,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.0b8 → auth0_api_python-1.0.0b9}/README.md

@@ -212,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`:
@@ -353,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.0b8 → auth0_api_python-1.0.0b9}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "auth0-api-python"
-version = "1.0.0b8"
+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.0b8 → auth0_api_python-1.0.0b9}/src/auth0_api_python/__init__.py

@@ -5,6 +5,7 @@ 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
@@ -14,7 +15,11 @@ from .errors import (
     DomainsResolverError,
     GetTokenByExchangeProfileError,
 )
-from .types import DomainsResolver, DomainsResolverContext
+from .types import (
+    DomainsResolver,
+    DomainsResolverContext,
+    OnBehalfOfTokenResult,
+)
 
 __all__ = [
     "ApiClient",
@@ -26,5 +31,8 @@ __all__ = [
     "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

{auth0_api_python-1.0.0b8 → auth0_api_python-1.0.0b9}/src/auth0_api_python/api_client.py

@@ -21,6 +21,7 @@ from .errors import (
     MissingRequiredArgumentError,
     VerifyAccessTokenError,
 )
+from .types import OnBehalfOfTokenResult
 from .utils import (
     calculate_jwk_thumbprint,
     fetch_jwks,
@@ -34,6 +35,7 @@ from .utils import (
 
 # Token Exchange constants
 TOKEN_EXCHANGE_GRANT_TYPE = "urn:ietf:params:oauth:grant-type:token-exchange"  # noqa: S105
+OBO_ACCESS_TOKEN_TYPE = "urn:ietf:params:oauth:token-type:access_token"  # noqa: S105
 MAX_ARRAY_VALUES_PER_KEY = 20  # DoS protection for extra parameter arrays
 
 # OAuth parameter denylist - parameters that cannot be overridden via extras
@@ -232,7 +234,7 @@ class ApiClient:
             http_url: The HTTP URL (required for DPoP, also used for MCD resolver context)
 
         Returns:
-            The decoded access token claims
+            The decoded access token claims, including `act` when present.
 
         Raises:
             MissingRequiredArgumentError: If required args are missing
@@ -412,7 +414,7 @@ class ApiClient:
             required_claims: Optional list of additional claim names that must be present
 
         Returns:
-            The decoded token claims if valid.
+            The decoded token claims if valid, including `act` when present.
 
         Raises:
             MissingRequiredArgumentError: If no token is provided.
@@ -794,7 +796,7 @@ class ApiClient:
             Dictionary containing:
             - access_token (str): The Auth0 access token
             - expires_in (int): Token lifetime in seconds
-            - expires_at (int): Unix timestamp when token expires
+            - expires_at (int): Absolute expiration time as a Unix timestamp in seconds, calculated by the SDK from expires_in
             - id_token (str, optional): OpenID Connect ID token
             - refresh_token (str, optional): Refresh token
             - scope (str, optional): Granted scopes
@@ -962,6 +964,64 @@ class ApiClient:
                 exc
             )
 
+    async def get_token_on_behalf_of(
+        self,
+        access_token: str,
+        audience: str,
+        scope: Optional[str] = None,
+    ) -> OnBehalfOfTokenResult:
+        """
+        Exchange an Auth0 access token for another Auth0 access token targeting a downstream API
+        while acting on behalf of the same end user (OBO).
+
+        This is a convenience wrapper around get_token_by_exchange_profile() that fixes the
+        RFC 8693 token types for Auth0 access-token-to-access-token exchange.
+
+        Args:
+            access_token: The Auth0 access token to exchange
+            audience: Target API identifier for the exchanged access token
+            scope: Optional space-separated OAuth 2.0 scopes to request
+
+        Returns:
+            Dictionary containing:
+            - access_token (str): The exchanged Auth0 access token
+            - expires_in (int): Token lifetime in seconds
+            - expires_at (int): Absolute expiration time as a Unix timestamp in seconds, calculated by the SDK from expires_in
+            - scope (str, optional): Granted scopes
+            - token_type (str, optional): Token type (typically "Bearer")
+            - issued_token_type (str, optional): RFC 8693 issued token type identifier
+
+        Raises:
+            MissingRequiredArgumentError: If required parameters are missing
+            GetTokenByExchangeProfileError: If client credentials are not configured or validation fails
+            ApiError: If the token endpoint returns an error
+        """
+        if not audience:
+            raise MissingRequiredArgumentError("audience")
+
+        result = await self.get_token_by_exchange_profile(
+            subject_token=access_token,
+            subject_token_type=OBO_ACCESS_TOKEN_TYPE,
+            audience=audience,
+            scope=scope,
+            requested_token_type=OBO_ACCESS_TOKEN_TYPE,
+        )
+
+        obo_result: OnBehalfOfTokenResult = {
+            "access_token": result["access_token"],
+            "expires_in": result["expires_in"],
+            "expires_at": result["expires_at"],
+        }
+
+        if "scope" in result:
+            obo_result["scope"] = result["scope"]
+        if "token_type" in result:
+            obo_result["token_type"] = result["token_type"]
+        if "issued_token_type" in result:
+            obo_result["issued_token_type"] = result["issued_token_type"]
+
+        return obo_result
+
     # ===== Private Methods =====
 
     def _apply_extra(

{auth0_api_python-1.0.0b8 → auth0_api_python-1.0.0b9}/src/auth0_api_python/config.py

@@ -27,8 +27,10 @@ class ApiClientOptions:
         dpop_required: Whether DPoP is required (default: False, allows both Bearer and DPoP).
         dpop_iat_leeway: Leeway in seconds for DPoP proof iat claim (default: 30).
         dpop_iat_offset: Maximum age in seconds for DPoP proof iat claim (default: 300).
-        client_id: Required for get_access_token_for_connection and get_token_by_exchange_profile.
-        client_secret: Required for get_access_token_for_connection and get_token_by_exchange_profile.
+        client_id: Required for get_access_token_for_connection, get_token_by_exchange_profile,
+                   and get_token_on_behalf_of.
+        client_secret: Required for get_access_token_for_connection, get_token_by_exchange_profile,
+                       and get_token_on_behalf_of.
         timeout: HTTP timeout in seconds for token endpoint requests (default: 10.0).
     """
     def __init__(

{auth0_api_python-1.0.0b8 → auth0_api_python-1.0.0b9}/src/auth0_api_python/types.py

@@ -6,6 +6,19 @@ from collections.abc import Awaitable, Callable
 from typing import Optional, TypedDict, Union
 
 
+class ActClaim(TypedDict, total=False):
+    """
+    Actor claim carried by access tokens issued through delegation.
+
+    Attributes:
+        sub: The current actor for this step of the delegation chain.
+        act: The prior actor in the delegation chain, if present.
+    """
+
+    sub: str
+    act: "ActClaim"
+
+
 class DomainsResolverContext(TypedDict, total=False):
     """
     Context passed to domains resolver functions.
@@ -19,6 +32,27 @@ class DomainsResolverContext(TypedDict, total=False):
     request_headers: Optional[dict]
     unverified_iss: str
 
+
+class OnBehalfOfTokenResult(TypedDict, total=False):
+    """
+    Result returned from an On Behalf Of token exchange.
+
+    Attributes:
+        access_token: The access token issued for the downstream API.
+        expires_in: Token lifetime in seconds.
+        expires_at: Absolute expiration time as a Unix timestamp in seconds, calculated by the SDK from expires_in.
+        scope: Granted scopes, if returned by Auth0.
+        token_type: Token type, if returned by Auth0.
+        issued_token_type: RFC 8693 issued token type, if returned by Auth0.
+    """
+
+    access_token: str
+    expires_in: int
+    expires_at: int
+    scope: str
+    token_type: str
+    issued_token_type: str
+
 DomainsResolver = Callable[
     [DomainsResolverContext], Union[list[str], Awaitable[list[str]]]
 ]