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

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

@@ -1,8 +1,9 @@
-Metadata-Version: 2.3
+Metadata-Version: 2.4
 Name: auth0-server-python
-Version: 1.0.0b4
+Version: 1.0.0b5
 Summary: Auth0 server-side Python SDK
 License: MIT
+License-File: LICENSE
 Author: Auth0
 Author-email: support@okta.com
 Requires-Python: >=3.9
@@ -13,6 +14,7 @@ Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Requires-Dist: authlib (>=1.2,<2.0)
 Requires-Dist: cryptography (>=43.0.1)
 Requires-Dist: httpx (>=0.28.1,<0.29.0)
@@ -29,7 +31,7 @@ The Auth0 Server Python SDK is a library for implementing user authentication in
 
 ## Documentation
 
-- [Examples](https://github.com/auth0/auth0-server-python/blob/main/packages/auth0_server_python/EXAMPLES.md) - examples for your different use cases.
+- [Examples](https://github.com/auth0/auth0-server-python/blob/main/examples) - examples for your different use cases.
 - [Docs Site](https://auth0.com/docs) - explore our docs site and learn more about Auth0.
 
 ## Getting Started
@@ -132,7 +134,7 @@ We appreciate feedback and contribution to this repo! Before you get started, pl
 
 - [Auth0's general contribution guidelines](https://github.com/auth0/open-source-template/blob/master/GENERAL-CONTRIBUTING.md)
 - [Auth0's code of conduct guidelines](https://github.com/auth0/open-source-template/blob/master/CODE-OF-CONDUCT.md)
-- [This repo's contribution guide](./../../CONTRIBUTING.md)
+- [This repo's contribution guide](./CONTRIBUTING.md)
 
 ### Raise an issue
 
@@ -155,5 +157,5 @@ Please do not report security vulnerabilities on the public GitHub issue tracker
   Auth0 is an easy to implement, adaptable authentication and authorization platform. To learn more checkout <a href="https://auth0.com/why-auth0">Why Auth0?</a>
 </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/packages/auth0_server_python/LICENSE"> LICENSE</a> file for more info.
+  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.0b4 → auth0_server_python-1.0.0b5}/README.md

@@ -6,7 +6,7 @@ The Auth0 Server Python SDK is a library for implementing user authentication in
 
 ## Documentation
 
-- [Examples](https://github.com/auth0/auth0-server-python/blob/main/packages/auth0_server_python/EXAMPLES.md) - examples for your different use cases.
+- [Examples](https://github.com/auth0/auth0-server-python/blob/main/examples) - examples for your different use cases.
 - [Docs Site](https://auth0.com/docs) - explore our docs site and learn more about Auth0.
 
 ## Getting Started
@@ -109,7 +109,7 @@ We appreciate feedback and contribution to this repo! Before you get started, pl
 
 - [Auth0's general contribution guidelines](https://github.com/auth0/open-source-template/blob/master/GENERAL-CONTRIBUTING.md)
 - [Auth0's code of conduct guidelines](https://github.com/auth0/open-source-template/blob/master/CODE-OF-CONDUCT.md)
-- [This repo's contribution guide](./../../CONTRIBUTING.md)
+- [This repo's contribution guide](./CONTRIBUTING.md)
 
 ### Raise an issue
 
@@ -132,5 +132,5 @@ Please do not report security vulnerabilities on the public GitHub issue tracker
   Auth0 is an easy to implement, adaptable authentication and authorization platform. To learn more checkout <a href="https://auth0.com/why-auth0">Why Auth0?</a>
 </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/packages/auth0_server_python/LICENSE"> LICENSE</a> file for more info.
+  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.0b4 → auth0_server_python-1.0.0b5}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "auth0-server-python"
-version = "1.0.0.b4"
+version = "1.0.0.b5"
 description = "Auth0 server-side Python SDK"
 readme = "README.md"
 authors = ["Auth0 <support@okta.com>"]
@@ -25,9 +25,10 @@ pytest-cov = "^4.0"
 pytest-asyncio = "^0.20.3"
 pytest-mock = "^3.14.0"
 twine = "^6.1.0"
+ruff = "^0.1.0"
 
 [tool.pytest.ini_options]
-addopts = "--cov=auth_server --cov-report=term-missing:skip-covered --cov-report=xml"
+addopts = "--cov=auth0_server_python --cov-report=term-missing:skip-covered --cov-report=xml"
 
 [build-system]
 requires = ["poetry-core>=1.4.0"]

{auth0_server_python-1.0.0b4 → auth0_server_python-1.0.0b5}/src/auth0_server_python/auth_server/__init__.py

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

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

@@ -3,42 +3,39 @@ Main client for auth0-server-python SDK.
 Handles authentication flows, token management, and user sessions.
 """
 
-import time
-from typing import Dict, Any, Optional, List, Union, TypeVar, Generic, Callable
-from urllib.parse import urlparse, parse_qs
-import json
 import asyncio
-import jwt
+import json
+import time
+from typing import Any, Generic, Optional, TypeVar
+from urllib.parse import parse_qs, urlparse
 
-from authlib.integrations.httpx_client import AsyncOAuth2Client
-from authlib.integrations.base_client.errors import OAuthError
 import httpx
-
-from pydantic import BaseModel, ValidationError
-
-from auth0_server_python.error import (
-    MissingTransactionError,
-    ApiError,
-    MissingRequiredArgumentError,
-    BackchannelLogoutError,
-    AccessTokenError,
-    AccessTokenForConnectionError,
-    StartLinkUserError,
-    AccessTokenErrorCode,
-    AccessTokenForConnectionErrorCode
-
-)
+import jwt
 from auth0_server_python.auth_types import (
+    LogoutOptions,
+    LogoutTokenClaims,
+    StartInteractiveLoginOptions,
     StateData,
+    TokenSet,
     TransactionData,
     UserClaims,
-    TokenSet,
-    LogoutTokenClaims,
-    StartInteractiveLoginOptions,
-    LogoutOptions
 )
-from auth0_server_python.utils import PKCE, State, URL
-
+from auth0_server_python.error import (
+    AccessTokenError,
+    AccessTokenErrorCode,
+    AccessTokenForConnectionError,
+    AccessTokenForConnectionErrorCode,
+    ApiError,
+    BackchannelLogoutError,
+    MissingRequiredArgumentError,
+    MissingTransactionError,
+    PollingApiError,
+    StartLinkUserError,
+)
+from auth0_server_python.utils import PKCE, URL, State
+from authlib.integrations.base_client.errors import OAuthError
+from authlib.integrations.httpx_client import AsyncOAuth2Client
+from pydantic import ValidationError
 
 # Generic type for store options
 TStoreOptions = TypeVar('TStoreOptions')
@@ -63,7 +60,7 @@ class ServerClient(Generic[TStoreOptions]):
         state_store=None,
         transaction_identifier: str = "_a0_tx",
         state_identifier: str = "_a0_session",
-        authorization_params: Optional[Dict[str, Any]] = None,
+        authorization_params: Optional[dict[str, Any]] = None,
         pushed_authorization_requests: bool = False
     ):
         """
@@ -224,7 +221,7 @@ class ServerClient(Generic[TStoreOptions]):
         self,
         url: str,
         store_options: dict = None
-    ) -> Dict[str, Any]:
+    ) -> dict[str, Any]:
         """
         Completes the login process after user is redirected back.
 
@@ -337,7 +334,7 @@ class ServerClient(Generic[TStoreOptions]):
     async def start_link_user(
         self,
         options,
-        store_options: Optional[Dict[str, Any]] = None
+        store_options: Optional[dict[str, Any]] = None
     ):
         """
         Starts the user linking process, and returns a URL to redirect the user-agent to.
@@ -387,8 +384,8 @@ class ServerClient(Generic[TStoreOptions]):
     async def complete_link_user(
         self,
         url: str,
-        store_options: Optional[Dict[str, Any]] = None
-    ) -> Dict[str, Any]:
+        store_options: Optional[dict[str, Any]] = None
+    ) -> dict[str, Any]:
         """
         Completes the user linking process.
 
@@ -411,7 +408,7 @@ class ServerClient(Generic[TStoreOptions]):
     async def start_unlink_user(
         self,
         options,
-        store_options: Optional[Dict[str, Any]] = None
+        store_options: Optional[dict[str, Any]] = None
     ):
         """
         Starts the user unlinking process, and returns a URL to redirect the user-agent to.
@@ -460,8 +457,8 @@ class ServerClient(Generic[TStoreOptions]):
     async def complete_unlink_user(
         self,
         url: str,
-        store_options: Optional[Dict[str, Any]] = None
-    ) -> Dict[str, Any]:
+        store_options: Optional[dict[str, Any]] = None
+    ) -> dict[str, Any]:
         """
         Completes the user unlinking process.
 
@@ -483,9 +480,9 @@ class ServerClient(Generic[TStoreOptions]):
 
     async def login_backchannel(
         self,
-        options: Dict[str, Any],
-        store_options: Optional[Dict[str, Any]] = None
-    ) -> Dict[str, Any]:
+        options: dict[str, Any],
+        store_options: Optional[dict[str, Any]] = None
+    ) -> dict[str, Any]:
         """
         Logs in using Client-Initiated Backchannel Authentication.
 
@@ -527,7 +524,7 @@ class ServerClient(Generic[TStoreOptions]):
         }
         return result
 
-    async def get_user(self, store_options: Optional[Dict[str, Any]] = None) -> Optional[Dict[str, Any]]:
+    async def get_user(self, store_options: Optional[dict[str, Any]] = None) -> Optional[dict[str, Any]]:
         """
         Retrieves the user from the store, or None if no user found.
 
@@ -545,7 +542,7 @@ class ServerClient(Generic[TStoreOptions]):
             return state_data.get("user")
         return None
 
-    async def get_session(self, store_options: Optional[Dict[str, Any]] = None) -> Optional[Dict[str, Any]]:
+    async def get_session(self, store_options: Optional[dict[str, Any]] = None) -> Optional[dict[str, Any]]:
         """
         Retrieve the user session from the store, or None if no session found.
 
@@ -565,7 +562,7 @@ 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) -> 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.
@@ -636,8 +633,8 @@ class ServerClient(Generic[TStoreOptions]):
 
     async def get_access_token_for_connection(
         self,
-        options: Dict[str, Any],
-        store_options: Optional[Dict[str, Any]] = None
+        options: dict[str, Any],
+        store_options: Optional[dict[str, Any]] = None
     ) -> str:
         """
         Retrieves an access token for a connection.
@@ -702,7 +699,7 @@ class ServerClient(Generic[TStoreOptions]):
     async def logout(
         self,
         options: Optional[LogoutOptions] = None,
-        store_options: Optional[Dict[str, Any]] = None
+        store_options: Optional[dict[str, Any]] = None
     ) -> str:
         options = options or LogoutOptions()
 
@@ -718,7 +715,7 @@ class ServerClient(Generic[TStoreOptions]):
     async def handle_backchannel_logout(
         self,
         logout_token: str,
-        store_options: Optional[Dict[str, Any]] = None
+        store_options: Optional[dict[str, Any]] = None
     ) -> None:
         """
         Handles backchannel logout requests.
@@ -762,7 +759,7 @@ class ServerClient(Generic[TStoreOptions]):
         code_verifier: str,
         state: str,
         connection_scope: Optional[str] = None,
-        authorization_params: Optional[Dict[str, Any]] = None
+        authorization_params: Optional[dict[str, Any]] = None
     ) -> str:
         """Build a URL for linking user accounts"""
         # Generate code challenge from verifier
@@ -805,7 +802,7 @@ class ServerClient(Generic[TStoreOptions]):
         id_token: str,
         code_verifier: str,
         state: str,
-        authorization_params: Optional[Dict[str, Any]] = None
+        authorization_params: Optional[dict[str, Any]] = None
     ) -> str:
         """Build a URL for unlinking user accounts"""
         # Generate code challenge from verifier
@@ -839,17 +836,24 @@ class ServerClient(Generic[TStoreOptions]):
 
     async def backchannel_authentication(
         self,
-        options: Dict[str, Any]
-    ) -> Dict[str, Any]:
+        options: dict[str, Any]
+    ) -> dict[str, Any]:
         """
-        Initiates backchannel authentication with Auth0.
+        Performs backchannel authentication with Auth0.
 
         This method starts a Client-Initiated Backchannel Authentication (CIBA) flow,
         which allows an application to request authentication from a user via a separate
         device or channel.
 
+        Then polls the token endpoint until the user has authenticated or the request times out.
+
         Args:
-            options: Configuration options for backchannel authentication
+            options (dict): Configuration options for backchannel authentication
+                - login_hint (dict): Must contain a 'sub' field (e.g., {'sub': 'user_id'}).
+                - binding_message (str, optional): Message to display to the user.
+                - authorization_params (dict, optional): Additional authorization parameters.
+                    - requested_expiry (int, optional): Requested expiry time in seconds, default is 30 secs.
+                    - authorization_details (str, optional): JSON string for RAR.
 
         Returns:
             Token response data from the backchannel authentication
@@ -857,6 +861,97 @@ class ServerClient(Generic[TStoreOptions]):
         Raises:
             ApiError: If the backchannel authentication fails
         """
+        backchannel_data = await self.initiate_backchannel_authentication(options)
+        auth_req_id = backchannel_data.get("auth_req_id")
+        expires_in = backchannel_data.get(
+            "expires_in", 120)  # Default to 2 minutes
+        interval = backchannel_data.get(
+            "interval", 5)  # Default to 5 seconds
+
+        # Calculate when to stop polling
+        end_time = time.time() + expires_in
+
+        # Poll until we get a response or timeout
+        while time.time() < end_time:
+            # Make token request
+            try:
+                token_response = await self.backchannel_authentication_grant(auth_req_id)
+                return token_response
+
+            except Exception as e:
+                if isinstance(e, PollingApiError):
+                    if e.code == "authorization_pending":
+                        # Wait for the specified interval before polling again
+                        await asyncio.sleep(interval)
+                        continue
+                    if e.code == "slow_down":
+                        # Wait for the specified interval before polling again
+                        await asyncio.sleep(e.interval or interval)
+                        continue
+                raise ApiError(
+                    "backchannel_error",
+                    f"Backchannel authentication failed: {str(e) or 'Unknown error'}",
+                    e
+                )
+
+        # If we get here, we've timed out
+        raise ApiError(
+            "timeout", "Backchannel authentication timed out")
+
+    async def initiate_backchannel_authentication(
+            self,
+            options: dict[str, Any]
+    ) -> dict[str, Any]:
+        """
+        Start backchannel authentication with Auth0.
+
+        This method starts a Client-Initiated Backchannel Authentication (CIBA) flow,
+        which allows an application to request authentication from a user via a separate
+        device or channel.
+
+        Args:
+            options (dict): Configuration options for backchannel authentication
+                - login_hint (dict): Must contain a 'sub' field (e.g., {'sub': 'user_id'}).
+                - binding_message (str, optional): Message to display to the user.
+                - authorization_params (dict, optional): Additional authorization parameters.
+                    - requested_expiry (int, optional): Requested expiry time in seconds, default is 30 secs.
+                    - authorization_details (str, optional): JSON string for RAR.
+
+        Returns:
+            dict: Response data from the bc-authorize backchannel authentication
+                - auth_req_id (str): The authentication request ID.
+                - expires_in (int): Time in seconds until the request expires.
+                - interval (int, optional): Polling interval in seconds.
+
+        Raises:
+            ApiError: If the backchannel authentication fails
+
+        See:
+            https://auth0.com/docs/get-started/authentication-and-authorization-flow/client-initiated-backchannel-authentication-flow
+        """
+
+        sub = options.get('login_hint', {}).get("sub")
+        if not sub:
+            raise MissingRequiredArgumentError(
+                "login_hint.sub"
+            )
+
+        authorization_params = options.get('authorization_params')
+        if authorization_params is not None and not isinstance(authorization_params, dict):
+            raise ApiError(
+                "invalid_argument",
+                "authorization_params must be a dict"
+            )
+
+        if authorization_params:
+            requested_expiry = authorization_params.get("requested_expiry")
+            if requested_expiry is not None:
+                if not isinstance(requested_expiry, int) or requested_expiry <= 0:
+                    raise ApiError(
+                        "invalid_argument",
+                        "authorization_params.requested_expiry must be a positive integer"
+                    )
+
         try:
             # Fetch OpenID Connect metadata if not already fetched
             if not hasattr(self, '_oauth_metadata'):
@@ -875,21 +970,6 @@ class ServerClient(Generic[TStoreOptions]):
                     "Backchannel authentication is not supported by the authorization server"
                 )
 
-            # Get token endpoint
-            token_endpoint = self._oauth_metadata.get("token_endpoint")
-            if not token_endpoint:
-                raise ApiError(
-                    "configuration_error",
-                    "Token endpoint is missing in OIDC metadata"
-                )
-
-            sub = sub = options.get('login_hint', {}).get("sub")
-            if not sub:
-                raise ApiError(
-                    "invalid_parameter",
-                    "login_hint must contain a 'sub' field"
-                )
-
             # Prepare login hint in the required format
             login_hint = json.dumps({
                 "format": "iss_sub",
@@ -912,8 +992,8 @@ class ServerClient(Generic[TStoreOptions]):
             if self._default_authorization_params:
                 params.update(self._default_authorization_params)
 
-            if options.get('authorization_params'):
-                params.update(options.get('authorization_params'))
+            if authorization_params:
+                params.update(authorization_params)
 
             # Make the backchannel authentication request
             async with httpx.AsyncClient() as client:
@@ -933,10 +1013,6 @@ class ServerClient(Generic[TStoreOptions]):
 
                 backchannel_data = backchannel_response.json()
                 auth_req_id = backchannel_data.get("auth_req_id")
-                expires_in = backchannel_data.get(
-                    "expires_in", 120)  # Default to 2 minutes
-                interval = backchannel_data.get(
-                    "interval", 5)  # Default to 5 seconds
 
                 if not auth_req_id:
                     raise ApiError(
@@ -944,64 +1020,95 @@ class ServerClient(Generic[TStoreOptions]):
                         "Missing auth_req_id in backchannel authentication response"
                     )
 
-                # Poll for token using the auth_req_id
-                token_params = {
-                    "grant_type": "urn:openid:params:grant-type:ciba",
-                    "auth_req_id": auth_req_id,
-                    "client_id": self._client_id,
-                    "client_secret": self._client_secret
-                }
+                return backchannel_data
+
+        except Exception as e:
+            if isinstance(e, ApiError):
+                raise
+            raise ApiError(
+                "backchannel_error",
+                f"Backchannel authentication failed: {str(e) or 'Unknown error'}",
+                e
+            )
+
+    async def backchannel_authentication_grant(self, auth_req_id: str) -> dict[str, Any]:
+        """
+        Retrieves a token by exchanging an auth_req_id.
+
+        Args:
+            auth_req_id (str): The authentication request ID obtained from bc-authorize
+
+        Raises:
+            AccessTokenError: If there was an issue requesting the access token.
+
+        Returns:
+            A dictionary containing the token response from Auth0.
+        """
+        if not auth_req_id:
+            raise MissingRequiredArgumentError("auth_req_id")
+
+        try:
+            # Ensure we have the OIDC metadata
+            if not hasattr(self._oauth, "metadata") or not self._oauth.metadata:
+                self._oauth.metadata = await self._fetch_oidc_metadata(self._domain)
+
+            token_endpoint = self._oauth.metadata.get("token_endpoint")
+            if not token_endpoint:
+                raise ApiError("configuration_error",
+                               "Token endpoint missing in OIDC metadata")
+
+            # Prepare the token request parameters
+            token_params = {
+                "grant_type": "urn:openid:params:grant-type:ciba",
+                "auth_req_id": auth_req_id,
+                "client_id": self._client_id,
+                "client_secret": self._client_secret
+            }
+
+            # Exchange the auth_req_id for an access token
+            async with httpx.AsyncClient() as client:
+                response = await client.post(
+                    token_endpoint,
+                    data=token_params,
+                    auth=(self._client_id, self._client_secret)
+                )
 
-                # Calculate when to stop polling
-                end_time = time.time() + expires_in
-
-                # Poll until we get a response or timeout
-                while time.time() < end_time:
-                    # Make token request
-                    token_response = await client.post(token_endpoint, data=token_params)
-
-                    # Check for success (200 OK)
-                    if token_response.status_code == 200:
-                        # Success! Parse and return the token response
-                        return token_response.json()
-
-                    # Check for specific error that indicates we should continue polling
-                    if token_response.status_code == 400:
-                        error_data = token_response.json()
-                        error = error_data.get("error")
-
-                        # authorization_pending means we should keep polling
-                        if error == "authorization_pending":
-                            # Wait for the specified interval before polling again
-                            await asyncio.sleep(interval)
-                            continue
-
-                        # Other errors should be raised
-                        raise ApiError(
-                            error,
-                            error_data.get("error_description",
-                                           "Token request failed")
-                        )
-
-                    # Any other status code is an error
+                if response.status_code != 200:
+                    error_data = response.json()
+                    retry_after = response.headers.get("Retry-After")
+                    interval = int(retry_after) if retry_after is not None else None
+                    raise PollingApiError(
+                        error_data.get("error", "auth_req_id_error"),
+                        error_data.get("error_description",
+                                       "Failed to exchange auth_req_id"),
+                        interval
+                    )
+
+                try:
+                    token_response = response.json()
+                except json.JSONDecodeError:
                     raise ApiError(
-                        "token_error",
-                        f"Unexpected status code: {token_response.status_code}"
+                        "invalid_response",
+                        "Failed to parse token response as JSON"
                     )
 
-                # If we get here, we've timed out
-                raise ApiError(
-                    "timeout", "Backchannel authentication timed out")
+                # Add required fields if they are missing
+                if "expires_in" in token_response and "expires_at" not in token_response:
+                    token_response["expires_at"] = int(
+                        time.time()) + token_response["expires_in"]
+
+                return token_response
 
         except Exception as e:
-            print("Caught exception:", type(e), e.args, repr(e))
-            raise ApiError(
-                "backchannel_error",
-                f"Backchannel authentication failed: {str(e) or 'Unknown error'}",
+            if isinstance(e, (ApiError, PollingApiError)):
+                raise
+            raise AccessTokenError(
+                AccessTokenErrorCode.AUTH_REQ_ID_ERROR,
+                "There was an error while trying to exchange the auth_req_id for an access token.",
                 e
             )
 
-    async def get_token_by_refresh_token(self, options: Dict[str, Any]) -> Dict[str, Any]:
+    async def get_token_by_refresh_token(self, options: dict[str, Any]) -> dict[str, Any]:
         """
         Retrieves a token by exchanging a refresh token.
 
@@ -1074,7 +1181,7 @@ class ServerClient(Generic[TStoreOptions]):
                 e
             )
 
-    async def get_token_for_connection(self, options: Dict[str, Any]) -> Dict[str, Any]:
+    async def get_token_for_connection(self, options: dict[str, Any]) -> dict[str, Any]:
         """
         Retrieves a token for a connection.