auth0-server-python 1.0.0b14__tar.gz → 1.0.0b16__tar.gz

{auth0_server_python-1.0.0b14 → auth0_server_python-1.0.0b16}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: auth0-server-python
-Version: 1.0.0b14
+Version: 1.0.0b16
 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,58 @@ 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.
+
+#### Authenticating with Mutual TLS (mTLS)
+
+The SDK supports mTLS client authentication (RFC 8705): the client presents a TLS certificate during the handshake instead of a client secret. Pass `use_mtls=True` and a caller-built `ssl.SSLContext` that already has the certificate loaded:
+
+```python
+import ssl
+
+ssl_context = ssl.create_default_context()
+ssl_context.load_cert_chain("client.crt", "client.key")
+
+auth0 = ServerClient(
+    domain="login.example.com",   # self_managed_certs custom domain
+    client_id="<AUTH0_CLIENT_ID>",
+    use_mtls=True,
+    ssl_context=ssl_context,
+    secret="<AUTH0_SECRET>",
+)
+```
+
+`use_mtls=True` requires an Enterprise tenant with the Highly Regulated Identity add-on, a `self_managed_certs` custom domain, and mTLS endpoint aliases enabled. It cannot be combined with `client_secret`, `client_assertion_signing_key`, or a per-call `dpop_key`. Each raises `ConfigurationError`. See the [Auth0 mTLS configuration docs](https://auth0.com/docs/get-started/applications/configure-mtls) for tenant-side setup steps.
+
+See [examples/MutualTLS.md](examples/MutualTLS.md) for the full setup guide, certificate generation, and token sender-constraining details.
+
 ### 3. Add login to your Application (interactive)
 
 Before using redirect-based login, ensure the `redirect_uri` is configured when initializing the SDK:
@@ -225,6 +277,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.0b14 → auth0_server_python-1.0.0b16}/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,58 @@ 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.
+
+#### Authenticating with Mutual TLS (mTLS)
+
+The SDK supports mTLS client authentication (RFC 8705): the client presents a TLS certificate during the handshake instead of a client secret. Pass `use_mtls=True` and a caller-built `ssl.SSLContext` that already has the certificate loaded:
+
+```python
+import ssl
+
+ssl_context = ssl.create_default_context()
+ssl_context.load_cert_chain("client.crt", "client.key")
+
+auth0 = ServerClient(
+    domain="login.example.com",   # self_managed_certs custom domain
+    client_id="<AUTH0_CLIENT_ID>",
+    use_mtls=True,
+    ssl_context=ssl_context,
+    secret="<AUTH0_SECRET>",
+)
+```
+
+`use_mtls=True` requires an Enterprise tenant with the Highly Regulated Identity add-on, a `self_managed_certs` custom domain, and mTLS endpoint aliases enabled. It cannot be combined with `client_secret`, `client_assertion_signing_key`, or a per-call `dpop_key`. Each raises `ConfigurationError`. See the [Auth0 mTLS configuration docs](https://auth0.com/docs/get-started/applications/configure-mtls) for tenant-side setup steps.
+
+See [examples/MutualTLS.md](examples/MutualTLS.md) for the full setup guide, certificate generation, and token sender-constraining details.
+
 ### 3. Add login to your Application (interactive)
 
 Before using redirect-based login, ensure the `redirect_uri` is configured when initializing the SDK:
@@ -200,6 +252,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.0b14 → auth0_server_python-1.0.0b16}/pyproject.toml

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

auth0_server_python-1.0.0b16/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.0b16/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.0b14 → auth0_server_python-1.0.0b16}/src/auth0_server_python/auth_server/mfa_client.py

@@ -4,8 +4,10 @@ Handles Multi-Factor Authentication operations against the Auth0 MFA API.
 """
 
 import json
+import ssl
 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 +30,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 +69,15 @@ 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,
+        use_mtls: bool = False,
+        ssl_context: Optional[ssl.SSLContext] = None,
+        token_endpoint_resolver: Optional[Callable[..., Awaitable[str]]] = None,
     ):
         if callable(domain):
             self._domain = None
@@ -80,12 +91,29 @@ 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
+        self._use_mtls = use_mtls
+        self._ssl_context = ssl_context
+        self._token_endpoint_resolver = token_endpoint_resolver
 
     def _get_http_client(self, **kwargs) -> httpx.AsyncClient:
         """Return an httpx.AsyncClient with default headers injected."""
         headers = {**kwargs.pop("headers", {}), **self._headers}
+        if self._use_mtls and "verify" not in kwargs:
+            kwargs["verify"] = self._ssl_context
         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 +165,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 +421,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 +444,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 +511,28 @@ 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 dpop_key is combined with use_mtls. DPoP and mTLS
+                use incompatible token-binding mechanisms and cannot be used together.
+            ConfigurationError: If neither client_secret nor client_assertion_signing_key is configured.
         """
+        if self._use_mtls and dpop_key is not None:
+            raise ConfigurationError(
+                "dpop_key cannot be combined with use_mtls. DPoP and mTLS bind tokens "
+                "differently. DPoP would take precedence and the token would not be "
+                "certificate-bound."
+            )
         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,8 +551,10 @@ class MfaClient:
             )
 
         try:
-            base_url = await self._resolve_base_url(store_options)
-            token_endpoint = f"{base_url}/oauth/token"
+            if self._use_mtls and self._token_endpoint_resolver:
+                token_endpoint = await self._token_endpoint_resolver(store_options)
+            else:
+                token_endpoint = f"{base_url}/oauth/token"
 
             async with self._get_http_client() as client:
                 headers = {"Content-Type": "application/x-www-form-urlencoded"}
@@ -626,6 +668,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"
                 )

{auth0_server_python-1.0.0b14 → auth0_server_python-1.0.0b16}/src/auth0_server_python/auth_server/my_account_client.py

@@ -1,4 +1,5 @@
 import json
+import ssl
 from typing import TYPE_CHECKING, Optional
 from urllib.parse import quote, unquote, urlparse
 
@@ -46,20 +47,31 @@ class MyAccountClient:
     Client for interacting with the Auth0 MyAccount API.
     """
 
-    def __init__(self, domain: str, headers: Optional[dict[str, str]] = None):
+    def __init__(
+        self,
+        domain: str,
+        headers: Optional[dict[str, str]] = None,
+        ssl_context: Optional[ssl.SSLContext] = None,
+    ):
         """
         Initialize the MyAccount API client.
 
         Args:
             domain: Auth0 domain (e.g., '<tenant>.<locality>.auth0.com')
             headers: Optional default headers to include on every request
+            ssl_context: Optional SSL context for mTLS. When provided, the client
+                certificate is presented on every request so the My Account API can
+                verify cnf.x5t#S256 binding on cert-bound access tokens.
         """
         self._domain = domain
         self._headers = headers or {}
+        self._ssl_context = ssl_context
 
     def _get_http_client(self, **kwargs) -> httpx.AsyncClient:
         """Return an httpx.AsyncClient with default headers injected."""
         headers = {**kwargs.pop("headers", {}), **self._headers}
+        if self._ssl_context is not None and "verify" not in kwargs:
+            kwargs["verify"] = self._ssl_context
         return httpx.AsyncClient(headers=headers, **kwargs)
 
     @property