osdu-python-client 0.4.1__py3-none-any.whl

osdu_python_client/auth/azure.py

@@ -0,0 +1,375 @@
+"""Azure / Entra ID token providers backed by MSAL."""
+
+from __future__ import annotations
+
+import logging
+import pathlib
+import threading
+import time
+from typing import TYPE_CHECKING, Any, Literal
+
+from pydantic import AliasChoices, Field, model_validator
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+from osdu_python_client.auth._base import (
+    TokenProvider,
+    register_provider,
+)
+from osdu_python_client.errors import OsduAuthError, OsduConfigError
+
+if TYPE_CHECKING:
+    from osdu_python_client.config import OsduConfig
+
+log = logging.getLogger(__name__)
+
+AzureAuthMode = Literal[
+    "interactive", "device_flow", "client_credentials", "workload_identity"
+]
+
+# MSAL adds these implicitly and rejects them in caller-supplied scope lists.
+_MSAL_RESERVED_SCOPES: frozenset[str] = frozenset(
+    {"openid", "profile", "offline_access"}
+)
+
+
+class AzureMsalConfig(BaseSettings):
+    """Azure-specific auth settings, loaded from the same ``.env`` as OsduConfig.
+
+    The env var names (``AUTHORITY``, ``SCOPES``, ``CLIENT_ID``, ``CLIENT_SECRET``,
+    ``AUTH_MODE``, ``MSAL_CACHE_PATH``) are unchanged from the pre-split layout.
+    For workload identity (``AUTH_MODE=workload_identity``), uses Azure-standard env vars:
+    - ``AZURE_TENANT_ID`` — tenant ID (required for workload identity)
+    - ``AZURE_CLIENT_ID`` or ``CLIENT_ID`` — client/application ID (with fallback)
+    - ``AZURE_FEDERATED_TOKEN_FILE`` — path to federated token file (required for workload identity)
+    """
+
+    authority: str | None = None
+    scopes: str
+    client_id: str | None = Field(
+        default=None,
+        validation_alias=AliasChoices("AZURE_CLIENT_ID", "CLIENT_ID"),
+    )
+    client_secret: str | None = None
+    auth_mode: AzureAuthMode = "interactive"
+    msal_cache_path: str = ".msal_token_cache.bin"
+    # Workload identity specific (using AliasChoices for environment variable flexibility)
+    tenant_id: str | None = Field(
+        default=None,
+        validation_alias=AliasChoices("AZURE_TENANT_ID", "TENANT_ID"),
+    )
+    federated_token_file: str | None = Field(
+        default=None,
+        validation_alias=AliasChoices("AZURE_FEDERATED_TOKEN_FILE"),
+    )
+
+    model_config = SettingsConfigDict(
+        env_file=".env",
+        env_file_encoding="utf-8",
+        extra="ignore",
+    )
+
+    @model_validator(mode="after")
+    def validate_auth_mode_requirements(self) -> AzureMsalConfig:
+        """Validate that all required fields are present for the chosen auth mode."""
+        if self.auth_mode == "workload_identity":
+            # Workload identity requires tenant_id, client_id, and federated_token_file
+            # Authority is not needed for workload identity
+            if not self.tenant_id:
+                raise OsduConfigError("workload_identity mode requires AZURE_TENANT_ID")
+            if not self.client_id:
+                raise OsduConfigError(
+                    "workload_identity mode requires AZURE_CLIENT_ID or CLIENT_ID"
+                )
+            if not self.federated_token_file:
+                raise OsduConfigError(
+                    "workload_identity mode requires AZURE_FEDERATED_TOKEN_FILE"
+                )
+        else:
+            # MSAL modes (interactive, device_flow, client_credentials) require authority
+            if not self.authority:
+                raise OsduConfigError(
+                    "MSAL modes (interactive, device_flow, client_credentials) require AUTHORITY"
+                )
+            if self.auth_mode == "client_credentials" and not self.client_secret:
+                raise OsduConfigError("client_credentials mode requires CLIENT_SECRET")
+        return self
+
+    @property
+    def scopes_list(self) -> list[str]:
+        raw = self.scopes.split()
+        filtered = [s for s in raw if s.lower() not in _MSAL_RESERVED_SCOPES]
+        dropped = [s for s in raw if s.lower() in _MSAL_RESERVED_SCOPES]
+        if dropped:
+            log.debug(
+                "ignoring MSAL-reserved scopes from config: %s (MSAL adds these itself)",
+                dropped,
+            )
+        return filtered
+
+
+_MSAL_INSTALL_HINT = (
+    "msal is required for Azure auth. "
+    "Install it with: pip install 'osdu-python-client[azure]'"
+)
+_WORKLOAD_IDENTITY_INSTALL_HINT = (
+    "azure-identity is required for workload identity auth. "
+    "Install it with: pip install 'osdu-python-client[azure]'"
+)
+
+
+def _load_cache(path: pathlib.Path) -> Any:
+    try:
+        from msal import SerializableTokenCache
+    except ImportError as exc:
+        raise OsduConfigError(_MSAL_INSTALL_HINT) from exc
+
+    cache = SerializableTokenCache()
+    if path.exists():
+        cache.deserialize(path.read_text(encoding="utf-8"))
+    return cache
+
+
+def _save_cache(cache: Any, path: pathlib.Path) -> None:
+    if cache.has_state_changed:
+        path.write_text(cache.serialize(), encoding="utf-8")
+
+
+class _MsalProviderBase:
+    def __init__(self, config: AzureMsalConfig) -> None:
+        self._config = config
+        self._lock = threading.Lock()
+        self._cache_path = pathlib.Path(config.msal_cache_path)
+        self._cache = _load_cache(self._cache_path)
+        self._app = self._build_app()
+
+    def _build_app(self) -> Any:  # pragma: no cover - subclasses override
+        raise NotImplementedError
+
+    def _persist(self) -> None:
+        _save_cache(self._cache, self._cache_path)
+
+    def _try_silent(self, force_refresh: bool) -> dict[str, Any] | None:
+        accounts = self._app.get_accounts()
+        if not accounts:
+            return None
+        return self._app.acquire_token_silent(
+            scopes=self._config.scopes_list,
+            account=accounts[0],
+            force_refresh=force_refresh,
+        )
+
+    def _extract_token(self, result: dict[str, Any] | None) -> str:
+        token = result.get("access_token") if isinstance(result, dict) else None
+        if not token:
+            raise OsduAuthError(f"Authentication failed: {result}")
+        return token
+
+
+class MsalInteractiveProvider(_MsalProviderBase):
+    def _build_app(self) -> Any:
+        try:
+            from msal import PublicClientApplication
+        except ImportError as exc:
+            raise OsduConfigError(_MSAL_INSTALL_HINT) from exc
+
+        return PublicClientApplication(
+            client_id=self._config.client_id,
+            authority=self._config.authority,
+            token_cache=self._cache,
+        )
+
+    def get_token(self, force_refresh: bool = False) -> str:
+        with self._lock:
+            result = self._try_silent(force_refresh=force_refresh)
+            if result and "access_token" in result:
+                log.debug("token acquired silently (force_refresh=%s)", force_refresh)
+            else:
+                log.info("interactive auth flow required")
+                result = self._app.acquire_token_interactive(
+                    scopes=self._config.scopes_list
+                )
+                log.debug("token acquired via interactive flow")
+            self._persist()
+            return self._extract_token(result)
+
+
+class MsalDeviceFlowProvider(_MsalProviderBase):
+    def __init__(
+        self,
+        config: AzureMsalConfig,
+        prompt_callback: Any | None = None,
+    ) -> None:
+        super().__init__(config)
+        self._prompt_callback = prompt_callback or (lambda flow: print(flow["message"]))
+
+    def _build_app(self) -> Any:
+        try:
+            from msal import PublicClientApplication
+        except ImportError as exc:
+            raise OsduConfigError(_MSAL_INSTALL_HINT) from exc
+
+        return PublicClientApplication(
+            client_id=self._config.client_id,
+            authority=self._config.authority,
+            token_cache=self._cache,
+        )
+
+    def get_token(self, force_refresh: bool = False) -> str:
+        with self._lock:
+            result = self._try_silent(force_refresh=force_refresh)
+            if result and "access_token" in result:
+                log.debug("token acquired silently (force_refresh=%s)", force_refresh)
+            else:
+                flow = self._app.initiate_device_flow(scopes=self._config.scopes_list)
+                if "user_code" not in flow:
+                    raise OsduAuthError(f"Device flow init failed: {flow}")
+                log.info("device flow initiated — awaiting user code entry")
+                self._prompt_callback(flow)
+                result = self._app.acquire_token_by_device_flow(flow)
+                log.debug("token acquired via device flow")
+            self._persist()
+            return self._extract_token(result)
+
+
+class ClientCredentialsProvider(_MsalProviderBase):
+    def __init__(self, config: AzureMsalConfig) -> None:
+        if not config.client_secret:
+            raise OsduConfigError(
+                "client_secret is required for client_credentials auth_mode"
+            )
+        super().__init__(config)
+
+    def _build_app(self) -> Any:
+        try:
+            from msal import ConfidentialClientApplication
+        except ImportError as exc:
+            raise OsduConfigError(_MSAL_INSTALL_HINT) from exc
+
+        return ConfidentialClientApplication(
+            client_id=self._config.client_id,
+            authority=self._config.authority,
+            client_credential=self._config.client_secret,
+            token_cache=self._cache,
+        )
+
+    def get_token(self, force_refresh: bool = False) -> str:
+        with self._lock:
+            result: dict[str, Any] | None = None
+            if not force_refresh:
+                result = self._app.acquire_token_silent(
+                    scopes=self._config.scopes_list, account=None
+                )
+            if result and "access_token" in result:
+                log.debug("client_credentials token acquired silently")
+            else:
+                log.debug(
+                    "client_credentials acquiring new token (force_refresh=%s)",
+                    force_refresh,
+                )
+                result = self._app.acquire_token_for_client(
+                    scopes=self._config.scopes_list
+                )
+            self._persist()
+            return self._extract_token(result)
+
+
+class WorkloadIdentityProvider:
+    """Azure Workload Identity provider using ``azure-identity`` SDK.
+
+    Uses ``WorkloadIdentityCredential`` to exchange a federated token (from
+    ``AZURE_FEDERATED_TOKEN_FILE``) for an access token, without user interaction.
+    Suitable for Kubernetes/AKS environments with Workload Identity federation.
+    """
+
+    def __init__(self, config: AzureMsalConfig) -> None:
+        self._config = config
+        self._lock = threading.Lock()
+        self._credential = self._build_credential()
+        self._cached_token: str | None = None
+        self._token_expiry: float | None = None
+        self._refresh_buffer_seconds = 300  # Refresh if token expires within this many seconds
+
+    def _build_credential(self) -> Any:
+        try:
+            from azure.identity import WorkloadIdentityCredential
+        except ImportError as exc:
+            raise OsduConfigError(_WORKLOAD_IDENTITY_INSTALL_HINT) from exc
+
+        return WorkloadIdentityCredential(
+            client_id=self._config.client_id,
+            tenant_id=self._config.tenant_id,
+            token_file=self._config.federated_token_file,
+        )
+
+    def _clear_cache(self) -> None:
+        """Clear cached token and credential state."""
+        self._cached_token = None
+        self._token_expiry = None
+        self._credential = self._build_credential()  # Rebuild credential to clear any internal state
+        log.debug("workload identity cache cleared")
+
+    def _token_refresh_required(self) -> bool:
+        """Determine if the cached token is missing or close to expiry."""
+        return (
+            self._cached_token is None
+            or self._token_expiry is None
+            or self._token_expiry - time.time() < self._refresh_buffer_seconds
+        )
+
+    def get_token(self, force_refresh: bool = False) -> str:
+        """Get or refresh access token using workload identity credential."""
+        with self._lock:
+            if force_refresh:
+                self._clear_cache()
+
+            if self._token_refresh_required():
+                log.debug(
+                    "acquiring workload identity token (force_refresh=%s)", force_refresh
+                )
+                try:
+                    scopes = self._config.scopes_list
+                    token_response = self._credential.get_token(*scopes)
+                    self._cached_token = token_response.token
+                    self._token_expiry = token_response.expires_on
+                    remaining = (
+                        max(0, int(self._token_expiry - time.time()))
+                        if self._token_expiry
+                        else 0
+                    )
+                    log.debug(
+                        "workload identity token acquired (expires in %d seconds)",
+                        remaining,
+                    )
+                except Exception as exc:
+                    msg = f"failed to acquire workload identity token: {exc}"
+                    log.error(msg)
+                    raise OsduAuthError(msg) from exc
+
+            if not self._cached_token:
+                raise OsduAuthError("failed to acquire workload identity token")
+
+            remaining = (
+                max(0, int(self._token_expiry - time.time()))
+                if self._token_expiry
+                else 0
+            )
+            log.debug("returning cached token (expires in %d seconds)", remaining)
+
+            return self._cached_token
+
+
+
+def _factory(_config: "OsduConfig") -> TokenProvider:
+    azure_config = AzureMsalConfig()
+    match azure_config.auth_mode:
+        case "interactive":
+            return MsalInteractiveProvider(azure_config)
+        case "device_flow":
+            return MsalDeviceFlowProvider(azure_config)
+        case "client_credentials":
+            return ClientCredentialsProvider(azure_config)
+        case "workload_identity":
+            return WorkloadIdentityProvider(azure_config)
+
+
+register_provider("azure_msal", _factory)

