auth0-server-python 1.0.0b10__tar.gz → 1.0.0b11__tar.gz

{auth0_server_python-1.0.0b10 → auth0_server_python-1.0.0b11}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: auth0-server-python
-Version: 1.0.0b10
+Version: 1.0.0b11
 Summary: Auth0 server-side Python SDK
 License: MIT
 License-File: LICENSE
@@ -129,6 +129,10 @@ async def callback(request: Request):
     return RedirectResponse(url="/")
 ```
 
+#### Organizations
+
+The SDK supports [Auth0 Organizations](https://auth0.com/docs/organizations) with first-class `organization` and `invitation` parameters on `ServerClient` and `StartInteractiveLoginOptions`. Token claim validation is enforced automatically at callback. For setup, invitation flows, error handling, and reading org data from the session, see [examples/InteractiveLogin.md](examples/InteractiveLogin.md#8-organizations).
+
 ### 4. Login with Custom Token Exchange
 
 If you're migrating from a legacy authentication system or integrating with a custom identity provider, you can exchange external tokens for Auth0 tokens using the OAuth 2.0 Token Exchange specification (RFC 8693):

{auth0_server_python-1.0.0b10 → auth0_server_python-1.0.0b11}/README.md

@@ -104,6 +104,10 @@ async def callback(request: Request):
     return RedirectResponse(url="/")
 ```
 
+#### Organizations
+
+The SDK supports [Auth0 Organizations](https://auth0.com/docs/organizations) with first-class `organization` and `invitation` parameters on `ServerClient` and `StartInteractiveLoginOptions`. Token claim validation is enforced automatically at callback. For setup, invitation flows, error handling, and reading org data from the session, see [examples/InteractiveLogin.md](examples/InteractiveLogin.md#8-organizations).
+
 ### 4. Login with Custom Token Exchange
 
 If you're migrating from a legacy authentication system or integrating with a custom identity provider, you can exchange external tokens for Auth0 tokens using the OAuth 2.0 Token Exchange specification (RFC 8693):

{auth0_server_python-1.0.0b10 → auth0_server_python-1.0.0b11}/pyproject.toml

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

{auth0_server_python-1.0.0b10 → auth0_server_python-1.0.0b11}/src/auth0_server_python/auth_server/server_client.py

@@ -54,6 +54,7 @@ from auth0_server_python.error import (
     MfaRequiredError,
     MissingRequiredArgumentError,
     MissingTransactionError,
+    OrganizationTokenValidationError,
     PollingApiError,
     StartLinkUserError,
 )
@@ -61,6 +62,7 @@ from auth0_server_python.telemetry import Telemetry
 from auth0_server_python.utils import PKCE, URL, State
 from auth0_server_python.utils.helpers import (
     build_domain_resolver_context,
+    validate_org_claims,
     validate_resolved_domain_value,
 )
 
@@ -96,6 +98,7 @@ class ServerClient(Generic[TStoreOptions]):
         state_identifier: str = "_a0_session",
         authorization_params: Optional[dict[str, Any]] = None,
         pushed_authorization_requests: bool = False,
+        organization: Optional[str] = None,
     ):
         """
         Initialize the Auth0 server client.
@@ -112,6 +115,9 @@ class ServerClient(Generic[TStoreOptions]):
             state_identifier: Identifier for state data
             authorization_params: Default parameters for authorization requests
             pushed_authorization_requests: Whether to use Pushed Authorization Requests
+            organization: Default organization for all login flows from this client.
+                Can be an org ID (e.g. 'org_abc123') or an org name (e.g. 'acme-corp').
+                Per-login values passed in StartInteractiveLoginOptions always override this.
         """
         if not secret:
             raise MissingRequiredArgumentError("secret")
@@ -146,6 +152,7 @@ class ServerClient(Generic[TStoreOptions]):
         self._secret = secret
         self._default_authorization_params = authorization_params or {}
         self._pushed_authorization_requests = pushed_authorization_requests  # store the flag
+        self._organization = organization
 
         # Initialize stores
         self._transaction_store = transaction_store
@@ -207,6 +214,7 @@ class ServerClient(Generic[TStoreOptions]):
 
         return value.rstrip('/')
 
+
     async def _resolve_current_domain(self, store_options=None) -> str:
         """Resolve domain from resolver function or return static domain."""
         if self._domain_resolver:
@@ -502,6 +510,16 @@ class ServerClient(Generic[TStoreOptions]):
         merged_scope = self._merge_scope_with_defaults(requested_scope, audience)
         auth_params["scope"] = merged_scope
 
