auth0-server-python 1.0.0b13__tar.gz → 1.0.0b15__tar.gz

{auth0_server_python-1.0.0b13 → auth0_server_python-1.0.0b15}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: auth0-server-python
-Version: 1.0.0b13
+Version: 1.0.0b15
 Summary: Auth0 server-side Python SDK
 License: MIT
 License-File: LICENSE
@@ -48,7 +48,7 @@ pip install auth0-server-python
 If you’re using Poetry:
 
 ```shell
-poetry install auth0-server-python
+poetry add auth0-server-python
 ```
 
 ### 2. Create the Auth0 SDK client
@@ -65,7 +65,7 @@ auth0 = ServerClient(
     client_secret='<AUTH0_CLIENT_SECRET>',
     secret='<AUTH0_SECRET>',
     authorization_params= {
-      redirect_uri: '<AUTH0_REDIRECT_URI>',
+      'redirect_uri': '<AUTH0_REDIRECT_URI>',
     }
 )
 ```
@@ -80,6 +80,35 @@ The `AUTH0_SECRET` is the key used to encrypt the session and transaction cookie
 openssl rand -hex 64
 ```
 
+#### Authenticating with Private Key JWT
+
+The SDK authenticates to Auth0 with either a client secret or a Private Key JWT (`private_key_jwt`). To use Private Key JWT, pass your private signing key as `client_assertion_signing_key` instead of `client_secret`:
+
+```python
+from auth0_server_python.auth_server.server_client import ServerClient
+
+with open('private_key.pem') as f:
+    private_key = f.read()
+
+auth0 = ServerClient(
+    domain='<AUTH0_DOMAIN>',
+    client_id='<AUTH0_CLIENT_ID>',
+    client_assertion_signing_key=private_key,
+    secret='<AUTH0_SECRET>',
+    authorization_params={
+        'redirect_uri': '<AUTH0_REDIRECT_URI>',
+    }
+)
+```
+
+The key must be a PKCS8 PEM private key. Register its public key on your Auth0 application under **Settings → Credentials**, and set the application's authentication method to Private Key JWT. The signing algorithm defaults to `RS256` and can be overridden with `client_assertion_signing_alg`. Auth0 accepts `RS256`, `RS384`, and `PS256`, all of which use an RSA key. The algorithm must match the key type and the algorithm chosen when the public key credential was created.
+
+> [!NOTE]
+> The passkey challenge endpoints (`register` and `challenge`) accept only a client secret, so a client configured with just a signing key cannot use them.
+
+> [!IMPORTANT]
+> Private keys must not be committed to source control. Load them from a secure secret store or an environment-provided file.
+
 ### 3. Add login to your Application (interactive)
 
 Before using redirect-based login, ensure the `redirect_uri` is configured when initializing the SDK:
@@ -172,6 +201,11 @@ response = await auth0.custom_token_exchange(
 print(response.access_token)
 ```
 
+Building on token exchange, the SDK also supports:
+
+- **[Delegation and Impersonation](examples/CustomTokenExchange.md#3-actor-tokens-delegation)** - exchange with an `actor_token` so the issued tokens record who is acting on whose behalf (the `act` claim).
+- **[Impersonation via Session Transfer (STT)](examples/CustomTokenExchange.md#8-impersonation-via-session-transfer-stt)** - mint a Session Transfer Token to log an agent into a target app as a customer, via `request_session_transfer_token()` and `build_session_transfer_redirect()`.
+
 For more details and examples, see [examples/CustomTokenExchange.md](examples/CustomTokenExchange.md).
 
 ### 5. Multiple Custom Domains (MCD)
@@ -220,6 +254,10 @@ Let a logged-in user manage their own enrolled authentication methods — enroll
 
 Bind tokens to a key your server holds ([RFC 9449](https://www.rfc-editor.org/rfc/rfc9449)) so a stolen token alone cannot be replayed. DPoP is supported for Passkey sign-in (`signin_with_passkey`) and the authentication-methods/factors methods on `MyAccountClient`. For key generation and usage, see [examples/Passkeys.md](examples/Passkeys.md#3-dpop-bound-passkey-tokens-optional) and [examples/MyAccountAuthenticationMethods.md](examples/MyAccountAuthenticationMethods.md#dpop).
 
+### 10. Passwordless Authentication
+
+Sign users in with a one-time code sent by email or SMS, or with a magic link sent by email, via [Auth0 embedded passwordless login](https://auth0.com/docs/authenticate/passwordless/implement-login/embedded-login/relevant-api-endpoints). OTP verification and the magic-link callback each establish a server-side session like every other login path. For prerequisites, both flows, custom scopes/audiences, step-up MFA, and error handling, see [examples/Passwordless.md](examples/Passwordless.md).
+
 ## Feedback
 
 ### Contributing

{auth0_server_python-1.0.0b13 → auth0_server_python-1.0.0b15}/README.md

@@ -23,7 +23,7 @@ pip install auth0-server-python
 If you’re using Poetry:
 
 ```shell
-poetry install auth0-server-python
+poetry add auth0-server-python
 ```
 
 ### 2. Create the Auth0 SDK client
@@ -40,7 +40,7 @@ auth0 = ServerClient(
     client_secret='<AUTH0_CLIENT_SECRET>',
     secret='<AUTH0_SECRET>',
     authorization_params= {
-      redirect_uri: '<AUTH0_REDIRECT_URI>',
+      'redirect_uri': '<AUTH0_REDIRECT_URI>',
     }
 )
 ```
@@ -55,6 +55,35 @@ The `AUTH0_SECRET` is the key used to encrypt the session and transaction cookie
 openssl rand -hex 64
 ```
 
+#### Authenticating with Private Key JWT
+
+The SDK authenticates to Auth0 with either a client secret or a Private Key JWT (`private_key_jwt`). To use Private Key JWT, pass your private signing key as `client_assertion_signing_key` instead of `client_secret`:
+
+```python
+from auth0_server_python.auth_server.server_client import ServerClient
+
+with open('private_key.pem') as f:
+    private_key = f.read()
+
+auth0 = ServerClient(
+    domain='<AUTH0_DOMAIN>',
+    client_id='<AUTH0_CLIENT_ID>',
+    client_assertion_signing_key=private_key,
+    secret='<AUTH0_SECRET>',
+    authorization_params={
+        'redirect_uri': '<AUTH0_REDIRECT_URI>',
+    }
+)
+```
+
+The key must be a PKCS8 PEM private key. Register its public key on your Auth0 application under **Settings → Credentials**, and set the application's authentication method to Private Key JWT. The signing algorithm defaults to `RS256` and can be overridden with `client_assertion_signing_alg`. Auth0 accepts `RS256`, `RS384`, and `PS256`, all of which use an RSA key. The algorithm must match the key type and the algorithm chosen when the public key credential was created.
+
+> [!NOTE]
+> The passkey challenge endpoints (`register` and `challenge`) accept only a client secret, so a client configured with just a signing key cannot use them.
+
+> [!IMPORTANT]
+> Private keys must not be committed to source control. Load them from a secure secret store or an environment-provided file.
+
 ### 3. Add login to your Application (interactive)
 
 Before using redirect-based login, ensure the `redirect_uri` is configured when initializing the SDK:
@@ -147,6 +176,11 @@ response = await auth0.custom_token_exchange(
 print(response.access_token)
 ```
 
+Building on token exchange, the SDK also supports:
+
+- **[Delegation and Impersonation](examples/CustomTokenExchange.md#3-actor-tokens-delegation)** - exchange with an `actor_token` so the issued tokens record who is acting on whose behalf (the `act` claim).
+- **[Impersonation via Session Transfer (STT)](examples/CustomTokenExchange.md#8-impersonation-via-session-transfer-stt)** - mint a Session Transfer Token to log an agent into a target app as a customer, via `request_session_transfer_token()` and `build_session_transfer_redirect()`.
+
 For more details and examples, see [examples/CustomTokenExchange.md](examples/CustomTokenExchange.md).
 
 ### 5. Multiple Custom Domains (MCD)
@@ -195,6 +229,10 @@ Let a logged-in user manage their own enrolled authentication methods — enroll
 
 Bind tokens to a key your server holds ([RFC 9449](https://www.rfc-editor.org/rfc/rfc9449)) so a stolen token alone cannot be replayed. DPoP is supported for Passkey sign-in (`signin_with_passkey`) and the authentication-methods/factors methods on `MyAccountClient`. For key generation and usage, see [examples/Passkeys.md](examples/Passkeys.md#3-dpop-bound-passkey-tokens-optional) and [examples/MyAccountAuthenticationMethods.md](examples/MyAccountAuthenticationMethods.md#dpop).
 
+### 10. Passwordless Authentication
+
+Sign users in with a one-time code sent by email or SMS, or with a magic link sent by email, via [Auth0 embedded passwordless login](https://auth0.com/docs/authenticate/passwordless/implement-login/embedded-login/relevant-api-endpoints). OTP verification and the magic-link callback each establish a server-side session like every other login path. For prerequisites, both flows, custom scopes/audiences, step-up MFA, and error handling, see [examples/Passwordless.md](examples/Passwordless.md).
+
 ## Feedback
 
 ### Contributing

{auth0_server_python-1.0.0b13 → auth0_server_python-1.0.0b15}/pyproject.toml

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

auth0_server_python-1.0.0b15/src/auth0_server_python/auth_schemes/client_assertion.py

@@ -0,0 +1,63 @@
+import secrets
+import time
+from typing import Union
+
+import jwt
+
+from auth0_server_python.error import ConfigurationError
+
+# RFC 7523 client-assertion type for private_key_jwt authentication.
+CLIENT_ASSERTION_TYPE = "urn:ietf:params:oauth:client-assertion-type:jwt-bearer"
+
+# Assertion lifetime in seconds.
+_ASSERTION_LIFETIME = 60
+
+
+def validate_client_assertion_key(private_key: Union[str, bytes], alg: str = "RS256") -> None:
+    """
+    Verify the signing key and algorithm can produce a client assertion.
+
+    Args:
+        private_key: The client's private signing key (PKCS8 PEM string or bytes).
+        alg: The signing algorithm (defaults to "RS256").
+
+    Raises:
+        ConfigurationError: If the key is malformed or does not match the algorithm.
+    """
+    try:
+        jwt.encode({"probe": True}, private_key, algorithm=alg)
+    except Exception as e:
+        raise ConfigurationError(
+            f"Invalid client_assertion_signing_key for algorithm {alg}: {e}"
+        ) from e
+
+
+def build_client_assertion(
+    private_key: Union[str, bytes],
+    client_id: str,
+    issuer: str,
+    alg: str = "RS256",
+) -> str:
+    """
+    Mint a private_key_jwt client assertion for token-endpoint authentication (RFC 7523).
+
+    Args:
+        private_key: The client's private signing key (PKCS8 PEM string or bytes).
+        client_id: The Auth0 client ID, used as both the issuer and subject claim.
+        issuer: The authorization server issuer identifier, used as the audience claim.
+        alg: The signing algorithm (defaults to "RS256").
+
+    Returns:
+        The signed client-assertion JWT.
+    """
+    now = int(time.time())
+    payload = {
+        "iss": client_id,
+        "sub": client_id,
+        "aud": issuer,
+        "iat": now,
+        "nbf": now,
+        "exp": now + _ASSERTION_LIFETIME,
+        "jti": secrets.token_urlsafe(32),
+    }
+    return jwt.encode(payload, private_key, algorithm=alg)

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

@@ -0,0 +1,6 @@
+from .mfa_client import MfaClient
+from .my_account_client import MyAccountClient
+from .passwordless_client import PasswordlessClient
+from .server_client import ServerClient
+
+__all__ = ["ServerClient", "MyAccountClient", "MfaClient", "PasswordlessClient"]

{auth0_server_python-1.0.0b13 → auth0_server_python-1.0.0b15}/src/auth0_server_python/auth_server/mfa_client.py

@@ -5,7 +5,8 @@ Handles Multi-Factor Authentication operations against the Auth0 MFA API.
 
 import json
 import time
-from typing import TYPE_CHECKING, Any, Callable, Optional, Union
+from collections.abc import Awaitable, Callable
+from typing import TYPE_CHECKING, Any, Optional, Union
 
 import httpx
 
@@ -28,6 +29,7 @@ from auth0_server_python.auth_types import (
 )
 from auth0_server_python.encryption.encrypt import decrypt, encrypt
 from auth0_server_python.error import (
+    ConfigurationError,
     DomainResolverError,
     MfaChallengeError,
     MfaEnrollmentError,
@@ -66,7 +68,12 @@ class MfaClient:
         secret: str,
         state_store=None,
         state_identifier: str = "_a0_session",
-        headers: Optional[dict[str, str]] = None
+        headers: Optional[dict[str, str]] = None,
+        session_establisher: Optional[
+            Callable[..., Awaitable[None]]
+        ] = None,
+        mfa_token_ttl: int = DEFAULT_MFA_TOKEN_TTL,
+        apply_client_authentication: Optional[Callable] = None,
     ):
         if callable(domain):
             self._domain = None
@@ -80,12 +87,24 @@ class MfaClient:
         self._state_store = state_store
         self._state_identifier = state_identifier
         self._headers = headers or {}
+        self._session_establisher = session_establisher
+        if mfa_token_ttl <= 0:
+            raise ConfigurationError("mfa_token_ttl must be a positive number of seconds")
+        self._mfa_token_ttl = mfa_token_ttl
+        self._apply_client_authentication = apply_client_authentication
 
     def _get_http_client(self, **kwargs) -> httpx.AsyncClient:
         """Return an httpx.AsyncClient with default headers injected."""
         headers = {**kwargs.pop("headers", {}), **self._headers}
         return httpx.AsyncClient(headers=headers, **kwargs)
 
+    def _apply_mfa_client_authentication(self, body: dict, base_url: str) -> None:
+        """Add client authentication to an MFA request body (client_secret or client assertion)."""
+        if self._apply_client_authentication:
+            self._apply_client_authentication(body, f"{base_url}/", in_body=True)
+        elif self._client_secret:
+            body["client_secret"] = self._client_secret
+
     async def _resolve_base_url(
         self,
         store_options: Optional[dict[str, Any]] = None
@@ -137,7 +156,7 @@ class MfaClient:
             raise MfaTokenInvalidError()
 
         elapsed = int(time.time()) - context.created_at
-        if elapsed > DEFAULT_MFA_TOKEN_TTL:
+        if elapsed > self._mfa_token_ttl:
             raise MfaTokenExpiredError()
 
         return context
@@ -393,6 +412,7 @@ class MfaClient:
 
         Raises:
             MfaChallengeError: When the challenge fails.
+            ConfigurationError: If neither client_secret nor client_assertion_signing_key is configured.
         """
         mfa_token = options.get("mfa_token")
         if not mfa_token:
@@ -415,9 +435,9 @@ class MfaClient:
         body: dict[str, Any] = {
             "mfa_token": context.mfa_token,
             "client_id": self._client_id,
-            "client_secret": self._client_secret,
             "challenge_type": challenge_type
         }
+        self._apply_mfa_client_authentication(body, base_url)
 
         if "authenticator_id" in options and options["authenticator_id"]:
             body["authenticator_id"] = options["authenticator_id"]
@@ -482,17 +502,20 @@ class MfaClient:
             MfaVerifyError: When verification fails, or when dpop_key was supplied
                 but the server returned an unbound (Bearer) token.
             MfaRequiredError: When chained MFA is required.
+            ConfigurationError: If neither client_secret nor client_assertion_signing_key is configured.
         """
         mfa_token = options.get("mfa_token")
         if not mfa_token:
             raise MfaTokenInvalidError()
         context = self.decrypt_mfa_token(mfa_token)
 
+        base_url = await self._resolve_base_url(store_options)
+
         body: dict[str, Any] = {
             "client_id": self._client_id,
-            "client_secret": self._client_secret,
             "mfa_token": context.mfa_token
         }
+        self._apply_mfa_client_authentication(body, base_url)
 
         if "otp" in options:
             body["grant_type"] = "http://auth0.com/oauth/grant-type/mfa-otp"
@@ -511,7 +534,6 @@ class MfaClient:
             )
 
         try:
-            base_url = await self._resolve_base_url(store_options)
             token_endpoint = f"{base_url}/oauth/token"
 
             async with self._get_http_client() as client:
@@ -626,6 +648,14 @@ class MfaClient:
             )
 
             if not state_data:
+                if self._session_establisher:
+                    await self._session_establisher(
+                        verify_response=verify_response,
+                        audience=audience,
+                        scope=scope,
+                        store_options=store_options,
+                    )
+                    return
                 raise MfaVerifyError(
                     "No existing session found to update with MFA tokens"
                 )