osdu_python_client/auth/ci.py

@@ -0,0 +1,105 @@
+"""Community Implementation (CI / baremetal) auth provider.
+
+OSDU Community / baremetal deployments authenticate via Keycloak using
+OAuth2 client credentials. The response ``id_token`` is used as the bearer
+token (not the ``access_token``). No extra dependencies are required beyond
+the core package.
+
+Required environment variables (or .env entries):
+
+    CI_KEYCLOAK_AUTH_URL  — full token endpoint URL
+                            (e.g. https://keycloak.example.com/auth/realms/<realm>/protocol/openid-connect/token)
+    CI_CLIENT_ID          — OAuth2 client ID
+    CI_CLIENT_SECRET      — OAuth2 client secret
+    CI_SCOPES             — space-separated scopes (optional; defaults to "openid")
+"""
+
+from __future__ import annotations
+
+import logging
+import threading
+import time
+from typing import TYPE_CHECKING
+
+import httpx
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+from osdu_python_client.auth._base import TokenProvider, register_provider
+from osdu_python_client.errors import OsduAuthError
+
+if TYPE_CHECKING:
+    from osdu_python_client.config import OsduConfig
+
+log = logging.getLogger(__name__)
+
+
+class CiConfig(BaseSettings):
+    """Community Implementation auth settings, loaded from the same ``.env`` as OsduConfig."""
+
+    ci_keycloak_auth_url: str
+    ci_client_id: str
+    ci_client_secret: str
+    ci_scopes: str = "openid"
+
+    model_config = SettingsConfigDict(
+        env_file=".env",
+        env_file_encoding="utf-8",
+        extra="ignore",
+    )
+
+    @property
+    def scopes_list(self) -> list[str]:
+        return self.ci_scopes.split() if self.ci_scopes.strip() else ["openid"]
+
+
+class CiKeycloakProvider:
+    """Token provider for OSDU Community / baremetal using Keycloak client credentials."""
+
+    def __init__(self, config: CiConfig) -> None:
+        self._config = config
+        self._lock = threading.Lock()
+        self._token: str | None = None
+        self._expires_at: float = 0.0
+
+    def get_token(self, force_refresh: bool = False) -> str:
+        with self._lock:
+            if force_refresh or self._token is None or time.monotonic() >= self._expires_at:
+                self._fetch()
+            return self._token  # type: ignore[return-value]
+
+    def _fetch(self) -> None:
+        cfg = self._config
+        data = {
+            "grant_type": "client_credentials",
+            "scope": " ".join(cfg.scopes_list),
+            "client_id": cfg.ci_client_id,
+            "client_secret": cfg.ci_client_secret,
+        }
+        log.debug("acquiring CI token from %s", cfg.ci_keycloak_auth_url)
+        response = httpx.post(
+            cfg.ci_keycloak_auth_url,
+            headers={"Content-Type": "application/x-www-form-urlencoded"},
+            data=data,
+            timeout=30,
+        )
+        if response.status_code != 200:
+            raise OsduAuthError(
+                f"CI token request failed [{response.status_code}]: {response.text}"
+            )
+        payload = response.json()
+        # Baremetal OSDU uses the id_token as the bearer token
+        token = payload.get("id_token") or payload.get("access_token")
+        if not token:
+            raise OsduAuthError(f"CI token response missing id_token/access_token: {payload}")
+
+        expires_in = int(payload.get("expires_in", 300))
+        self._token = token
+        self._expires_at = time.monotonic() + expires_in - 30  # 30s early-refresh buffer
+        log.debug("CI token acquired, expires in %ds", expires_in)
+
+
+def _factory(_config: "OsduConfig") -> TokenProvider:
+    return CiKeycloakProvider(CiConfig())
+
+
+register_provider("community", _factory)

osdu_python_client/auth/gcp.py

@@ -0,0 +1,103 @@
+"""GCP auth provider using google-auth.
+
+OSDU-on-GCP deployments authenticate via Google Cloud service accounts or
+Application Default Credentials (ADC). Requires ``google-auth[requests]``;
+install with ``pip install 'osdu-python-client[gcp]'``.
+
+Required environment variables (or .env entries):
+
+    GCP_SA_FILE_PATH  — path to a service account JSON key file (optional;
+                        omit to use Application Default Credentials)
+    GCP_USE_ID_TOKEN  — set to "true" to return an ID token instead of an
+                        access token (some OSDU-on-GCP deployments require this)
+    GCP_SCOPES        — space-separated scopes (optional; defaults to
+                        "openid email profile")
+"""
+
+from __future__ import annotations
+
+import logging
+import threading
+from typing import TYPE_CHECKING
+
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+from osdu_python_client.auth._base import TokenProvider, register_provider
+from osdu_python_client.errors import OsduAuthError, OsduConfigError
+
+if TYPE_CHECKING:
+    from osdu_python_client.config import OsduConfig
+
+log = logging.getLogger(__name__)
+
+_DEFAULT_SCOPES = ["openid", "email", "profile"]
+
+
+class GcpConfig(BaseSettings):
+    """GCP auth settings, loaded from the same ``.env`` as OsduConfig."""
+
+    gcp_sa_file_path: str | None = None
+    gcp_use_id_token: bool = False
+    gcp_scopes: str = ""
+
+    model_config = SettingsConfigDict(
+        env_file=".env",
+        env_file_encoding="utf-8",
+        extra="ignore",
+    )
+
+    @property
+    def scopes_list(self) -> list[str]:
+        raw = self.gcp_scopes.strip()
+        return raw.split() if raw else _DEFAULT_SCOPES
+
+
+class GcpTokenProvider:
+    """Token provider for OSDU-on-GCP using google-auth."""
+
+    def __init__(self, config: GcpConfig) -> None:
+        self._config = config
+        self._lock = threading.Lock()
+
+    def get_token(self, force_refresh: bool = False) -> str:
+        with self._lock:
+            try:
+                import google.auth
+                from google.auth.transport.requests import Request
+            except ImportError as exc:
+                raise OsduConfigError(
+                    "google-auth is required for GCP auth. "
+                    "Install it with: pip install 'osdu-python-client[gcp]'"
+                ) from exc
+
+            if self._config.gcp_sa_file_path:
+                from google.oauth2 import service_account
+
+                log.debug("loading GCP credentials from SA file: %s", self._config.gcp_sa_file_path)
+                credentials = service_account.Credentials.from_service_account_file(
+                    self._config.gcp_sa_file_path,
+                    scopes=self._config.scopes_list,
+                )
+            else:
+                log.debug("loading GCP Application Default Credentials")
+                credentials, _ = google.auth.default(scopes=self._config.scopes_list)
+
+            credentials.refresh(Request())
+
+            if self._config.gcp_use_id_token and hasattr(credentials, "id_token"):
+                token = credentials.id_token
+                log.debug("GCP ID token acquired")
+            else:
+                token = credentials.token
+                log.debug("GCP access token acquired")
+
+            if not token:
+                raise OsduAuthError("GCP credential refresh returned an empty token")
+            return token
+
+
+def _factory(_config: "OsduConfig") -> TokenProvider:
+    return GcpTokenProvider(GcpConfig())
+
+
+register_provider("gcp_iam", _factory)