+        # Typed org/invitation fields win over anything already in auth_params from authorization_params.
+        resolved_org = options.organization or self._organization
+        if resolved_org and not resolved_org.strip():
+            raise InvalidArgumentError("organization", "organization must not be blank")
+        if resolved_org:
+            auth_params["organization"] = resolved_org
+
+        if options.invitation:
+            auth_params["invitation"] = options.invitation
+
         # Build the transaction data to store with domain
         transaction_data = TransactionData(
             code_verifier=code_verifier,
@@ -509,6 +527,7 @@ class ServerClient(Generic[TStoreOptions]):
             audience=audience,
             domain=origin_domain,
             redirect_uri=auth_params.get("redirect_uri"),
+            organization=resolved_org,
         )
 
         # Store the transaction data
@@ -638,8 +657,26 @@ class ServerClient(Generic[TStoreOptions]):
         user_info = token_response.get("userinfo")
         user_claims = None
         id_token = token_response.get("id_token")
+        expected_org = transaction_data.organization
+
+        if not user_info and not id_token and expected_org:
+            raise OrganizationTokenValidationError(
+                "Organization was requested but the token response included neither an ID token nor userinfo; "
+                "cannot verify organization membership"
+            )
 
         if user_info:
+            if not isinstance(user_info, dict):
+                if expected_org:
+                    raise OrganizationTokenValidationError(
+                        "Userinfo response is not a valid claims dictionary; cannot verify organization membership"
+                    )
+                raise ApiError(
+                    "invalid_response",
+                    "Userinfo response is not a valid claims dictionary"
+                )
+            if expected_org:
+                validate_org_claims(user_info, expected_org)
             user_claims = UserClaims.parse_obj(user_info)
         elif id_token:
             # Fetch JWKS for signature verification
@@ -656,6 +693,10 @@ class ServerClient(Generic[TStoreOptions]):
                 if self._normalize_url(token_issuer) != self._normalize_url(origin_issuer):
                     raise IssuerValidationError("ID token issuer mismatch. Ensure your Auth0 domain is configured correctly.")
 
+                # Organization claim validation — mandatory when org was requested.
+                if expected_org:
+                    validate_org_claims(claims, expected_org)
+
                 user_claims = UserClaims.parse_obj(claims)
             except ValueError as e:
                 raise ApiError("jwks_key_not_found", str(e))
@@ -1283,7 +1324,10 @@ class ServerClient(Generic[TStoreOptions]):
         while time.time() < end_time:
             # Make token request
             try:
-                token_response = await self.backchannel_authentication_grant(auth_req_id, store_options=store_options)
+                token_response = await self.backchannel_authentication_grant(
+                    auth_req_id,
+                    store_options=store_options,
+                )
                 return token_response
 
             except Exception as e:
@@ -2243,10 +2287,45 @@ class ServerClient(Generic[TStoreOptions]):
             https://datatracker.ietf.org/doc/html/rfc8693
         """
         try:
-            # Validate options (Pydantic handles this automatically)
             if not isinstance(options, CustomTokenExchangeOptions):
                 options = CustomTokenExchangeOptions(**options)
 
+            if not options.subject_token.strip():
+                raise CustomTokenExchangeError(
+                    CustomTokenExchangeErrorCode.INVALID_TOKEN_FORMAT,
+                    "subject_token cannot be empty or whitespace-only"
+                )
+            if not options.subject_token_type.strip():
+                raise CustomTokenExchangeError(
+                    CustomTokenExchangeErrorCode.INVALID_TOKEN_FORMAT,
+                    "subject_token_type cannot be empty or whitespace-only"
+                )
+            if options.subject_token.strip().startswith("Bearer "):
+                raise CustomTokenExchangeError(
+                    CustomTokenExchangeErrorCode.INVALID_TOKEN_FORMAT,
+                    "subject_token should not include 'Bearer ' prefix"
+                )
+            if options.actor_token is not None and not options.actor_token.strip():
+                raise CustomTokenExchangeError(
+                    CustomTokenExchangeErrorCode.INVALID_TOKEN_FORMAT,
+                    "actor_token cannot be empty or whitespace-only"
+                )
+            if options.actor_token and options.actor_token.strip().startswith("Bearer "):
+                raise CustomTokenExchangeError(
+                    CustomTokenExchangeErrorCode.INVALID_TOKEN_FORMAT,
+                    "actor_token should not include 'Bearer ' prefix"
+                )
+            if options.actor_token and not options.actor_token_type:
+                raise CustomTokenExchangeError(
+                    CustomTokenExchangeErrorCode.MISSING_ACTOR_TOKEN_TYPE,
+                    "actor_token_type is required when actor_token is provided"
+                )
+            if options.actor_token_type and not options.actor_token:
+                raise CustomTokenExchangeError(
+                    CustomTokenExchangeErrorCode.MISSING_ACTOR_TOKEN,
+                    "actor_token is required when actor_token_type is provided"
+                )
+
             # Resolve domain
             domain = await self._resolve_current_domain(store_options)
             metadata = await self._get_oidc_metadata_cached(domain)
@@ -2309,8 +2388,25 @@ class ServerClient(Generic[TStoreOptions]):
                         "Failed to parse token response as JSON"
                     )
 
-                # Validate and return response
-                return TokenExchangeResponse(**token_data)
+                token_response = TokenExchangeResponse(**token_data)
+
+                # Surface the actor claim for delegation exchanges. Best-effort:
+                # a decode/verify hiccup must not fail an exchange the token
+                # endpoint already accepted, so act stays None on any failure.
+                if options.actor_token and token_response.id_token:
+                    try:
+                        jwks = await self._get_jwks_cached(domain, metadata)
+                        claims = await self._verify_and_decode_jwt(
+                            token_response.id_token, jwks, audience=self._client_id
+                        )
+                        # Apply the same normalized issuer check the login path uses
+                        # before trusting any claim from the token.
+                        if self._normalize_url(claims.get("iss", "")) == self._normalize_url(metadata.get("issuer")):
+                            token_response.act = claims.get("act")
+                    except Exception:
+                        token_response.act = None
+
+                return token_response
 
         except ValidationError as e:
             raise CustomTokenExchangeError(
@@ -2386,6 +2482,7 @@ class ServerClient(Generic[TStoreOptions]):
             # Extract user claims from ID token if present
             user_claims = None
             sid = PKCE.generate_random_string(32)  # Default sid
+
             if token_response.id_token:
                 # Fetch JWKS and verify ID token signature
                 jwks = await self._get_jwks_cached(domain, metadata)
@@ -2402,6 +2499,8 @@ class ServerClient(Generic[TStoreOptions]):
                             "ID token issuer mismatch. Ensure your Auth0 domain is configured correctly."
                         )
 
+                    # UserClaims allows extra fields, so any act claim in the
+                    # verified id_token is carried onto the session user here.
                     user_claims = UserClaims.parse_obj(claims)
                     # Extract sid from token if available
                     sid = claims.get("sid", sid)
@@ -2467,7 +2566,7 @@ class ServerClient(Generic[TStoreOptions]):
             return result
 
         except Exception as e:
-            if isinstance(e, (CustomTokenExchangeError, ApiError)):
+            if isinstance(e, (CustomTokenExchangeError, ApiError, IssuerValidationError)):
                 raise
             raise CustomTokenExchangeError(
                 CustomTokenExchangeErrorCode.TOKEN_EXCHANGE_FAILED,

{auth0_server_python-1.0.0b10 → auth0_server_python-1.0.0b11}/src/auth0_server_python/auth_types/__init__.py

@@ -5,7 +5,7 @@ These Pydantic models provide type safety and validation for all SDK data struct
 
 from typing import Any, Literal, Optional, Union
 
-from pydantic import BaseModel, Field, field_validator, model_validator
+from pydantic import BaseModel, Field
 
 
 class UserClaims(BaseModel):
@@ -22,6 +22,7 @@ class UserClaims(BaseModel):
     email: Optional[str] = None
     email_verified: Optional[bool] = None
     org_id: Optional[str] = None
+    org_name: Optional[str] = None
 
     class Config:
         extra = "allow"  # Allow additional fields not defined in the model
@@ -91,6 +92,7 @@ class TransactionData(BaseModel):
     auth_session: Optional[str] = None
     redirect_uri: Optional[str] = None
     domain: Optional[str] = None
+    organization: Optional[str] = None
 
     class Config:
         extra = "allow"  # Allow additional fields not defined in the model
@@ -128,6 +130,7 @@ class ServerClientOptionsBase(BaseModel):
     transaction_identifier: Optional[str] = "_a0_tx"
     state_identifier: Optional[str] = "_a0_session"
     custom_fetch: Optional[Any] = None  # Function type hint would be more complex
+    organization: Optional[str] = None
 
 
 class ServerClientOptionsWithSecret(ServerClientOptionsBase):
@@ -147,6 +150,8 @@ class StartInteractiveLoginOptions(BaseModel):
     pushed_authorization_requests: Optional[bool] = False
     app_state: Optional[Any] = None
     authorization_params: Optional[dict[str, Any]] = None
+    organization: Optional[str] = None
+    invitation: Optional[str] = None
 
 
 class LogoutOptions(BaseModel):
@@ -257,8 +262,8 @@ class CustomTokenExchangeOptions(BaseModel):
         organization: Organization identifier for the token exchange (optional)
         authorization_params: Additional OAuth parameters (optional)
     """
