auth0-server-python 1.0.0b5__tar.gz → 1.0.0b6__tar.gz

{auth0_server_python-1.0.0b5 → auth0_server_python-1.0.0b6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: auth0-server-python
-Version: 1.0.0b5
+Version: 1.0.0b6
 Summary: Auth0 server-side Python SDK
 License: MIT
 License-File: LICENSE
@@ -25,7 +25,10 @@ Description-Content-Type: text/markdown
 
 The Auth0 Server Python SDK is a library for implementing user authentication in Python applications.
 
-![PyPI](https://img.shields.io/pypi/v/auth0-server-python) ![Downloads](https://img.shields.io/pypi/dw/auth0-server-python) [![License](https://img.shields.io/:license-MIT-blue.svg?style=flat)](https://opensource.org/licenses/MIT)
+![PyPI](https://img.shields.io/pypi/v/auth0-server-python)
+![Downloads](https://img.shields.io/pypi/dw/auth0-server-python)
+[![License](https://img.shields.io/:license-MIT-blue.svg?style=flat)](https://opensource.org/licenses/MIT)
+[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/auth0/auth0-server-python)
 
 📚 [Documentation](#documentation) - 🚀 [Getting Started](#getting-started) - 💬 [Feedback](#feedback)
 
@@ -159,3 +162,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-server-python/blob/main/LICENSE"> LICENSE</a> file for more info.
 </p>
+

{auth0_server_python-1.0.0b5 → auth0_server_python-1.0.0b6}/README.md

@@ -1,6 +1,9 @@
 The Auth0 Server Python SDK is a library for implementing user authentication in Python applications.
 
-![PyPI](https://img.shields.io/pypi/v/auth0-server-python) ![Downloads](https://img.shields.io/pypi/dw/auth0-server-python) [![License](https://img.shields.io/:license-MIT-blue.svg?style=flat)](https://opensource.org/licenses/MIT)
+![PyPI](https://img.shields.io/pypi/v/auth0-server-python)
+![Downloads](https://img.shields.io/pypi/dw/auth0-server-python)
+[![License](https://img.shields.io/:license-MIT-blue.svg?style=flat)](https://opensource.org/licenses/MIT)
+[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/auth0/auth0-server-python)
 
 📚 [Documentation](#documentation) - 🚀 [Getting Started](#getting-started) - 💬 [Feedback](#feedback)
 
@@ -133,4 +136,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-server-python/blob/main/LICENSE"> LICENSE</a> file for more info.
-</p>
+</p>

{auth0_server_python-1.0.0b5 → auth0_server_python-1.0.0b6}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "auth0-server-python"
-version = "1.0.0.b5"
+version = "1.0.0.b6"
 description = "Auth0 server-side Python SDK"
 readme = "README.md"
 authors = ["Auth0 <support@okta.com>"]

auth0_server_python-1.0.0b6/src/auth0_server_python/auth_schemes/__init__.py

@@ -0,0 +1,3 @@
+from .bearer_auth import BearerAuth
+
+__all__ = ["BearerAuth"]

auth0_server_python-1.0.0b6/src/auth0_server_python/auth_schemes/bearer_auth.py

@@ -0,0 +1,10 @@
+import httpx
+
+
+class BearerAuth(httpx.Auth):
+    def __init__(self, token: str):
+        self.token = token
+
+    def auth_flow(self, request):
+        request.headers['Authorization'] = f"Bearer {self.token}"
+        yield request

auth0_server_python-1.0.0b6/src/auth0_server_python/auth_server/__init__.py

@@ -0,0 +1,4 @@
+from .my_account_client import MyAccountClient
+from .server_client import ServerClient
+
+__all__ = ["ServerClient", "MyAccountClient"]

auth0_server_python-1.0.0b6/src/auth0_server_python/auth_server/my_account_client.py

@@ -0,0 +1,94 @@
+
+import httpx
+from auth0_server_python.auth_schemes.bearer_auth import BearerAuth
+from auth0_server_python.auth_types import (
+    CompleteConnectAccountRequest,
+    CompleteConnectAccountResponse,
+    ConnectAccountRequest,
+    ConnectAccountResponse,
+)
+from auth0_server_python.error import (
+    ApiError,
+    MyAccountApiError,
+)
+
+
+class MyAccountClient:
+    def __init__(self, domain: str):
+        self._domain = domain
+
+    @property
+    def audience(self):
+        return f"https://{self._domain}/me/"
+
+    async def connect_account(
+        self,
+        access_token: str,
+        request: ConnectAccountRequest
+    ) -> ConnectAccountResponse:
+        try:
+            async with httpx.AsyncClient() as client:
+                response = await client.post(
+                    url=f"{self.audience}v1/connected-accounts/connect",
+                    json=request.model_dump(exclude_none=True),
+                    auth=BearerAuth(access_token)
+                )
+
+                if response.status_code != 201:
+                    error_data = response.json()
+                    raise MyAccountApiError(
+                        title=error_data.get("title", None),
+                        type=error_data.get("type", None),
+                        detail=error_data.get("detail", None),
+                        status=error_data.get("status", None),
+                        validation_errors=error_data.get("validation_errors", None)
+                    )
+
+                data = response.json()
+
+                return ConnectAccountResponse.model_validate(data)
+
+        except Exception as e:
+            if isinstance(e, MyAccountApiError):
+                raise
+            raise ApiError(
+                "connect_account_error",
+                f"Connected Accounts connect request failed: {str(e) or 'Unknown error'}",
+                e
+            )
+
+    async def complete_connect_account(
+        self,
+        access_token: str,
+        request: CompleteConnectAccountRequest
+    ) -> CompleteConnectAccountResponse:
+        try:
+            async with httpx.AsyncClient() as client:
+                response = await client.post(
+                    url=f"{self.audience}v1/connected-accounts/complete",
+                    json=request.model_dump(exclude_none=True),
+                    auth=BearerAuth(access_token)
+                )
+
+                if response.status_code != 201:
+                    error_data = response.json()
+                    raise MyAccountApiError(
+                        title=error_data.get("title", None),
+                        type=error_data.get("type", None),
+                        detail=error_data.get("detail", None),
+                        status=error_data.get("status", None),
+                        validation_errors=error_data.get("validation_errors", None)
+                    )
+
+                data = response.json()
+
+                return CompleteConnectAccountResponse.model_validate(data)
+
+        except Exception as e:
+            if isinstance(e, MyAccountApiError):
+                raise
+            raise ApiError(
+                "connect_account_error",
+                f"Connected Accounts complete request failed: {str(e) or 'Unknown error'}",
+                e
+            )

{auth0_server_python-1.0.0b5 → auth0_server_python-1.0.0b6}/src/auth0_server_python/auth_server/server_client.py

@@ -7,11 +7,16 @@ import asyncio
 import json
 import time
 from typing import Any, Generic, Optional, TypeVar
-from urllib.parse import parse_qs, urlparse
+from urllib.parse import parse_qs, urlencode, urlparse, urlunparse
 
 import httpx
 import jwt
+from auth0_server_python.auth_server.my_account_client import MyAccountClient
 from auth0_server_python.auth_types import (
+    CompleteConnectAccountRequest,
+    CompleteConnectAccountResponse,
+    ConnectAccountOptions,
+    ConnectAccountRequest,
     LogoutOptions,
     LogoutTokenClaims,
     StartInteractiveLoginOptions,
@@ -40,7 +45,7 @@ from pydantic import ValidationError
 # Generic type for store options
 TStoreOptions = TypeVar('TStoreOptions')
 INTERNAL_AUTHORIZE_PARAMS = ["client_id", "redirect_uri", "response_type",
-                             "code_challenge", "code_challenge_method", "state", "nonce"]
+                             "code_challenge", "code_challenge_method", "state", "nonce", "scope"]
 
 
 class ServerClient(Generic[TStoreOptions]):
@@ -48,6 +53,7 @@ class ServerClient(Generic[TStoreOptions]):
     Main client for Auth0 server SDK. Handles authentication flows, session management,
     and token operations using Authlib for OIDC functionality.
     """
+    DEFAULT_AUDIENCE_STATE_KEY = "default"
 
     def __init__(
         self,
@@ -101,6 +107,8 @@ class ServerClient(Generic[TStoreOptions]):
             client_secret=client_secret,
         )
 
+        self._my_account_client = MyAccountClient(domain=domain)
+
     async def _fetch_oidc_metadata(self, domain: str) -> dict:
         metadata_url = f"https://{domain}/.well-known/openid-configuration"
         async with httpx.AsyncClient() as client:
@@ -152,10 +160,17 @@ class ServerClient(Generic[TStoreOptions]):
         state = PKCE.generate_random_string(32)
         auth_params["state"] = state
 
+                #merge any requested scope with defaults
+        requested_scope = options.authorization_params.get("scope", None) if options.authorization_params else None
+        audience = auth_params.get("audience", None)
+        merged_scope = self._merge_scope_with_defaults(requested_scope, audience)
+        auth_params["scope"] = merged_scope
+
         # Build the transaction data to store
         transaction_data = TransactionData(
             code_verifier=code_verifier,
-            app_state=options.app_state
+            app_state=options.app_state,
+            audience=audience,
         )
 
         # Store the transaction data
@@ -290,7 +305,7 @@ class ServerClient(Generic[TStoreOptions]):
 
         # Build a token set using the token response data
         token_set = TokenSet(
-            audience=token_response.get("audience", "default"),
+            audience=transaction_data.audience or self.DEFAULT_AUDIENCE_STATE_KEY,
             access_token=token_response.get("access_token", ""),
             scope=token_response.get("scope", ""),
             expires_at=int(time.time()) +
@@ -509,7 +524,7 @@ class ServerClient(Generic[TStoreOptions]):
         existing_state_data = await self._state_store.get(self._state_identifier, store_options)
 
         audience = self._default_authorization_params.get(
-            "audience", "default")
+            "audience", self.DEFAULT_AUDIENCE_STATE_KEY)
 
         state_data = State.update_state_data(
             audience,
@@ -562,7 +577,12 @@ class ServerClient(Generic[TStoreOptions]):
             return session_data
         return None
 
-    async def get_access_token(self, store_options: Optional[dict[str, Any]] = None) -> str:
+    async def get_access_token(
+        self,
+        store_options: Optional[dict[str, Any]] = None,
+        audience: Optional[str] = None,
+        scope: Optional[str] = None,
+    ) -> str:
         """
         Retrieves the access token from the store, or calls Auth0 when the access token
         is expired and a refresh token is available in the store.
@@ -579,10 +599,13 @@ class ServerClient(Generic[TStoreOptions]):
         """
         state_data = await self._state_store.get(self._state_identifier, store_options)
 
-        # Get audience and scope from options or use defaults
         auth_params = self._default_authorization_params or {}
-        audience = auth_params.get("audience", "default")
-        scope = auth_params.get("scope")
+
+        # Get audience passed in on options or use defaults
+        if not audience:
+            audience = auth_params.get("audience", None)
+
+        merged_scope = self._merge_scope_with_defaults(scope, audience)
 
         if state_data and hasattr(state_data, "dict") and callable(state_data.dict):
             state_data_dict = state_data.dict()
@@ -592,10 +615,7 @@ class ServerClient(Generic[TStoreOptions]):
         # Find matching token set
         token_set = None
         if state_data_dict and "token_sets" in state_data_dict:
-            for ts in state_data_dict["token_sets"]:
-                if ts.get("audience") == audience and (not scope or ts.get("scope") == scope):
-                    token_set = ts
-                    break
+            token_set = self._find_matching_token_set(state_data_dict["token_sets"], audience, merged_scope)
 
         # If token is valid, return it
         if token_set and token_set.get("expires_at", 0) > time.time():
@@ -610,9 +630,14 @@ class ServerClient(Generic[TStoreOptions]):
 
         # Get new token with refresh token
         try:
-            token_endpoint_response = await self.get_token_by_refresh_token({
-                "refresh_token": state_data_dict["refresh_token"]
-            })
+            get_refresh_token_options = {"refresh_token": state_data_dict["refresh_token"]}
+            if audience:
+                get_refresh_token_options["audience"] = audience
+
+            if merged_scope:
+                get_refresh_token_options["scope"] = merged_scope
+
+            token_endpoint_response = await self.get_token_by_refresh_token(get_refresh_token_options)
 
             # Update state data with new token
             existing_state_data = await self._state_store.get(self._state_identifier, store_options)
@@ -631,6 +656,51 @@ class ServerClient(Generic[TStoreOptions]):
                 f"Failed to get token with refresh token: {str(e)}"
             )
 
+    def _merge_scope_with_defaults(
+        self,
+        request_scope: Optional[str],
+        audience: Optional[str]
+    ) -> Optional[str]:
+        audience = audience or self.DEFAULT_AUDIENCE_STATE_KEY
+        default_scopes = ""
+        if self._default_authorization_params and "scope" in self._default_authorization_params:
+            auth_param_scope = self._default_authorization_params.get("scope")
+            # For backwards compatibility, allow scope to be a single string
+            # or dictionary by audience for MRRT
+            if isinstance(auth_param_scope, dict) and audience in auth_param_scope:
+                default_scopes = auth_param_scope[audience]
+            elif isinstance(auth_param_scope, str):
+                default_scopes = auth_param_scope
+
+        default_scopes_list = default_scopes.split()
+        request_scopes_list = (request_scope or "").split()
+
+        merged_scopes = list(dict.fromkeys(default_scopes_list + request_scopes_list))
+        return " ".join(merged_scopes) if merged_scopes else None
+
+
+    def _find_matching_token_set(
+        self,
+        token_sets: list[dict[str, Any]],
+        audience: Optional[str],
+        scope: Optional[str]
+    ) -> Optional[dict[str, Any]]:
+        audience = audience or self.DEFAULT_AUDIENCE_STATE_KEY
+        requested_scopes = set(scope.split()) if scope else set()
+        matches: list[tuple[int, dict]] = []
+        for token_set in token_sets:
+            token_set_audience = token_set.get("audience")
+            token_set_scopes = set(token_set.get("scope", "").split())
+            if token_set_audience == audience and token_set_scopes == requested_scopes:
+                # short-circuit if exact match
+                return token_set
+            if token_set_audience == audience and token_set_scopes.issuperset(requested_scopes):
+                # consider stored tokens with more scopes than requested by number of scopes
+                matches.append((len(token_set_scopes), token_set))
+
+        # Return the token set with the smallest superset of scopes that matches the requested audience and scopes
+        return min(matches, key=lambda t: t[0])[1] if matches else None
+
     async def get_access_token_for_connection(
         self,
         options: dict[str, Any],
@@ -1143,9 +1213,18 @@ class ServerClient(Generic[TStoreOptions]):
                 "client_id": self._client_id,
             }
 
-            # Add scope if present in the original authorization params
-            if "scope" in self._default_authorization_params:
-                token_params["scope"] = self._default_authorization_params["scope"]
+            audience = options.get("audience")
+            if audience:
+                token_params["audience"] = audience
+
+            # Merge scope if present in options with any in the original authorization params
+            merged_scope = self._merge_scope_with_defaults(
+                request_scope=options.get("scope"),
+                audience=audience
+            )
+
+            if merged_scope:
+                token_params["scope"] = merged_scope
 
             # Exchange the refresh token for an access token
             async with httpx.AsyncClient() as client:
@@ -1260,3 +1339,135 @@ class ServerClient(Generic[TStoreOptions]):
                 "There was an error while trying to retrieve an access token for a connection.",
                 e
             )
+
+    async def start_connect_account(
+        self,
+        options: ConnectAccountOptions,
+        store_options: dict = None
+    ) -> str:
+        """
+        Initiates the connect account flow for linking a third-party account to the user's profile.
+
+        This method generates PKCE parameters, creates a transaction and calls the My Account API
+        to create a connect account request, returning /connect url containing a ticket.
+
+        Args:
+            options: Options for retrieving an access token for a connection.
+            store_options: Optional options used to pass to the Transaction and State Store.
+
+        Returns:
+            The a connect URL containing a ticket to redirect the user to.
+        """
+        # Use the default redirect_uri if none is specified
+        redirect_uri = options.redirect_uri or self._redirect_uri
+        # Ensure we have a redirect_uri
+        if not redirect_uri:
+            raise MissingRequiredArgumentError("redirect_uri")
+
+        # Generate PKCE code verifier and challenge
+        code_verifier = PKCE.generate_code_verifier()
+        code_challenge = PKCE.generate_code_challenge(code_verifier)
+
+        state= PKCE.generate_random_string(32)
+
+        connect_request = ConnectAccountRequest(
+            connection=options.connection,
+            scopes=options.scopes,
+            redirect_uri = redirect_uri,
+            code_challenge=code_challenge,
+            code_challenge_method="S256",
+            state=state,
+            authorization_params=options.authorization_params
+        )
+
+        access_token = await self.get_access_token(
+            audience=self._my_account_client.audience,
+            scope="create:me:connected_accounts",
+            store_options=store_options
+        )
+        connect_response = await self._my_account_client.connect_account(
+            access_token=access_token,
+            request=connect_request
+        )
+
+        # Build the transaction data to store
+        transaction_data = TransactionData(
+            code_verifier=code_verifier,
+            app_state=options.app_state,
+            auth_session=connect_response.auth_session,
+            redirect_uri=redirect_uri
+        )
+
+        # Store the transaction data
+        await self._transaction_store.set(
+            f"{self._transaction_identifier}:{state}",
+            transaction_data,
+            options=store_options
+        )
+
+        parsedUrl = urlparse(connect_response.connect_uri)
+        query = urlencode({"ticket": connect_response.connect_params.ticket})
+        return urlunparse((parsedUrl.scheme, parsedUrl.netloc, parsedUrl.path, parsedUrl.params, query, parsedUrl.fragment))
+
+    async def complete_connect_account(
+        self,
+        url: str,
+        store_options: dict = None
+    ) -> CompleteConnectAccountResponse:
+        """
+        Handles the redirect callback to complete the connect account flow for linking a third-party
+        account to the user's profile.
+
+        This works similar to the redirect from the login flow except it verifies the `connect_code`
+        with the My Account API rather than the `code` with the Authorization Server.
+
+        Args:
+            url: The full callback URL including query parameters
+            store_options: Optional options used to pass to the Transaction and State Store.
+
+        Returns:
+            A response from the connect account flow.
+        """
+        # Parse the URL to get query parameters
+        parsed_url = urlparse(url)
+        query_params = parse_qs(parsed_url.query)
+
+        # Get state parameter from the URL
+        state = query_params.get("state", [""])[0]
+        if not state:
+            raise MissingRequiredArgumentError("state")
+
+        # Get the authorization code from the URL
+        connect_code = query_params.get("connect_code", [""])[0]
+        if not connect_code:
+            raise MissingRequiredArgumentError("connect_code")
+
+        # Retrieve the transaction data using the state
+        transaction_identifier = f"{self._transaction_identifier}:{state}"
+        transaction_data = await self._transaction_store.get(transaction_identifier, options=store_options)
+
+        if not transaction_data:
+            raise MissingTransactionError()
+
+        access_token = await self.get_access_token(
+            audience=self._my_account_client.audience,
+            scope="create:me:connected_accounts",
+            store_options=store_options
+        )
+
+        request = CompleteConnectAccountRequest(
+            auth_session=transaction_data.auth_session,
+            connect_code=connect_code,
+            redirect_uri=transaction_data.redirect_uri,
+            code_verifier=transaction_data.code_verifier
+        )
+        try:
+            response = await self._my_account_client.complete_connect_account(
+                access_token=access_token, request=request)
+            if transaction_data.app_state is not None:
+                response.app_state = transaction_data.app_state
+        finally:
+            # Clean up transaction data
+            await self._transaction_store.delete(transaction_identifier, options=store_options)
+
+        return response

{auth0_server_python-1.0.0b5 → auth0_server_python-1.0.0b6}/src/auth0_server_python/auth_types/__init__.py

@@ -87,6 +87,8 @@ class TransactionData(BaseModel):
     audience: Optional[str] = None
     code_verifier: str
     app_state: Optional[Any] = None
+    auth_session: Optional[str] = None
+    redirect_uri: Optional[str] = None
 
     class Config:
         extra = "allow"  # Allow additional fields not defined in the model
@@ -210,3 +212,43 @@ class StartLinkUserOptions(BaseModel):
     connection_scope: Optional[str] = None
     authorization_params: Optional[dict[str, Any]] = None
     app_state: Optional[Any] = None
+
+class ConnectParams(BaseModel):
+    ticket: str
+
+class ConnectAccountOptions(BaseModel):
+    connection: str
+    redirect_uri: Optional[str] = None
+    scopes: Optional[list[str]] = None
+    app_state: Optional[Any] = None
+    authorization_params: Optional[dict[str, Any]] = None
+
+class ConnectAccountRequest(BaseModel):
+    connection: str
+    scopes: Optional[list[str]] = None
+    redirect_uri: Optional[str] = None
+    state: Optional[str] = None
+    code_challenge: Optional[str] = None
+    code_challenge_method: Optional[str] = 'S256'
+    authorization_params: Optional[dict[str, Any]] = None
+
+class ConnectAccountResponse(BaseModel):
+    auth_session: str
+    connect_uri: str
+    connect_params: ConnectParams
+    expires_in: int
+
+class CompleteConnectAccountRequest(BaseModel):
+    auth_session: str
+    connect_code: str
+    redirect_uri: str
+    code_verifier: Optional[str] = None
+
+class CompleteConnectAccountResponse(BaseModel):
+    id: str
+    connection: str
+    access_type: str
+    scopes: list[str]
+    created_at: str
+    expires_at: Optional[str] = None
+    app_state: Optional[Any] = None

{auth0_server_python-1.0.0b5 → auth0_server_python-1.0.0b6}/src/auth0_server_python/error/__init__.py

@@ -56,6 +56,26 @@ class PollingApiError(ApiError):
         super().__init__(code, message, cause)
         self.interval = interval
 
+class MyAccountApiError(Auth0Error):
+    """
+    Error raised when an API request to My Account API fails.
+    Contains details about the original error from Auth0.
+    """
+
+    def __init__(
+            self,
+            title: Optional[str],
+            type: Optional[str],
+            detail: Optional[str],
+            status: Optional[int],
+            validation_errors: Optional[list[dict[str, str]]] = None
+        ):
+        super().__init__(detail)
+        self.title = title
+        self.type = type
+        self.detail = detail
+        self.status = status
+        self.validation_errors = validation_errors
 
 class AccessTokenError(Auth0Error):
     """Error raised when there's an issue with access tokens."""
@@ -124,6 +144,7 @@ class AccessTokenErrorCode:
     FAILED_TO_REQUEST_TOKEN = "failed_to_request_token"
     REFRESH_TOKEN_ERROR = "refresh_token_error"
     AUTH_REQ_ID_ERROR = "auth_req_id_error"
+    INCORRECT_AUDIENCE = "incorrect_audience"
 
 
 class AccessTokenForConnectionErrorCode: