dynamics-client-gh 0.1.2__py3-none-any.whl

dynamics_client/__init__.py

@@ -0,0 +1,8 @@
+from .base_client import BaseClient
+from .dataverse_client import DataverseClient
+from .token_manager import TokenManager
+from .certificate_token_manager import CertificateTokenManager
+from .exceptions import TokenAcquisitionError
+
+
+__all__ = ["BaseClient", "DataverseClient", "TokenManager", "TokenAcquisitionError", "CertificateTokenManager"]

dynamics_client/base_client.py

@@ -0,0 +1,8 @@
+from typing import Protocol
+
+class BaseClient(Protocol):
+    def __init__(self, *args, **kwargs):
+        ...
+
+    def read(self):
+        ...

dynamics_client/base_token_manager.py

@@ -0,0 +1,23 @@
+from abc import ABC
+import time
+
+
+class BaseTokenManager(ABC):
+    def __init__(self, *args, **kwargs):
+        ...
+
+    def get_headers(self) -> dict:
+        return {
+            "Authorization": f"Bearer {self.get_token()}",
+            "Accept": "application/json",
+            "OData-MaxVersion": "4.0",
+            "OData-Version": "4.0",
+            "Content-Type": "application/json; charset=utf-8",
+        }
+
+    def get_token(self) -> str:
+        with self._lock:
+            if self._access_token and time.time() < self._expires_at - 60:
+                return self._access_token
+            self._fetch_token()
+            return self._access_token

dynamics_client/certificate_token_manager.py

@@ -0,0 +1,144 @@
+import base64
+import binascii
+import threading
+
+from azure.core.exceptions import ClientAuthenticationError, HttpResponseError, ResourceNotFoundError
+from azure.identity import CertificateCredential, DefaultAzureCredential
+from azure.keyvault.secrets import SecretClient
+from .base_token_manager import BaseTokenManager
+from .exceptions import CertificateAuthError
+
+
+class CertificateTokenManager(BaseTokenManager):
+    """
+    TokenManager-compatible class that authenticates to Dataverse using a
+    certificate pulled from Azure Key Vault, instead of a client secret.
+
+    The certificate's private key material is stored in Key Vault as the
+    secret linked to the certificate (standard Key Vault behavior), so it
+    is fetched via SecretClient and handed to CertificateCredential.
+    """
+
+    def __init__(
+        self,
+        tenant_id: str,
+        client_id: str,
+        dataverse_url: str,
+        key_vault_url: str,
+        certificate_secret_name: str,
+        managed_identity_client_id: str = None,
+    ):
+        for name, value in (
+            ("tenant_id", tenant_id),
+            ("client_id", client_id),
+            ("dataverse_url", dataverse_url),
+            ("key_vault_url", key_vault_url),
+            ("certificate_secret_name", certificate_secret_name),
+        ):
+            if not value:
+                raise ValueError(f"'{name}' is required and cannot be empty")
+
+        self.tenant_id = tenant_id
+        self.client_id = client_id
+        self.dataverse_url = dataverse_url.rstrip("/")
+        self.key_vault_url = key_vault_url
+        self.certificate_secret_name = certificate_secret_name
+        self.managed_identity_client_id = managed_identity_client_id
+
+        self._access_token = None
+        self._expires_at = 0
+        self._lock = threading.Lock()
+        self._credential = None  # lazily built CertificateCredential
+
+    def _fetch_certificate_secret(self):
+        kv_credential_kwargs = {}
+        if self.managed_identity_client_id:
+            kv_credential_kwargs["managed_identity_client_id"] = self.managed_identity_client_id
+
+        try:
+            # DefaultAzureCredential uses the Function App's managed identity in
+            # Azure, and falls back to local dev credentials (e.g. Azure CLI)
+            # when running locally.
+            key_vault_credential = DefaultAzureCredential(**kv_credential_kwargs)
+            secret_client = SecretClient(vault_url=self.key_vault_url, credential=key_vault_credential)
+            return secret_client.get_secret(self.certificate_secret_name)
+        except ResourceNotFoundError as e:
+            raise CertificateAuthError(
+                f"Certificate secret '{self.certificate_secret_name}' was not found in Key Vault "
+                f"'{self.key_vault_url}': {e}"
+            ) from e
+        except ClientAuthenticationError as e:
+            raise CertificateAuthError(
+                f"Failed to authenticate to Key Vault '{self.key_vault_url}' using the managed "
+                f"identity/local credential: {e}"
+            ) from e
+        except HttpResponseError as e:
+            raise CertificateAuthError(
+                f"Key Vault request for secret '{self.certificate_secret_name}' failed: {e}"
+            ) from e
+        except CertificateAuthError:
+            raise
+        except Exception as e:
+            raise CertificateAuthError(
+                f"Unexpected error retrieving certificate secret '{self.certificate_secret_name}' "
+                f"from Key Vault '{self.key_vault_url}': {e}"
+            ) from e
+
+    def _load_certificate_credential(self) -> CertificateCredential:
+        certificate_secret = self._fetch_certificate_secret()
+
+        if not certificate_secret or not certificate_secret.value:
+            raise CertificateAuthError(
+                f"Certificate secret '{self.certificate_secret_name}' in Key Vault "
+                f"'{self.key_vault_url}' has no value"
+            )
+
+        try:
+            pfx_bytes = base64.b64decode(certificate_secret.value, validate=True)
+        except (binascii.Error, ValueError) as e:
+            raise CertificateAuthError(
+                f"Certificate secret '{self.certificate_secret_name}' is not valid base64-encoded "
+                f"PFX data: {e}"
+            ) from e
+
+        if not pfx_bytes:
+            raise CertificateAuthError(
+                f"Certificate secret '{self.certificate_secret_name}' decoded to empty PFX data"
+            )
+
+        try:
+            return CertificateCredential(
+                tenant_id=self.tenant_id,
+                client_id=self.client_id,
+                certificate_data=pfx_bytes,
+            )
+        except ValueError as e:
+            raise CertificateAuthError(
+                f"Certificate secret '{self.certificate_secret_name}' could not be loaded as a valid "
+                f"certificate/private key: {e}"
+            ) from e
+
+    def _fetch_token(self):
+        try:
+            if self._credential is None:
+                self._credential = self._load_certificate_credential()
+            token = self._credential.get_token(f"{self.dataverse_url}/.default")
+        except CertificateAuthError:
+            # Reset so a subsequent call can retry credential creation instead of
+            # being stuck with a half-initialized state.
+            self._credential = None
+            raise
+        except ClientAuthenticationError as e:
+            self._credential = None
+            raise CertificateAuthError(
+                f"Failed to acquire a Dataverse access token for '{self.dataverse_url}' using the "
+                f"certificate credential: {e}"
+            ) from e
+        except Exception as e:
+            self._credential = None
+            raise CertificateAuthError(
+                f"Unexpected error acquiring Dataverse access token for '{self.dataverse_url}': {e}"
+            ) from e
+
+        self._access_token = token.token
+        self._expires_at = token.expires_on

dynamics_client/dataverse_client.py

@@ -0,0 +1,103 @@
+# dynamics_auth/dataverse_client.py
+import requests
+
+from .token_manager import TokenManager
+from .certificate_token_manager import CertificateTokenManager
+
+
+class DataverseError(Exception):
+    """Raised when a Dataverse API call fails."""
+    pass
+
+
+class DataverseClient:
+    def __init__(self, token_manager: TokenManager, base_url: str, api_version: str = "v9.2", timeout: int = 30):
+        self.token_manager = token_manager
+        self.base_url = base_url.rstrip("/")
+        self.api_version = api_version
+        self.timeout = timeout
+
+    @classmethod
+    def with_certificate_auth(
+        cls,
+        tenant_id: str,
+        client_id: str,
+        base_url: str,
+        key_vault_url: str,
+        certificate_secret_name: str,
+        managed_identity_client_id: str = None,
+        api_version: str = "v9.2",
+        timeout: int = 30,
+    ) -> "DataverseClient":
+        """
+        Convenience constructor that wires up certificate-based auth via
+        Azure Key Vault instead of the existing secret-based TokenManager.
+
+        Example:
+            client = DataverseClient.with_certificate_auth(
+                tenant_id=os.environ["ENTRA_TENANT_ID"],
+                client_id=os.environ["DATAVERSE_CLIENT_ID"],
+                base_url=os.environ["DATAVERSE_URL"],
+                key_vault_url=os.environ["KEY_VAULT_URL"],
+                certificate_secret_name=os.environ["DATAVERSE_CERTIFICATE_SECRET_NAME"],
+            )
+        """
+        token_manager = CertificateTokenManager(
+            tenant_id=tenant_id,
+            client_id=client_id,
+            dataverse_url=base_url,
+            key_vault_url=key_vault_url,
+            certificate_secret_name=certificate_secret_name,
+            managed_identity_client_id=managed_identity_client_id,
+        )
+        return cls(token_manager=token_manager, base_url=base_url, api_version=api_version, timeout=timeout)
+
+    @property
+    def _api_url(self) -> str:
+        return f"{self.base_url}/api/data/{self.api_version}"
+
+    def _headers(self, extra: dict = None) -> dict:
+        headers = self.token_manager.get_headers()
+        if extra:
+            headers.update(extra)
+        return headers
+
+    def _request(self, method: str, path: str, **kwargs) -> requests.Response:
+        url = f"{self._api_url}/{path.lstrip('/')}"
+        headers = self._headers(kwargs.pop("headers", None))
+
+        try:
+            resp = requests.request(method, url, headers=headers, timeout=self.timeout, **kwargs)
+            resp.raise_for_status()
+        except requests.RequestException as e:
+            raise DataverseError(f"{method} {url} failed: {e}") from e
+        return resp
+
+    # --- generic CRUD ---
+
+    def get(self, entity_set: str, entity_id: str = None, query: str = "") -> dict:
+        path = f"{entity_set}({entity_id})" if entity_id else entity_set
+        if query:
+            path += f"?{query}"
+        resp = self._request("GET", path)
+        return resp.json()
+
+    def get_list(self, entity_set: str, query: str = "") -> list:
+        data = self.get(entity_set, query=query)
+        return data.get("value", [])
+
+    def create(self, entity_set: str, payload: dict) -> str:
+        resp = self._request("POST", entity_set, json=payload)
+        # Dataverse returns the new record's URL in this header
+        return resp.headers.get("OData-EntityId")
+
+    def update(self, entity_set: str, entity_id: str, payload: dict) -> None:
+        self._request(
+            "PATCH",
+            f"{entity_set}({entity_id})",
+            json=payload,
+            headers={"If-Match": "*"},
+        )
+
+    def delete(self, entity_set: str, entity_id: str) -> None:
+        self._request("DELETE", f"{entity_set}({entity_id})")

dynamics_client/exceptions.py

@@ -0,0 +1,7 @@
+class TokenAcquisitionError(Exception):
+    """Raised when the OAuth token request fails."""
+    pass
+
+class CertificateAuthError(Exception):
+    """Raised when certificate-based authentication to Dataverse via Key Vault fails."""
+    pass

dynamics_client/token_manager.py

@@ -0,0 +1,65 @@
+import threading
+import requests
+
+from .exceptions import TokenAcquisitionError
+from .base_token_manager import BaseTokenManager
+
+class TokenManager(BaseTokenManager):
+    def __init__(self, tenant_id: str, client_id: str, client_secret: str, resource: str, timeout: int = 10):
+        self.tenant_id = tenant_id
+        self.client_id = client_id
+        self.client_secret = client_secret
+        self.resource = resource
+        self.timeout = timeout
+
+        self._access_token = None
+        self._expires_at = 0
+        self._lock = threading.Lock()
+
+    def _fetch_token(self):
+        try:
+            resp = requests.post(
+                f"https://login.microsoftonline.com/{self.tenant_id}/oauth2/token",
+                data={
+                    "grant_type": "client_credentials",
+                    "client_id": self.client_id,
+                    "client_secret": self.client_secret,
+                    "resource": self.resource,
+                },
+                timeout=self.timeout,
+            )
+            resp.raise_for_status()
+        except requests.RequestException as e:
+            raise TokenAcquisitionError(f"Failed to acquire token: {e}") from e
+
+        try:
+            data = resp.json()
+        except ValueError as e:
+            raise TokenAcquisitionError(f"Token endpoint returned a non-JSON response: {e}") from e
+
+        if not isinstance(data, dict):
+            raise TokenAcquisitionError(
+                f"Token endpoint returned an unexpected payload type: {type(data).__name__}"
+            )
+
+        access_token = data.get("access_token")
+        expires_on = data.get("expires_on")
+
+        if not access_token:
+            raise TokenAcquisitionError(
+                f"Token response is missing 'access_token': {data}"
+            )
+        if expires_on is None:
+            raise TokenAcquisitionError(
+                f"Token response is missing 'expires_on': {data}"
+            )
+
+        try:
+            expires_on = int(expires_on)
+        except (TypeError, ValueError) as e:
+            raise TokenAcquisitionError(
+                f"Token response has a non-integer 'expires_on' value ({expires_on!r}): {e}"
+            ) from e
+
+        self._access_token = access_token
+        self._expires_at = expires_on

dynamics_client_gh-0.1.2.dist-info/METADATA

@@ -0,0 +1,51 @@
+Metadata-Version: 2.5
+Name: dynamics-client-gh
+Version: 0.1.2
+Summary: Client library to easaly work within the ms dynamics universe
+Author-email: PommereningMartin <m.pommerening@gruenhorn.de>, MichaelWehling <m.wehling@gruenhorn.de>
+Requires-Python: >=3.11
+Requires-Dist: azure-identity
+Requires-Dist: azure-keyvault-secrets
+Requires-Dist: pytest>=9.1.1
+Requires-Dist: requests>=2.34.2
+Description-Content-Type: text/markdown
+
+# dynamics-client-gh
+
+Simple, thread-safe OAuth2 client-credentials authentication and a lightweight Dataverse (Microsoft Dynamics 365) OData client for Python.
+
+## Features
+
+- `TokenManager` — acquires and caches Azure AD access tokens automatically.
+- `DataverseClient` — thin wrapper around the Dataverse Web API with `get`, `get_list`, `create`, `update`, `delete`.
+- Thread-safe, minimal dependencies (`requests` only).
+
+## Installation
+
+pip install dynamics-client-pukna
+
+## Requirements
+
+- Python 3.8+
+- Azure AD App Registration with a client secret
+- A Dataverse Application User linked to that app, with a security role assigned
+
+## Quick Start
+
+from dynamics_client import TokenManager
+from dynamics_client.dataverse_client import DataverseClient
+
+token_manager = TokenManager(
+tenant_id="...", client_id="...", client_secret="...",
+resource="https://yourorg.crm.dynamics.com",
+)
+
+client = DataverseClient(token_manager=token_manager, base_url="https://yourorg.crm.dynamics.com")
+
+accounts = client.get_list("accounts", query="$select=name&$top=5")
+
+See the [full documentation](https://github.com/yourname/dynamics-auth#readme) for the API reference, error handling, and building custom entity services.
+
+## License
+
+MIT

dynamics_client_gh-0.1.2.dist-info/RECORD

@@ -0,0 +1,11 @@
+dynamics_client/__init__.py,sha256=6R3nE70mjkZcZ0WIVVxc0ITt1cp-eha_Nzg1SG0g9zQ,351
+dynamics_client/base_client.py,sha256=fGWoJM7mJg5mM_Jhjj1PFQqcq-nqzFKsxMA7uHCsWuQ,149
+dynamics_client/base_token_manager.py,sha256=sPWOGUaPb5lFMgqjSyULjb21OfFHAiXr6IQrXY6u1vo,684
+dynamics_client/certificate_token_manager.py,sha256=8wRQ70rqZ6foFGCqEB86ZG6g2CBzZVhjHjQAQExL7QY,6137
+dynamics_client/dataverse_client.py,sha256=a5maUfv-dx04rrnct3CuaHetB9GVNNcUQ2SryFhcmeI,3837
+dynamics_client/exceptions.py,sha256=uMy9PnP2mCiN5ktO40RQL5G4_mOdULNQEFjHTfFtpWE,245
+dynamics_client/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+dynamics_client/token_manager.py,sha256=L-Z0VPK_ZKgZ7nCJ8YyMBkzCzj3RC09tWJEzWTIQwiQ,2345
+dynamics_client_gh-0.1.2.dist-info/METADATA,sha256=cIy0xs8FhqITYNXbHkL1PjSU9OH4e3g00l14hWPstoQ,1665
+dynamics_client_gh-0.1.2.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+dynamics_client_gh-0.1.2.dist-info/RECORD,,

dynamics_client_gh-0.1.2.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any