libre-devops-helpers 0.4.1__py3-none-any.whl

libre_devops_helpers/microsoft/auth/entra.py

@@ -0,0 +1,241 @@
+"""Tokens for an app registration, straight from the Entra ID token endpoint.
+
+Two client credential flows, for automation that has no Azure CLI sign-in:
+
+- ``ClientSecretCredential``: a client secret, read from the environment by the caller.
+- ``WorkloadIdentityCredential``: a federated token (OIDC) exchanged for an access
+  token, so no secret exists at all. The federated token comes from a file (AKS and
+  most CI systems) or from the GitHub Actions OIDC endpoint.
+
+Secrets and assertions are sent in the form body only and never logged or repr'd.
+"""
+
+from __future__ import annotations
+
+import time
+from collections.abc import Callable, Mapping
+from datetime import datetime, timedelta
+from pathlib import Path
+from typing import Any
+
+import requests
+
+from libre_devops_helpers.core.auth import AccessToken, utc_now
+from libre_devops_helpers.core.errors import ApiError, AuthError
+from libre_devops_helpers.core.http import ApiClient
+from libre_devops_helpers.microsoft.clouds import PUBLIC
+
+ASSERTION_TYPE = "urn:ietf:params:oauth:client-assertion-type:jwt-bearer"
+# The audience Entra ID expects on a federated token.
+EXCHANGE_AUDIENCE = "api://AzureADTokenExchange"
+
+
+def scope_for(resource: str) -> str:
+    """The v2 ``.default`` scope for a v1 resource URL."""
+    return resource.rstrip("/") + "/.default"
+
+
+class _TokenEndpoint:
+    """POSTs a client credential grant to ``{login_url}/{tenant}/oauth2/v2.0/token``."""
+
+    def __init__(
+        self,
+        login_url: str,
+        *,
+        name: str,
+        session: requests.Session | None,
+        verify: bool | str,
+        clock: Callable[[], datetime],
+        sleep: Callable[[float], None],
+    ) -> None:
+        self._api = ApiClient(
+            login_url, None, name=name, session=session, verify=verify, sleep=sleep
+        )
+        self._name = name
+        self._clock = clock
+
+    def token(self, resource: str, tenant_id: str, form: Mapping[str, str]) -> AccessToken:
+        now = self._clock()
+        try:
+            data = self._api.request(
+                "POST",
+                f"/{tenant_id}/oauth2/v2.0/token",
+                form={**form, "grant_type": "client_credentials", "scope": scope_for(resource)},
+            )
+        except ApiError as exc:
+            raise AuthError(str(exc), hint=_hint(exc)) from None
+        return parse_token_response(data, resource, tenant_id, now=now, name=self._name)
+
+
+def parse_token_response(
+    data: Mapping[str, Any], resource: str, tenant_id: str, *, now: datetime, name: str
+) -> AccessToken:
+    """An AccessToken from an OAuth token response (``expires_in`` or ``expires_on``)."""
+    token = data.get("access_token")
+    if not isinstance(token, str) or not token:
+        raise AuthError(f"{name}: the token response has no access_token")
+    expires_in = _number(data.get("expires_in"))
+    expires_on = _number(data.get("expires_on"))
+    if expires_in is not None:
+        expiry = now + timedelta(seconds=expires_in)
+    elif expires_on is not None:
+        expiry = datetime.fromtimestamp(expires_on, now.tzinfo)
+    else:
+        raise AuthError(f"{name}: the token response has no expiry")
+    return AccessToken(token=token, expires_on=expiry, tenant_id=tenant_id, resource=resource)
+
+
+class ClientSecretCredential:
+    """A token provider for an app registration authenticating with a client secret."""
+
+    def __init__(
+        self,
+        client_id: str,
+        client_secret: str,
+        *,
+        login_url: str = PUBLIC.login_url,
+        session: requests.Session | None = None,
+        verify: bool | str = True,
+        clock: Callable[[], datetime] = utc_now,
+        sleep: Callable[[float], None] = time.sleep,
+    ) -> None:
+        if not client_secret:
+            raise AuthError("the client secret is empty")
+        self.client_id = client_id
+        self._secret = client_secret
+        self._endpoint = _TokenEndpoint(
+            login_url,
+            name="Entra ID token endpoint",
+            session=session,
+            verify=verify,
+            clock=clock,
+            sleep=sleep,
+        )
+
+    def __repr__(self) -> str:
+        return f"ClientSecretCredential(client_id={self.client_id!r})"
+
+    def get_token(self, resource: str, tenant_id: str) -> AccessToken:
+        return self._endpoint.token(
+            resource, tenant_id, {"client_id": self.client_id, "client_secret": self._secret}
+        )
+
+
+class WorkloadIdentityCredential:
+    """A token provider that exchanges a federated token for an access token.
+
+    ``assertion`` is called for every token request, because federated tokens are
+    short-lived and rotated by whatever issues them.
+    """
+
+    def __init__(
+        self,
+        client_id: str,
+        assertion: Callable[[], str],
+        *,
+        login_url: str = PUBLIC.login_url,
+        session: requests.Session | None = None,
+        verify: bool | str = True,
+        clock: Callable[[], datetime] = utc_now,
+        sleep: Callable[[float], None] = time.sleep,
+    ) -> None:
+        self.client_id = client_id
+        self._assertion = assertion
+        self._endpoint = _TokenEndpoint(
+            login_url,
+            name="Entra ID token endpoint",
+            session=session,
+            verify=verify,
+            clock=clock,
+            sleep=sleep,
+        )
+
+    def __repr__(self) -> str:
+        return f"WorkloadIdentityCredential(client_id={self.client_id!r})"
+
+    def get_token(self, resource: str, tenant_id: str) -> AccessToken:
+        return self._endpoint.token(
+            resource,
+            tenant_id,
+            {
+                "client_id": self.client_id,
+                "client_assertion_type": ASSERTION_TYPE,
+                "client_assertion": self._assertion(),
+            },
+        )
+
+
+def federated_token_file(path: Path) -> Callable[[], str]:
+    """An assertion source that re-reads ``path`` each time (the file is rotated)."""
+
+    def read() -> str:
+        try:
+            value = path.read_text(encoding="utf-8").strip()
+        except OSError as exc:
+            raise AuthError(f"cannot read the federated token file {path}: {exc}") from None
+        if not value:
+            raise AuthError(f"the federated token file {path} is empty")
+        return value
+
+    return read
+
+
+def github_actions_assertion(
+    request_url: str,
+    request_token: str,
+    *,
+    audience: str = EXCHANGE_AUDIENCE,
+    session: requests.Session | None = None,
+    verify: bool | str = True,
+    sleep: Callable[[float], None] = time.sleep,
+) -> Callable[[], str]:
+    """An assertion source that asks the GitHub Actions OIDC endpoint for an ID token.
+
+    ``request_url`` and ``request_token`` are the runner's ``ACTIONS_ID_TOKEN_REQUEST_URL``
+    and ``ACTIONS_ID_TOKEN_REQUEST_TOKEN``; the job needs ``permissions: id-token: write``.
+    """
+    api = ApiClient(
+        request_url,
+        lambda: request_token,
+        name="GitHub Actions OIDC",
+        session=session,
+        verify=verify,
+        sleep=sleep,
+    )
+
+    def fetch() -> str:
+        try:
+            data = api.get(request_url, params={"audience": audience})
+        except ApiError as exc:
+            raise AuthError(
+                str(exc), hint="the workflow job needs 'permissions: id-token: write'"
+            ) from None
+        value = data.get("value")
+        if not isinstance(value, str) or not value:
+            raise AuthError("GitHub Actions OIDC: the response has no token value")
+        return value
+
+    return fetch
+
+
+def _number(value: object) -> float | None:
+    if isinstance(value, bool):
+        return None
+    if isinstance(value, int | float):
+        return float(value)
+    if isinstance(value, str) and value.strip().isdigit():
+        return float(value.strip())
+    return None
+
+
+def _hint(exc: ApiError) -> str | None:
+    text = str(exc)
+    if "AADSTS7000215" in text or "AADSTS7000222" in text:
+        return "the client secret is wrong or expired; check AZURE_CLIENT_SECRET"
+    if "AADSTS700016" in text:
+        return "no app with this client_id exists in the tenant; check the profile's client_id"
+    if "AADSTS70021" in text or "AADSTS700213" in text:
+        return "no federated credential on the app matches this token's issuer and subject"
+    if "AADSTS90002" in text:
+        return "no such tenant: check the profile's tenant_id"
+    return "check the profile's client_id and tenant_id, and the app's credentials"

libre_devops_helpers/microsoft/auth/factory.py

@@ -0,0 +1,114 @@
+"""Build the credential a profile's ``auth`` setting names.
+
+Secrets never come from the config file. They come from the environment, under the
+same names the Azure SDKs use, so a CI job configured for one works for the other.
+"""
+
+from __future__ import annotations
+
+import os
+from collections.abc import Callable, Mapping
+from pathlib import Path
+
+import requests
+
+from libre_devops_helpers.core.auth import TokenProvider
+from libre_devops_helpers.core.errors import AuthError
+from libre_devops_helpers.core.token_store import TokenStore, open_store
+from libre_devops_helpers.microsoft.auth.azure_cli import AzureCliCredential, Reauthenticate
+from libre_devops_helpers.microsoft.auth.delegated import (
+    DeviceCodeCredential,
+    InteractiveCredential,
+)
+from libre_devops_helpers.microsoft.auth.entra import (
+    ClientSecretCredential,
+    WorkloadIdentityCredential,
+    federated_token_file,
+    github_actions_assertion,
+)
+from libre_devops_helpers.microsoft.auth.managed_identity import (
+    ManagedIdentityCredential,
+)
+from libre_devops_helpers.microsoft.config import DELEGATED_AUTH, Profile
+from libre_devops_helpers.microsoft.process import AzureCliRunner
+
+SECRET_VARIABLE = "AZURE_CLIENT_SECRET"
+TOKEN_FILE_VARIABLE = "AZURE_FEDERATED_TOKEN_FILE"
+GITHUB_URL_VARIABLE = "ACTIONS_ID_TOKEN_REQUEST_URL"
+GITHUB_TOKEN_VARIABLE = "ACTIONS_ID_TOKEN_REQUEST_TOKEN"
+
+
+def credential_for(
+    profile: Profile,
+    *,
+    runner: AzureCliRunner | None = None,
+    session: requests.Session | None = None,
+    verify: bool | str = True,
+    environ: Mapping[str, str] = os.environ,
+    notify: Callable[[str], None] | None = None,
+    reauthenticate: Reauthenticate | None = None,
+    token_store: TokenStore | None = None,
+) -> TokenProvider:
+    """The token provider for ``profile``. Raises AuthError when its inputs are missing.
+
+    ``reauthenticate`` is offered to the Azure CLI credential, to sign the CLI in again
+    when its session has lapsed; see AzureCliCredential. ``token_store`` keeps an
+    interactive or device-code sign-in between commands; without it, the store the
+    profile's ``token_cache`` names is opened.
+    """
+    login_url = profile.cloud.login_url
+    if profile.auth == "azure-cli":
+        return AzureCliCredential(runner, reauthenticate=reauthenticate)
+    if profile.auth == "managed-identity":
+        return ManagedIdentityCredential(profile.client_id, environ=environ, session=session)
+
+    client_id = profile.client_id
+    if client_id is None:
+        raise AuthError(f"profile {profile.name!r} uses auth = {profile.auth!r} without client_id")
+
+    if profile.auth in DELEGATED_AUTH:
+        flow = InteractiveCredential if profile.auth == "interactive" else DeviceCodeCredential
+        return flow(
+            client_id,
+            login_url=login_url,
+            session=session,
+            verify=verify,
+            notify=notify,
+            store=token_store or open_store(profile.token_cache, environ=environ),
+        )
+
+    if profile.auth == "client-secret":
+        secret = environ.get(SECRET_VARIABLE, "")
+        if not secret:
+            raise AuthError(
+                f"profile {profile.name!r} needs a client secret",
+                hint=f"set {SECRET_VARIABLE}; the config file never holds secrets",
+            )
+        return ClientSecretCredential(
+            client_id, secret, login_url=login_url, session=session, verify=verify
+        )
+
+    if profile.auth == "workload-identity":
+        token_file = environ.get(TOKEN_FILE_VARIABLE)
+        if token_file:
+            assertion = federated_token_file(Path(token_file))
+        elif environ.get(GITHUB_URL_VARIABLE) and environ.get(GITHUB_TOKEN_VARIABLE):
+            assertion = github_actions_assertion(
+                environ[GITHUB_URL_VARIABLE],
+                environ[GITHUB_TOKEN_VARIABLE],
+                session=session,
+                verify=verify,
+            )
+        else:
+            raise AuthError(
+                f"profile {profile.name!r} has no federated token to exchange",
+                hint=(
+                    f"set {TOKEN_FILE_VARIABLE}, or run in GitHub Actions with "
+                    "'permissions: id-token: write'"
+                ),
+            )
+        return WorkloadIdentityCredential(
+            client_id, assertion, login_url=login_url, session=session, verify=verify
+        )
+
+    raise AuthError(f"profile {profile.name!r} has an unknown auth method {profile.auth!r}")

libre_devops_helpers/microsoft/auth/lapse.py

@@ -0,0 +1,42 @@
+"""Why a sign-in lapsed: the Entra ID errors that only a fresh sign-in can clear.
+
+An access token lasts about an hour, and a refresh token renews it without asking
+anyone. These errors mean the refresh token itself can no longer be used, so retrying
+cannot help: someone has to sign in again. Naming the cause says whether that will keep
+happening (a sign-in frequency policy) or was a one-off (a password change).
+"""
+
+from __future__ import annotations
+
+import re
+
+# AADSTS code -> the cause, in plain words.
+REASONS = {
+    "AADSTS700082": "the session went unused for too long, so its refresh token expired",
+    "AADSTS70043": "a Conditional Access sign-in frequency policy wants a fresh sign-in",
+    "AADSTS70044": "a Conditional Access sign-in frequency policy wants a fresh sign-in",
+    "AADSTS50173": "the session was revoked (by an administrator, or by signing out everywhere)",
+    "AADSTS50132": "a password change or expiry ended the session",
+    "AADSTS50133": "a password change or expiry ended the session",
+    "AADSTS50055": "the password has expired",
+    "AADSTS50076": "multi-factor authentication is now required",
+    "AADSTS50078": "the multi-factor authentication on the session has expired",
+    "AADSTS50079": "multi-factor authentication must be set up for this account",
+    "AADSTS50158": "an external security challenge was not satisfied",
+}
+_CODE = re.compile(r"AADSTS\d+")
+_SIGNED_OUT = "az login"
+
+
+def lapse_reason(message: str) -> str | None:
+    """The cause when ``message`` says a sign-in lapsed, else None.
+
+    Knows the Entra ID codes above, and the Azure CLI's own ways of saying it has no
+    usable session (its messages all tell you to run ``az login``).
+    """
+    for code in _CODE.findall(message):
+        if code in REASONS:
+            return REASONS[code]
+    if _SIGNED_OUT in message:
+        return "the Azure CLI has no usable sign-in for this tenant"
+    return None

libre_devops_helpers/microsoft/auth/managed_identity.py

@@ -0,0 +1,84 @@
+"""Tokens for an Azure managed identity, from the endpoint of the host it runs on.
+
+App Service and Azure Functions publish ``IDENTITY_ENDPOINT`` and ``IDENTITY_HEADER``;
+virtual machines, scale sets and most other hosts use the instance metadata service
+(IMDS) at 169.254.169.254. Both are plain http on a local address by design; no bearer
+token is sent to either, so the http client allows them explicitly.
+"""
+
+from __future__ import annotations
+
+import os
+import time
+from collections.abc import Callable, Mapping
+from datetime import datetime
+
+import requests
+
+from libre_devops_helpers.core.auth import AccessToken, utc_now
+from libre_devops_helpers.core.errors import ApiError, AuthError
+from libre_devops_helpers.core.http import ApiClient
+from libre_devops_helpers.microsoft.auth.entra import parse_token_response
+
+IMDS_URL = "http://169.254.169.254/metadata/identity/oauth2/token"
+
+
+class ManagedIdentityCredential:
+    """A token provider for the managed identity of the Azure host this runs on.
+
+    ``client_id`` picks a user-assigned identity; without it the system-assigned one is
+    used. A managed identity belongs to one tenant, so ``tenant_id`` is not sent, and the
+    token checks catch a profile that names a different tenant.
+    """
+
+    def __init__(
+        self,
+        client_id: str | None = None,
+        *,
+        environ: Mapping[str, str] = os.environ,
+        session: requests.Session | None = None,
+        clock: Callable[[], datetime] = utc_now,
+        sleep: Callable[[float], None] = time.sleep,
+    ) -> None:
+        self.client_id = client_id
+        self._clock = clock
+        endpoint = environ.get("IDENTITY_ENDPOINT")
+        header = environ.get("IDENTITY_HEADER")
+        if endpoint and header:
+            self.source = "App Service"
+            self._url = endpoint
+            self._headers = {"X-IDENTITY-HEADER": header}
+            self._version = "2019-08-01"
+        else:
+            self.source = "IMDS"
+            self._url = IMDS_URL
+            self._headers = {"Metadata": "true"}
+            self._version = "2018-02-01"
+        # A short timeout: off Azure, IMDS never answers, and that should fail fast.
+        self._api = ApiClient(
+            self._url,
+            None,
+            name=f"managed identity ({self.source})",
+            session=session,
+            timeout=5.0,
+            max_attempts=3,
+            sleep=sleep,
+            allow_http=True,
+        )
+
+    def __repr__(self) -> str:
+        return f"ManagedIdentityCredential(client_id={self.client_id!r}, source={self.source!r})"
+
+    def get_token(self, resource: str, tenant_id: str) -> AccessToken:
+        params = {"api-version": self._version, "resource": resource}
+        if self.client_id:
+            params["client_id"] = self.client_id
+        now = self._clock()
+        try:
+            data = self._api.get(self._url, params=params, headers=self._headers)
+        except ApiError as exc:
+            raise AuthError(
+                str(exc),
+                hint="managed identity only works on an Azure host with an identity assigned",
+            ) from None
+        return parse_token_response(data, resource, tenant_id, now=now, name=self._api.name)

libre_devops_helpers/microsoft/automation/__init__.py

@@ -0,0 +1,24 @@
+"""Azure Automation: accounts, the jobs their runbooks ran, and each job's logs."""
+
+from libre_devops_helpers.microsoft.automation.client import API_VERSION, AutomationClient
+from libre_devops_helpers.microsoft.automation.models import (
+    FAILED,
+    STREAMS,
+    AutomationAccount,
+    Job,
+    JobStream,
+)
+
+# ARM tokens carry no scopes to check: Azure RBAC decides (Reader is enough to read jobs).
+REQUIREMENTS: tuple = ()
+
+__all__ = [
+    "API_VERSION",
+    "FAILED",
+    "REQUIREMENTS",
+    "STREAMS",
+    "AutomationAccount",
+    "AutomationClient",
+    "Job",
+    "JobStream",
+]