-    subject_token: str = Field(..., min_length=1)
-    subject_token_type: str = Field(..., min_length=1)
+    subject_token: str
+    subject_token_type: str
     audience: Optional[str] = None
     scope: Optional[str] = None
     actor_token: Optional[str] = None
@@ -266,24 +271,6 @@ class CustomTokenExchangeOptions(BaseModel):
     organization: Optional[str] = None
     authorization_params: Optional[dict[str, Any]] = None
 
-    @field_validator('subject_token', 'actor_token')
-    @classmethod
-    def validate_token_format(cls, v: Optional[str]) -> Optional[str]:
-        """Validate token doesn't have Bearer prefix and isn't whitespace-only."""
-        if v is not None:
-            if not v.strip():
-                raise ValueError("Token cannot be empty or whitespace-only")
-            if v.strip().startswith("Bearer "):
-                raise ValueError("Token should not include 'Bearer ' prefix")
-        return v
-
-    @model_validator(mode='after')
-    def validate_actor_token_type(self) -> 'CustomTokenExchangeOptions':
-        """Ensure actor_token_type is provided if actor_token is present."""
-        if self.actor_token and not self.actor_token_type:
-            raise ValueError("actor_token_type is required when actor_token is provided")
-        return self
-
 
 class TokenExchangeResponse(BaseModel):
     """
@@ -297,6 +284,7 @@ class TokenExchangeResponse(BaseModel):
         issued_token_type: Format of issued token
         id_token: OpenID Connect ID token (optional)
         refresh_token: Refresh token (optional)
+        act: Actor claim for delegation/impersonation exchanges (optional)
     """
     access_token: str
     token_type: str = "Bearer"
@@ -305,6 +293,7 @@ class TokenExchangeResponse(BaseModel):
     issued_token_type: Optional[str] = None
     id_token: Optional[str] = None
     refresh_token: Optional[str] = None
+    act: Optional[dict[str, Any]] = None
 
 
 class LoginWithCustomTokenExchangeOptions(BaseModel):
@@ -313,8 +302,8 @@ class LoginWithCustomTokenExchangeOptions(BaseModel):
 
     Combines token exchange parameters with session management.
     """
-    subject_token: str = Field(..., min_length=1)
-    subject_token_type: str = Field(..., min_length=1)
+    subject_token: str
+    subject_token_type: str
     audience: Optional[str] = None
     scope: Optional[str] = None
     actor_token: Optional[str] = None
@@ -322,24 +311,6 @@ class LoginWithCustomTokenExchangeOptions(BaseModel):
     organization: Optional[str] = None
     authorization_params: Optional[dict[str, Any]] = None
 
-    @field_validator('subject_token', 'actor_token')
-    @classmethod
-    def validate_token_format(cls, v: Optional[str]) -> Optional[str]:
-        """Validate token doesn't have Bearer prefix and isn't whitespace-only."""
-        if v is not None:
-            if not v.strip():
-                raise ValueError("Token cannot be empty or whitespace-only")
-            if v.strip().startswith("Bearer "):
-                raise ValueError("Token should not include 'Bearer ' prefix")
-        return v
-
-    @model_validator(mode='after')
-    def validate_actor_token_type(self) -> 'LoginWithCustomTokenExchangeOptions':
-        """Ensure actor_token_type is provided if actor_token is present."""
-        if self.actor_token and not self.actor_token_type:
-            raise ValueError("actor_token_type is required when actor_token is provided")
-        return self
-
 
 class LoginWithCustomTokenExchangeResult(BaseModel):
     """

{auth0_server_python-1.0.0b10 → auth0_server_python-1.0.0b11}/src/auth0_server_python/error/__init__.py

@@ -200,6 +200,18 @@ class AccessTokenErrorCode:
     DOMAIN_MISMATCH = "domain_mismatch"
 
 
+class OrganizationTokenValidationError(Auth0Error):
+    """
+    Raised when org_id or org_name claim in the ID token fails validation
+    against the organization value that was requested at login.
+    """
+    code = "organization_token_validation_error"
+
+    def __init__(self, message: str):
+        super().__init__(message)
+        self.name = "OrganizationTokenValidationError"
+
+
 class AccessTokenForConnectionErrorCode:
     """Error codes for connection-specific token operations."""
     MISSING_REFRESH_TOKEN = "missing_refresh_token"
@@ -225,6 +237,7 @@ class CustomTokenExchangeErrorCode:
     """Error codes for custom token exchange operations."""
     INVALID_TOKEN_FORMAT = "invalid_token_format"
     MISSING_ACTOR_TOKEN_TYPE = "missing_actor_token_type"
+    MISSING_ACTOR_TOKEN = "missing_actor_token"
     TOKEN_EXCHANGE_FAILED = "token_exchange_failed"
     INVALID_RESPONSE = "invalid_response"