osdu_python_client/auth/ibm.py

@@ -0,0 +1,102 @@
+"""IBM auth provider using Keycloak OIDC (Resource Owner Password Credentials).
+
+OSDU-on-IBM deployments authenticate via a Keycloak server. Requires
+``python-keycloak``; install with ``pip install 'osdu-python-client[ibm]'``.
+
+Required environment variables (or .env entries):
+
+    IBM_KEYCLOAK_URI    — Keycloak server URL (e.g. https://keycloak.example.com/auth/)
+    IBM_REALM_NAME      — Keycloak realm name
+    IBM_CLIENT_ID       — Keycloak client ID
+    IBM_CLIENT_SECRET   — Keycloak client secret
+    IBM_USERNAME        — user login
+    IBM_PASSWORD        — user password
+    IBM_VERIFY_SSL      — set to "false" to disable SSL verification (default: true)
+"""
+
+from __future__ import annotations
+
+import logging
+import threading
+import time
+from typing import TYPE_CHECKING
+
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+from osdu_python_client.auth._base import TokenProvider, register_provider
+from osdu_python_client.errors import OsduAuthError, OsduConfigError
+
+if TYPE_CHECKING:
+    from osdu_python_client.config import OsduConfig
+
+log = logging.getLogger(__name__)
+
+
+class IbmConfig(BaseSettings):
+    """IBM/Keycloak auth settings, loaded from the same ``.env`` as OsduConfig."""
+
+    ibm_keycloak_uri: str
+    ibm_realm_name: str
+    ibm_client_id: str
+    ibm_client_secret: str
+    ibm_username: str
+    ibm_password: str
+    ibm_verify_ssl: bool = True
+
+    model_config = SettingsConfigDict(
+        env_file=".env",
+        env_file_encoding="utf-8",
+        extra="ignore",
+    )
+
+
+class IbmKeycloakProvider:
+    """Token provider for OSDU-on-IBM using Keycloak OIDC."""
+
+    def __init__(self, config: IbmConfig) -> None:
+        self._config = config
+        self._lock = threading.Lock()
+        self._token: str | None = None
+        self._expires_at: float = 0.0
+
+    def get_token(self, force_refresh: bool = False) -> str:
+        with self._lock:
+            if force_refresh or self._token is None or time.monotonic() >= self._expires_at:
+                self._fetch()
+            return self._token  # type: ignore[return-value]
+
+    def _fetch(self) -> None:
+        try:
+            from keycloak import KeycloakOpenID
+        except ImportError as exc:
+            raise OsduConfigError(
+                "python-keycloak is required for IBM auth. "
+                "Install it with: pip install 'osdu-python-client[ibm]'"
+            ) from exc
+
+        cfg = self._config
+        log.debug("acquiring IBM token from %s realm=%s", cfg.ibm_keycloak_uri, cfg.ibm_realm_name)
+        kc = KeycloakOpenID(
+            server_url=cfg.ibm_keycloak_uri,
+            realm_name=cfg.ibm_realm_name,
+            client_id=cfg.ibm_client_id,
+            client_secret_key=cfg.ibm_client_secret,
+            verify=cfg.ibm_verify_ssl,
+        )
+        token_response = kc.token(cfg.ibm_username, cfg.ibm_password)
+        refreshed = kc.refresh_token(token_response["refresh_token"])
+        token = refreshed.get("access_token")
+        if not token:
+            raise OsduAuthError(f"IBM Keycloak token refresh returned no access_token: {refreshed}")
+
+        expires_in = int(refreshed.get("expires_in", 300))
+        self._token = token
+        self._expires_at = time.monotonic() + expires_in - 30  # 30s early-refresh buffer
+        log.debug("IBM token acquired, expires in %ds", expires_in)
+
+
+def _factory(_config: "OsduConfig") -> TokenProvider:
+    return IbmKeycloakProvider(IbmConfig())
+
+
+register_provider("ibm_iam", _factory)