power-admin 0.1.0__py3-none-any.whl

power_admin/__init__.py

@@ -0,0 +1,3 @@
+"""Power Platform admin data puller."""
+
+__version__ = "0.1.0"

power_admin/auth.py

@@ -0,0 +1,161 @@
+"""Token acquisition for the Power Platform API and Microsoft Graph.
+
+Supported modes:
+  interactive    browser sign-in as you (delegated). Default.
+  device-code    sign in on any device with a code (delegated). Good for SSH or locked-down shells.
+  client-secret  app-only service principal with a client secret.
+  certificate    app-only service principal with a certificate (PEM private key + thumbprint).
+  token          bring your own access tokens via POWER_ADMIN_PP_TOKEN / POWER_ADMIN_GRAPH_TOKEN.
+
+Delegated modes cache tokens in ~/.power-admin, so you sign in once and later runs are silent
+until the refresh token expires. Note the Power Platform inventory API only accepts
+delegated (user) tokens; app-only modes get 403 there.
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Callable
+
+import msal
+
+from .config import GRAPH_SCOPE, PP_SCOPE, TOKEN_CACHE_FILE, Settings
+
+DELEGATED_MODES = {"interactive", "device-code"}
+
+# Microsoft's public client ID for Azure PowerShell (the one Connect-AzAccount uses). It is
+# pre-authorized for the Power Platform API and Graph, so delegated sign-in works without
+# registering your own Entra app. Override with --client-id if your tenant blocks it.
+DEFAULT_PUBLIC_CLIENT_ID = "1950a258-227b-4e31-a9cf-717495945fc2"
+APP_ONLY_MODES = {"client-secret", "certificate"}
+
+_TOKEN_ENV = {PP_SCOPE: "POWER_ADMIN_PP_TOKEN", GRAPH_SCOPE: "POWER_ADMIN_GRAPH_TOKEN"}
+
+
+class AuthError(RuntimeError):
+    pass
+
+
+def _load_cache() -> msal.SerializableTokenCache:
+    cache = msal.SerializableTokenCache()
+    if TOKEN_CACHE_FILE.exists():
+        cache.deserialize(TOKEN_CACHE_FILE.read_text(encoding="utf-8"))
+    return cache
+
+
+def _save_cache(cache: msal.SerializableTokenCache) -> None:
+    if cache.has_state_changed:
+        TOKEN_CACHE_FILE.parent.mkdir(parents=True, exist_ok=True)
+        TOKEN_CACHE_FILE.write_text(cache.serialize(), encoding="utf-8")
+        try:
+            os.chmod(TOKEN_CACHE_FILE, 0o600)
+        except OSError:
+            pass
+
+
+class TokenProvider:
+    """Returns bearer tokens per scope, signing in on first use."""
+
+    def __init__(self, settings: Settings, echo: Callable[[str], None] = print):
+        self.settings = settings
+        self.echo = echo
+        self._cache = _load_cache()
+        self._app: msal.ClientApplication | None = None
+        self._memo: dict[str, str] = {}
+
+    @property
+    def mode(self) -> str:
+        return self.settings.auth_mode
+
+    @property
+    def is_delegated(self) -> bool:
+        return self.mode in DELEGATED_MODES or self.mode == "token"
+
+    def _require(self, *names: str) -> None:
+        missing = [n for n in names if not getattr(self.settings, n)]
+        if missing:
+            flags = ", ".join("--" + n.replace("_", "-") for n in missing)
+            raise AuthError(f"Auth mode {self.mode!r} needs {flags} (or the matching POWER_ADMIN_* env vars)")
+
+    def _client(self) -> msal.ClientApplication:
+        if self._app is not None:
+            return self._app
+        s = self.settings
+        if self.mode in DELEGATED_MODES:
+            self._app = msal.PublicClientApplication(
+                s.client_id or DEFAULT_PUBLIC_CLIENT_ID, authority=s.authority, token_cache=self._cache
+            )
+        elif self.mode == "client-secret":
+            self._require("tenant_id", "client_id", "client_secret")
+            self._app = msal.ConfidentialClientApplication(
+                s.client_id, authority=s.authority, client_credential=s.client_secret, token_cache=self._cache
+            )
+        elif self.mode == "certificate":
+            self._require("tenant_id", "client_id", "certificate_path", "certificate_thumbprint")
+            key = Path(s.certificate_path).read_text(encoding="utf-8")
+            self._app = msal.ConfidentialClientApplication(
+                s.client_id,
+                authority=s.authority,
+                client_credential={"private_key": key, "thumbprint": s.certificate_thumbprint},
+                token_cache=self._cache,
+            )
+        else:
+            raise AuthError(f"Auth mode {self.mode!r} does not use MSAL")
+        return self._app
+
+    def get_token(self, scope: str) -> str:
+        if scope in self._memo:
+            return self._memo[scope]
+        token = self._acquire(scope)
+        self._memo[scope] = token
+        return token
+
+    def _acquire(self, scope: str) -> str:
+        if self.mode == "token":
+            env = _TOKEN_ENV.get(scope)
+            value = os.environ.get(env or "")
+            if not value:
+                raise AuthError(f"Auth mode 'token' needs the {env} environment variable for {scope}")
+            return value
+
+        app = self._client()
+        scopes = [scope]
+        result = None
+        if self.mode in APP_ONLY_MODES:
+            result = app.acquire_token_for_client(scopes=scopes)
+        else:
+            accounts = app.get_accounts()
+            if accounts:
+                result = app.acquire_token_silent(scopes, account=accounts[0])
+            if not result:
+                result = self._sign_in(app, scopes)
+        _save_cache(self._cache)
+
+        if not result or "access_token" not in result:
+            detail = (result or {}).get("error_description") or (result or {}).get("error") or "no token returned"
+            raise AuthError(f"Could not get a token for {scope}: {detail}")
+        return result["access_token"]
+
+    def _sign_in(self, app: msal.PublicClientApplication, scopes: list[str]) -> dict:
+        if self.mode == "device-code":
+            flow = app.initiate_device_flow(scopes=scopes)
+            if "user_code" not in flow:
+                raise AuthError(f"Device code flow failed: {flow.get('error_description', flow)}")
+            self.echo(flow["message"])
+            return app.acquire_token_by_device_flow(flow)
+        self.echo("Opening a browser window to sign in...")
+        return app.acquire_token_interactive(scopes=scopes, prompt="select_account")
+
+    def signed_in_user(self) -> str | None:
+        if self.mode not in DELEGATED_MODES:
+            return None
+        accounts = self._client().get_accounts()
+        return accounts[0].get("username") if accounts else None
+
+
+def logout() -> bool:
+    if TOKEN_CACHE_FILE.exists():
+        TOKEN_CACHE_FILE.unlink()
+        return True
+    return False

power_admin/cli.py

@@ -0,0 +1,208 @@
+"""power-admin command line interface."""
+
+from __future__ import annotations
+
+from datetime import date, datetime, timedelta, timezone
+from typing import Annotated, Optional
+
+import typer
+
+from . import __version__
+from .auth import APP_ONLY_MODES, AuthError, TokenProvider, logout as clear_cache
+from .collectors import COLLECTORS, PullContext
+from .config import AUTH_MODES, CONFIG_FILE, GRAPH_SCOPE, PP_SCOPE, load_settings, save_settings
+from .http import ApiClient, ApiError
+from .storage import configure_s3, write_dataset, write_manifest
+
+app = typer.Typer(
+    help="Pull Power Platform admin data (inventory, capacity, Copilot credits, users) to a folder or S3.",
+    no_args_is_help=True,
+    add_completion=False,
+)
+
+# Shared auth options -------------------------------------------------------
+TenantOpt = Annotated[Optional[str], typer.Option("--tenant-id", "-t", help="Entra tenant ID or domain.")]
+ClientOpt = Annotated[Optional[str], typer.Option("--client-id", "-c", help="App registration (client) ID. Optional for interactive/device-code.")]
+AuthOpt = Annotated[
+    Optional[str],
+    typer.Option("--auth", "-a", help=f"Auth mode: {', '.join(AUTH_MODES)}. Default: interactive."),
+]
+SecretOpt = Annotated[
+    Optional[str], typer.Option("--client-secret", help="Client secret (client-secret mode). Prefer POWER_ADMIN_CLIENT_SECRET.")
+]
+CertOpt = Annotated[Optional[str], typer.Option("--certificate-path", help="PEM private key (certificate mode).")]
+ThumbOpt = Annotated[Optional[str], typer.Option("--certificate-thumbprint", help="Certificate thumbprint.")]
+
+
+def _settings(tenant_id, client_id, auth, client_secret=None, certificate_path=None, certificate_thumbprint=None, output=None):
+    try:
+        return load_settings(
+            tenant_id=tenant_id,
+            client_id=client_id,
+            auth_mode=auth,
+            client_secret=client_secret,
+            certificate_path=certificate_path,
+            certificate_thumbprint=certificate_thumbprint,
+            output=output,
+        )
+    except ValueError as exc:
+        raise typer.BadParameter(str(exc)) from exc
+
+
+def _parse_date(value: Optional[str], default: date) -> date:
+    return date.fromisoformat(value) if value else default
+
+
+@app.command()
+def version() -> None:
+    """Print the version."""
+    typer.echo(__version__)
+
+
+@app.command()
+def configure(
+    tenant_id: TenantOpt = None,
+    client_id: ClientOpt = None,
+    auth: AuthOpt = None,
+    certificate_path: CertOpt = None,
+    certificate_thumbprint: ThumbOpt = None,
+    output: Annotated[Optional[str], typer.Option("--output", "-o", help="Default output folder or s3://bucket/prefix.")] = None,
+) -> None:
+    """Save defaults to ~/.power-admin/config.json so you don't pass them every time (secrets are never saved)."""
+    s = _settings(tenant_id, client_id, auth, None, certificate_path, certificate_thumbprint, output)
+    path = save_settings(s)
+    typer.echo(f"Saved settings to {path}")
+
+
+@app.command()
+def login(
+    tenant_id: TenantOpt = None,
+    client_id: ClientOpt = None,
+    auth: AuthOpt = None,
+    client_secret: SecretOpt = None,
+    certificate_path: CertOpt = None,
+    certificate_thumbprint: ThumbOpt = None,
+) -> None:
+    """Sign in and cache tokens for the Power Platform API and Microsoft Graph."""
+    s = _settings(tenant_id, client_id, auth, client_secret, certificate_path, certificate_thumbprint)
+    tokens = TokenProvider(s, echo=typer.echo)
+    try:
+        tokens.get_token(PP_SCOPE)
+        typer.echo("Power Platform API: OK")
+        tokens.get_token(GRAPH_SCOPE)
+        typer.echo("Microsoft Graph: OK")
+    except AuthError as exc:
+        typer.secho(str(exc), fg=typer.colors.RED, err=True)
+        raise typer.Exit(1)
+    user = tokens.signed_in_user()
+    typer.echo(f"Signed in{' as ' + user if user else ''} using {s.auth_mode} auth.")
+
+
+@app.command()
+def logout() -> None:
+    """Delete the cached sign-in."""
+    typer.echo("Signed out." if clear_cache() else "No cached sign-in found.")
+
+
+@app.command()
+def datasets() -> None:
+    """List what `pull` can collect."""
+    for c in COLLECTORS.values():
+        note = "  (needs a signed-in user)" if c.delegated_only else ""
+        typer.echo(f"{c.name:<14}{c.description}{note}")
+
+
+@app.command()
+def pull(
+    output: Annotated[
+        Optional[str], typer.Option("--output", "-o", help="Folder or s3://bucket/prefix. Default from config.")
+    ] = None,
+    only: Annotated[Optional[list[str]], typer.Option("--only", help="Collect only these (repeatable).")] = None,
+    skip: Annotated[Optional[list[str]], typer.Option("--skip", help="Skip these (repeatable).")] = None,
+    date_from: Annotated[
+        Optional[str], typer.Option("--from", help="Start date for credit usage, YYYY-MM-DD. Default: 1st of last month.")
+    ] = None,
+    date_to: Annotated[Optional[str], typer.Option("--to", help="End date, YYYY-MM-DD. Default: today.")] = None,
+    credit_entitlement: Annotated[
+        str, typer.Option(help="Licensing entitlement ID used for Copilot credit consumption.")
+    ] = "MCSMessages",
+    fmt: Annotated[list[str], typer.Option("--format", "-f", help="jsonl and/or csv (repeatable).")] = ["jsonl", "csv"],
+    aws_profile: Annotated[Optional[str], typer.Option(help="AWS profile for s3:// output.")] = None,
+    s3_endpoint_url: Annotated[Optional[str], typer.Option(help="Custom S3 endpoint (e.g. MinIO).", hidden=True)] = None,
+    tenant_id: TenantOpt = None,
+    client_id: ClientOpt = None,
+    auth: AuthOpt = None,
+    client_secret: SecretOpt = None,
+    certificate_path: CertOpt = None,
+    certificate_thumbprint: ThumbOpt = None,
+) -> None:
+    """Collect admin data and save a dated snapshot."""
+    s = _settings(tenant_id, client_id, auth, client_secret, certificate_path, certificate_thumbprint, output)
+    unknown = [n for n in (only or []) + (skip or []) if n not in COLLECTORS]
+    if unknown:
+        raise typer.BadParameter(f"Unknown dataset(s): {', '.join(unknown)}. See `power-admin datasets`.")
+    bad_fmt = [f for f in fmt if f not in ("jsonl", "csv")]
+    if bad_fmt:
+        raise typer.BadParameter(f"Unknown format(s): {', '.join(bad_fmt)}")
+
+    today = date.today()
+    first_of_last_month = (today.replace(day=1) - timedelta(days=1)).replace(day=1)
+    ctx_from, ctx_to = _parse_date(date_from, first_of_last_month), _parse_date(date_to, today)
+
+    if s.output.startswith("s3://"):
+        configure_s3(aws_profile, s3_endpoint_url)
+
+    tokens = TokenProvider(s, echo=typer.echo)
+    ctx = PullContext(ApiClient(tokens), ctx_from, ctx_to, credit_entitlement)
+    selected = [c for name, c in COLLECTORS.items() if (not only or name in only) and name not in (skip or [])]
+
+    now = datetime.now(timezone.utc)
+    snapshot = now.date().isoformat()
+    manifest: dict = {
+        "run_id": now.strftime("%Y%m%dT%H%M%SZ"),
+        "started": now.isoformat(),
+        "auth_mode": s.auth_mode,
+        "period": {"from": ctx_from.isoformat(), "to": ctx_to.isoformat()},
+        "datasets": {},
+        "errors": {},
+    }
+    results: dict[str, list[dict]] = {}
+    for c in selected:
+        if c.delegated_only and s.auth_mode in APP_ONLY_MODES:
+            msg = "skipped: needs a signed-in user (use interactive or device-code auth)"
+            manifest["errors"][c.name] = msg
+            typer.secho(f"- {c.name}: {msg}", fg=typer.colors.YELLOW)
+            continue
+        typer.echo(f"- {c.name}: collecting...")
+        try:
+            out = c.run(ctx, results)
+        except (ApiError, AuthError) as exc:
+            manifest["errors"][c.name] = str(exc)
+            typer.secho(f"  failed: {exc}", fg=typer.colors.RED, err=True)
+            continue
+        for name, rows in out.items():
+            results[name] = rows
+            write_dataset(s.output, name, snapshot, rows, formats=tuple(fmt))
+            manifest["datasets"][name] = len(rows)
+            typer.echo(f"  {name}: {len(rows)} rows")
+
+    manifest["finished"] = datetime.now(timezone.utc).isoformat()
+    path = write_manifest(s.output, manifest["run_id"], manifest)
+    typer.echo(f"Saved to {s.output} (manifest: {path})")
+    if manifest["errors"]:
+        raise typer.Exit(1)
+
+
+@app.command()
+def status() -> None:
+    """Show the active settings and cached sign-in."""
+    s = load_settings()
+    typer.echo(f"Config file: {CONFIG_FILE}{'' if CONFIG_FILE.exists() else ' (not created yet)'}")
+    for k in ("tenant_id", "client_id", "auth_mode", "output"):
+        typer.echo(f"{k:<12}{getattr(s, k) or '-'}")
+    if s.auth_mode in ("interactive", "device-code"):
+        typer.echo(f"{'signed in':<12}{TokenProvider(s).signed_in_user() or 'no'}")
+
+
+if __name__ == "__main__":
+    app()

power_admin/collectors.py

@@ -0,0 +1,209 @@
+"""Collectors: each pulls one area of admin data and returns {dataset_name: rows}."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import date
+from typing import Callable
+
+from .config import GRAPH_API, GRAPH_SCOPE, POWER_PLATFORM_API, PP_SCOPE
+from .http import ApiClient
+
+PP_API_VERSION = "2024-10-01"
+
+# Resource types in the PowerPlatformResources inventory table.
+INVENTORY_TYPES = {
+    "microsoft.powerapps/canvasapps": "app",
+    "microsoft.powerapps/modeldrivenapps": "app",
+    "microsoft.powerapps/codeapps": "app",
+    "microsoft.powerapps/apps": "app",
+    "microsoft.powerautomate/cloudflows": "flow",
+    "microsoft.powerautomate/agentflows": "flow",
+    "microsoft.powerautomate/m365agentflows": "flow",
+    "microsoft.copilotstudio/agents": "agent",
+}
+
+GRAPH_USER_FIELDS = (
+    "id,displayName,userPrincipalName,mail,department,jobTitle,companyName,"
+    "officeLocation,country,accountEnabled,userType,createdDateTime,assignedLicenses"
+)
+
+
+@dataclass
+class PullContext:
+    client: ApiClient
+    date_from: date
+    date_to: date
+    credit_entitlement: str = "MCSMessages"
+
+
+@dataclass
+class Collector:
+    name: str
+    description: str
+    run: Callable[[PullContext, dict[str, list[dict]]], dict[str, list[dict]]]
+    delegated_only: bool = False
+
+
+def _pp(path: str) -> str:
+    sep = "&" if "?" in path else "?"
+    return f"{POWER_PLATFORM_API}{path}{sep}api-version={PP_API_VERSION}"
+
+
+def collect_environments(ctx: PullContext, _: dict) -> dict[str, list[dict]]:
+    rows = list(ctx.client.iter_odata(_pp("/environmentmanagement/environments"), PP_SCOPE))
+    return {"environments": rows}
+
+
+def inventory_query(skip_token: str | None = None) -> dict:
+    """All apps, flows and agents joined with their environment (the admin center's default query)."""
+    return {
+        "TableName": "PowerPlatformResources",
+        "Options": {"Top": 1000, "Skip": 0, "SkipToken": skip_token or ""},
+        "Clauses": [
+            {"$type": "extend", "FieldName": "joinKey", "Expression": "tolower(tostring(properties.environmentId))"},
+            {
+                "$type": "join",
+                "JoinKind": "leftouter",
+                "RightTable": {
+                    "TableName": "PowerPlatformResources",
+                    "Clauses": [
+                        {
+                            "$type": "where",
+                            "FieldName": "type",
+                            "Operator": "==",
+                            "Values": ["'microsoft.powerplatform/environments'"],
+                        },
+                        {
+                            "$type": "project",
+                            "FieldList": [
+                                "joinKey = tolower(name)",
+                                "environmentName = properties.displayName",
+                                "environmentRegion = location",
+                                "environmentType = properties.environmentType",
+                                "isManagedEnvironment = properties.isManaged",
+                            ],
+                        },
+                    ],
+                },
+                "LeftColumnName": "joinKey",
+                "RightColumnName": "joinKey",
+            },
+            {
+                "$type": "where",
+                "FieldName": "type",
+                "Operator": "in~",
+                "Values": [f"'{t}'" for t in INVENTORY_TYPES],
+            },
+        ],
+    }
+
+
+def collect_inventory(ctx: PullContext, _: dict) -> dict[str, list[dict]]:
+    url = _pp("/resourcequery/resources/query")
+    rows: list[dict] = []
+    skip_token = None
+    while True:
+        page = ctx.client.post_json(url, PP_SCOPE, inventory_query(skip_token)) or {}
+        rows.extend(page.get("data", []))
+        skip_token = page.get("skipToken")
+        if not skip_token:
+            break
+    out: dict[str, list[dict]] = {"inventory": rows, "agents": [], "apps": [], "flows": []}
+    for row in rows:
+        kind = INVENTORY_TYPES.get(str(row.get("type", "")).lower())
+        if kind:
+            out[kind + "s"].append(row)
+    return out
+
+
+def collect_capacity(ctx: PullContext, _: dict) -> dict[str, list[dict]]:
+    details = ctx.client.get_json(_pp("/licensing/tenantCapacity"), PP_SCOPE) or {}
+    rows = []
+    for cap in details.get("tenantCapacities", []):
+        consumption = cap.get("consumption") or {}
+        rows.append(
+            {
+                "capacityType": cap.get("capacityType"),
+                "capacityUnits": cap.get("capacityUnits"),
+                "status": cap.get("status"),
+                "totalCapacity": cap.get("totalCapacity"),
+                "maxCapacity": cap.get("maxCapacity"),
+                "consumedActual": consumption.get("actual"),
+                "consumedRated": consumption.get("rated"),
+                "consumedUpdatedOn": consumption.get("actualUpdatedOn"),
+                "capacityEntitlements": cap.get("capacityEntitlements"),
+            }
+        )
+    currency = ctx.client.get_json(
+        _pp("/licensing/tenantCapacity/currencyReports?includeAllocations=true&includeConsumptions=true"), PP_SCOPE
+    )
+    return {"capacity": rows, "capacity_raw": [details], "currency": currency or []}
+
+
+def collect_credits(ctx: PullContext, so_far: dict) -> dict[str, list[dict]]:
+    """Copilot credit consumption per resource (agent) across all environments."""
+    base = _pp(f"/licensing/entitlements/{ctx.credit_entitlement}/resources")
+    params: dict = {"fromDate": ctx.date_from.isoformat(), "toDate": ctx.date_to.isoformat()}
+    rows: list[dict] = []
+    while True:
+        page = ctx.client.get_json(base, PP_SCOPE, params=params) or {}
+        rows.extend(page.get("value", []))
+        token = page.get("continuationtoken") or page.get("continuationToken")
+        if not token:
+            break
+        params = {**params, "continuationToken": token}
+
+    # Attach agent names when inventory ran in the same pull.
+    names = {
+        str(a.get("name", "")).lower(): (a.get("properties") or {}).get("displayName") for a in so_far.get("agents", [])
+    }
+    envs = {
+        str(e.get("id", e.get("name", ""))).lower(): e.get("displayName") or (e.get("properties") or {}).get("displayName")
+        for e in so_far.get("environments", [])
+    }
+    for row in rows:
+        row["resourceName"] = names.get(str(row.get("resourceId", "")).lower())
+        row["environmentName"] = envs.get(str(row.get("environmentId", "")).lower())
+        row["periodFrom"] = ctx.date_from.isoformat()
+        row["periodTo"] = ctx.date_to.isoformat()
+    return {"agent_credits": rows}
+
+
+def collect_users(ctx: PullContext, _: dict) -> dict[str, list[dict]]:
+    users = list(
+        ctx.client.iter_odata(
+            f"{GRAPH_API}/v1.0/users", GRAPH_SCOPE, params={"$select": GRAPH_USER_FIELDS, "$top": "999"}
+        )
+    )
+    skus = list(ctx.client.iter_odata(f"{GRAPH_API}/v1.0/subscribedSkus", GRAPH_SCOPE))
+    sku_names = {s.get("skuId"): s.get("skuPartNumber") for s in skus}
+    user_licenses = [
+        {
+            "userId": u.get("id"),
+            "userPrincipalName": u.get("userPrincipalName"),
+            "skuId": lic.get("skuId"),
+            "skuPartNumber": sku_names.get(lic.get("skuId")),
+        }
+        for u in users
+        for lic in u.get("assignedLicenses") or []
+    ]
+    return {"users": users, "licenses": skus, "user_licenses": user_licenses}
+
+
+# Order matters: credits uses names from inventory and environments.
+COLLECTORS: dict[str, Collector] = {
+    c.name: c
+    for c in [
+        Collector("environments", "Environments with type, region, Dataverse and capacity details", collect_environments),
+        Collector(
+            "inventory",
+            "All apps, flows and Copilot Studio agents (also split into agents/apps/flows)",
+            collect_inventory,
+            delegated_only=True,
+        ),
+        Collector("capacity", "Tenant storage/API capacity and currency (credit) reports", collect_capacity),
+        Collector("credits", "Copilot credit consumption per agent for the date range", collect_credits),
+        Collector("users", "Entra users, tenant license SKUs, and per-user license assignments", collect_users),
+    ]
+}

power_admin/config.py

@@ -0,0 +1,72 @@
+"""Settings loaded from flags, environment variables and ~/.power-admin/config.json."""
+
+from __future__ import annotations
+
+import json
+import os
+from dataclasses import asdict, dataclass, fields
+from pathlib import Path
+
+CONFIG_DIR = Path(os.environ.get("POWER_ADMIN_HOME", Path.home() / ".power-admin"))
+CONFIG_FILE = CONFIG_DIR / "config.json"
+TOKEN_CACHE_FILE = CONFIG_DIR / "msal_token_cache.json"
+
+POWER_PLATFORM_API = "https://api.powerplatform.com"
+GRAPH_API = "https://graph.microsoft.com"
+PP_SCOPE = f"{POWER_PLATFORM_API}/.default"
+GRAPH_SCOPE = f"{GRAPH_API}/.default"
+
+AUTH_MODES = ("interactive", "device-code", "client-secret", "certificate", "token")
+
+
+@dataclass
+class Settings:
+    tenant_id: str | None = None
+    client_id: str | None = None
+    auth_mode: str = "interactive"
+    # Service principal options. The secret is never written to the config file.
+    client_secret: str | None = None
+    certificate_path: str | None = None
+    certificate_thumbprint: str | None = None
+    # Default output location: a local folder or s3://bucket/prefix
+    output: str = "./power-admin-output"
+
+    @property
+    def authority(self) -> str:
+        return f"https://login.microsoftonline.com/{self.tenant_id or 'organizations'}"
+
+
+_ENV = {
+    "tenant_id": "POWER_ADMIN_TENANT_ID",
+    "client_id": "POWER_ADMIN_CLIENT_ID",
+    "auth_mode": "POWER_ADMIN_AUTH_MODE",
+    "client_secret": "POWER_ADMIN_CLIENT_SECRET",
+    "certificate_path": "POWER_ADMIN_CERTIFICATE_PATH",
+    "certificate_thumbprint": "POWER_ADMIN_CERTIFICATE_THUMBPRINT",
+    "output": "POWER_ADMIN_OUTPUT",
+}
+
+_SECRET_FIELDS = {"client_secret"}
+
+
+def load_settings(**overrides: str | None) -> Settings:
+    """Config file < environment variables < explicit overrides (CLI flags)."""
+    values: dict[str, str] = {}
+    if CONFIG_FILE.exists():
+        values.update(json.loads(CONFIG_FILE.read_text(encoding="utf-8")))
+    for name, env in _ENV.items():
+        if os.environ.get(env):
+            values[name] = os.environ[env]
+    values.update({k: v for k, v in overrides.items() if v is not None})
+    known = {f.name for f in fields(Settings)}
+    settings = Settings(**{k: v for k, v in values.items() if k in known})
+    if settings.auth_mode not in AUTH_MODES:
+        raise ValueError(f"Unknown auth mode {settings.auth_mode!r}; choose one of {', '.join(AUTH_MODES)}")
+    return settings
+
+
+def save_settings(settings: Settings) -> Path:
+    CONFIG_DIR.mkdir(parents=True, exist_ok=True)
+    data = {k: v for k, v in asdict(settings).items() if v is not None and k not in _SECRET_FIELDS}
+    CONFIG_FILE.write_text(json.dumps(data, indent=2), encoding="utf-8")
+    return CONFIG_FILE

power_admin/http.py

@@ -0,0 +1,62 @@
+"""Thin HTTP client with bearer auth, retries on throttling, and paging helpers."""
+
+from __future__ import annotations
+
+import time
+from typing import Any, Iterator
+
+import requests
+
+from .auth import TokenProvider
+
+
+class ApiError(RuntimeError):
+    def __init__(self, status: int, url: str, body: str):
+        self.status = status
+        super().__init__(f"HTTP {status} from {url}: {body[:500]}")
+
+
+class ApiClient:
+    def __init__(
+        self,
+        tokens: TokenProvider,
+        session: requests.Session | None = None,
+        max_retries: int = 5,
+        sleep=time.sleep,
+    ):
+        self.tokens = tokens
+        self.session = session or requests.Session()
+        self.max_retries = max_retries
+        self._sleep = sleep
+
+    def request(self, method: str, url: str, scope: str, **kwargs: Any) -> requests.Response:
+        headers = {"Authorization": f"Bearer {self.tokens.get_token(scope)}", "Accept": "application/json"}
+        headers.update(kwargs.pop("headers", {}) or {})
+        for attempt in range(self.max_retries + 1):
+            resp = self.session.request(method, url, headers=headers, timeout=120, **kwargs)
+            if resp.status_code in (429, 500, 502, 503, 504) and attempt < self.max_retries:
+                retry_after = resp.headers.get("Retry-After")
+                delay = float(retry_after) if retry_after and retry_after.isdigit() else 2**attempt
+                self._sleep(min(delay, 60))
+                continue
+            if resp.status_code >= 400:
+                raise ApiError(resp.status_code, url, resp.text)
+            return resp
+        raise AssertionError("unreachable")
+
+    def get_json(self, url: str, scope: str, **kwargs: Any) -> Any:
+        resp = self.request("GET", url, scope, **kwargs)
+        return resp.json() if resp.content else None
+
+    def post_json(self, url: str, scope: str, body: Any) -> Any:
+        resp = self.request("POST", url, scope, json=body)
+        return resp.json() if resp.content else None
+
+    def iter_odata(self, url: str, scope: str, params: dict | None = None) -> Iterator[dict]:
+        """Follow @odata.nextLink (Graph and most Power Platform list endpoints)."""
+        next_url: str | None = url
+        while next_url:
+            page = self.get_json(next_url, scope, params=params) or {}
+            params = None  # nextLink already carries the query string
+            yield from page.get("value", [])
+            next_url = page.get("@odata.nextLink")

power_admin/storage.py

@@ -0,0 +1,74 @@
+"""Write datasets to a local folder or S3 using cloudpathlib.
+
+Layout (Athena/Glue friendly, partitioned by snapshot date):
+    <output>/<dataset>/snapshot_date=YYYY-MM-DD/<dataset>.jsonl
+    <output>/<dataset>/snapshot_date=YYYY-MM-DD/<dataset>.csv
+    <output>/_runs/<run_id>.json        run manifest (counts, errors)
+"""
+
+from __future__ import annotations
+
+import csv
+import io
+import json
+from typing import Any, Iterable
+
+from cloudpathlib import AnyPath, S3Client
+
+
+def configure_s3(profile: str | None = None, endpoint_url: str | None = None) -> None:
+    """Make s3:// paths use a named AWS profile (otherwise the default AWS credential chain)."""
+    if profile or endpoint_url:
+        S3Client(profile_name=profile, endpoint_url=endpoint_url).set_as_default_client()
+
+
+def flatten(row: dict, prefix: str = "") -> dict[str, Any]:
+    out: dict[str, Any] = {}
+    for key, value in row.items():
+        name = f"{prefix}{key}"
+        if isinstance(value, dict):
+            out.update(flatten(value, name + "."))
+        elif isinstance(value, list):
+            out[name] = json.dumps(value, ensure_ascii=False)
+        else:
+            out[name] = value
+    return out
+
+
+def to_csv(rows: Iterable[dict]) -> str:
+    flat = [flatten(r) for r in rows]
+    columns: list[str] = []
+    seen: set[str] = set()
+    for r in flat:
+        for k in r:
+            if k not in seen:
+                seen.add(k)
+                columns.append(k)
+    buf = io.StringIO()
+    writer = csv.DictWriter(buf, fieldnames=columns, extrasaction="ignore")
+    writer.writeheader()
+    writer.writerows(flat)
+    return buf.getvalue()
+
+
+def to_jsonl(rows: Iterable[dict]) -> str:
+    return "".join(json.dumps(r, ensure_ascii=False, default=str) + "\n" for r in rows)
+
+
+def write_dataset(output: str, dataset: str, snapshot_date: str, rows: list[dict], formats=("jsonl", "csv")) -> list[str]:
+    folder = AnyPath(output) / dataset / f"snapshot_date={snapshot_date}"
+    folder.mkdir(parents=True, exist_ok=True)
+    written = []
+    for fmt in formats:
+        target = folder / f"{dataset}.{fmt}"
+        target.write_text(to_jsonl(rows) if fmt == "jsonl" else to_csv(rows), encoding="utf-8")
+        written.append(str(target))
+    return written
+
+
+def write_manifest(output: str, run_id: str, manifest: dict) -> str:
+    folder = AnyPath(output) / "_runs"
+    folder.mkdir(parents=True, exist_ok=True)
+    target = folder / f"{run_id}.json"
+    target.write_text(json.dumps(manifest, indent=2, default=str), encoding="utf-8")
+    return str(target)

power_admin-0.1.0.dist-info/METADATA

@@ -0,0 +1,159 @@
+Metadata-Version: 2.5
+Name: power-admin
+Version: 0.1.0
+Summary: Pull Power Platform admin data (inventory, capacity, Copilot credits, users) to a local folder or S3.
+Project-URL: Homepage, https://github.com/emptymalei/power-admin
+Project-URL: Issues, https://github.com/emptymalei/power-admin/issues
+License-Expression: MIT
+License-File: LICENSE
+Keywords: admin,copilot-studio,governance,inventory,power-apps,power-automate,power-platform
+Classifier: Environment :: Console
+Classifier: Intended Audience :: System Administrators
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: System :: Systems Administration
+Requires-Python: >=3.10
+Requires-Dist: cloudpathlib[s3]>=0.18
+Requires-Dist: msal>=1.28
+Requires-Dist: requests>=2.31
+Requires-Dist: typer>=0.12
+Description-Content-Type: text/markdown
+
+# power-admin
+
+A small CLI that signs in to your Microsoft tenant and pulls Power Platform admin data into dated snapshots. You can save to a local folder or to S3.
+
+> Community tool. Not affiliated with or endorsed by Microsoft.
+
+| Dataset | What's in it | Source |
+| --- | --- | --- |
+| `environments` | Environments, their type and region, Dataverse details | Power Platform API `environmentmanagement` |
+| `inventory`, `agents`, `apps`, `flows` | Every canvas, model-driven and code app, every cloud and agent flow, and every Copilot Studio agent, joined to its environment | Power Platform inventory API (`PowerPlatformResources`) |
+| `capacity`, `capacity_raw`, `currency` | Tenant storage and API capacity, plus purchased, allocated and consumed amounts per currency (Copilot credits, AI Builder and others) | Power Platform API `licensing/tenantCapacity` |
+| `agent_credits` | Copilot credit consumption per agent and environment for a date range, with agent names attached | Power Platform API `licensing/entitlements/{id}/resources` |
+| `users`, `licenses`, `user_licenses` | Entra users, the tenant's license SKUs, and which user has which SKU | Microsoft Graph |
+
+## Install
+
+You need [uv](https://docs.astral.sh/uv/). In PowerShell:
+
+```powershell
+powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"   # if you don't have uv
+uvx power-admin --help          # run without installing (once published to PyPI)
+uv tool install power-admin     # or put `power-admin` on your PATH
+# from a local checkout: uv tool install .
+```
+
+## Setup
+
+You don't need your own Entra app. For `interactive` and `device-code` sign-in, power-admin uses the public client ID of Microsoft's Azure PowerShell app (`1950a258-227b-4e31-a9cf-717495945fc2`), which is the same one `Connect-AzAccount` uses. That app is already pre-authorized for the Power Platform API and Microsoft Graph, and it doesn't need an Azure subscription. Data access still comes from your own admin roles.
+
+```powershell
+power-admin configure --tenant-id contoso.onmicrosoft.com --output C:\power-admin
+```
+
+Your account needs the Power Platform Administrator role (or Global Administrator / Global Reader) so it can see the whole tenant. Graph reads need a role that can read users, such as Global Reader or User Administrator.
+
+### Optional: use your own app registration
+
+Use your own app if your tenant blocks the Azure PowerShell client through Conditional Access, if you want consent scoped to exactly these permissions, or if you need app-only auth.
+
+1. Go to **Entra admin center > App registrations > New registration**. Choose **single tenant**.
+2. Under **Authentication**, add the platform **Mobile and desktop applications** with the redirect URI `http://localhost`. If you'll use device-code sign-in, also set **Allow public client flows** to **Yes**.
+3. Under **API permissions**, add the following **delegated** permissions, then click **Grant admin consent**:
+   - **Power Platform API** (`8578e004-a5c6-46e7-913e-12f58912df43`): `ResourceQuery.Resources.Read`, `EnvironmentManagement.Environments.Read`, `Licensing.Allocations.Read`.
+     If the API doesn't show up in the list, run `New-MgServicePrincipal -AppId 8578e004-a5c6-46e7-913e-12f58912df43` once, using Microsoft Graph PowerShell.
+   - **Microsoft Graph**: `User.Read.All`, `Organization.Read.All`.
+4. Pass `--client-id <app-id>` to `power-admin configure`.
+
+### Or reuse an existing PowerShell sign-in
+
+If you're already signed in with the Az module, you can hand those tokens to power-admin:
+
+```powershell
+Connect-AzAccount -Tenant contoso.onmicrosoft.com   # warns that there are no subscriptions, which is fine
+$pp = Get-AzAccessToken -ResourceUrl "https://api.powerplatform.com" -AsSecureString
+$gr = Get-AzAccessToken -ResourceTypeName MSGraph -AsSecureString
+$env:POWER_ADMIN_PP_TOKEN    = $pp.Token | ConvertFrom-SecureString -AsPlainText
+$env:POWER_ADMIN_GRAPH_TOKEN = $gr.Token | ConvertFrom-SecureString -AsPlainText
+power-admin pull --auth token
+```
+
+Tokens last about an hour.
+
+## Use
+
+```powershell
+power-admin login                       # opens a browser; the sign-in is cached in ~/.power-admin
+power-admin pull                        # everything, credits from the 1st of last month to today
+power-admin pull -o s3://my-bucket/power-platform --aws-profile admin
+power-admin pull --only credits --from 2026-10-01 --to 2026-10-31
+power-admin pull --skip users -f csv    # CSV only
+power-admin datasets                    # list what can be pulled
+power-admin status                      # show settings and who's signed in
+power-admin logout
+```
+
+Output layout. It's the same for a local folder and for S3, and it's partitioned so that Athena and Glue can read it directly:
+
+```
+<output>/agents/snapshot_date=2026-10-30/agents.jsonl
+<output>/agents/snapshot_date=2026-10-30/agents.csv
+<output>/agent_credits/snapshot_date=2026-10-30/agent_credits.csv
+<output>/_runs/20261030T212400Z.json      # row counts and any errors for the run
+```
+
+Every run adds a new `snapshot_date`, so you build up history. If any dataset fails, the run still saves the rest, records the error in the manifest, and exits with code 1.
+
+S3 uploads use the normal AWS credential chain, or the profile you pass with `--aws-profile`. Run `aws sso login --profile admin` first if you use SSO.
+
+## Auth modes
+
+Pick a mode with `--auth` / `-a`, or set it in `power-admin configure` or with `POWER_ADMIN_AUTH_MODE`.
+
+| Mode | When to use | Needs |
+| --- | --- | --- |
+| `interactive` (default) | You, at your desk. Opens a browser. | `--tenant-id` (`--client-id` is optional) |
+| `device-code` | Remote or SSH shells, or when a browser can't open. You enter a code at microsoft.com/devicelogin. | Same (with your own app, also turn on **Allow public client flows**) |
+| `client-secret` | Unattended runs | `--tenant-id`, `--client-id`, `POWER_ADMIN_CLIENT_SECRET` |
+| `certificate` | Unattended runs without secrets | `--certificate-path` (PEM private key) and `--certificate-thumbprint` |
+| `token` | You already signed in with `Connect-AzAccount` or another tool | `POWER_ADMIN_PP_TOKEN` and `POWER_ADMIN_GRAPH_TOKEN` env vars |
+
+How the app-only modes (`client-secret`, `certificate`) differ:
+- **The inventory API rejects app-only tokens.** Microsoft only supports signed-in users there, so in these modes `inventory` is skipped and listed in the manifest.
+- **The service principal needs extra access.** It must be given a Power Platform RBAC role (see Microsoft's guide *Assign RBAC roles to service principals*), and for `users` it needs the Graph *application* permissions `User.Read.All` and `Organization.Read.All`.
+
+For monthly manual runs, `interactive` is the simplest option.
+
+## Caveats
+
+- **The per-agent credit endpoints may change or fail.** They are marked *deprecated* in the Power Platform API reference but still documented. The entitlement ID `MCSMessages` (Copilot credits) is our best reading of the docs and hasn't been tested against a live tenant yet; if you get a 400 or 404, try `--credit-entitlement` with another value. Whatever happens, the admin center's **Licensing > Copilot Studio > Download report** remains the authoritative source.
+- **Several licensing APIs are still in preview**, so their field names may change. JSONL keeps the full raw response; CSV flattens nested fields into `a.b.c` columns.
+- **Usage metrics are missing.** Per-app users, per-flow runs and per-agent sessions from the admin center's Usage page don't have a public API yet.
+
+## Querying in Athena (optional)
+
+```sql
+CREATE EXTERNAL TABLE agent_credits (
+  resourceId string, resourceName string, environmentId string, environmentName string,
+  consumed double, unit string, lastRefreshedDate string, periodFrom string, periodTo string
+)
+PARTITIONED BY (snapshot_date string)
+ROW FORMAT SERDE 'org.openx.data.jsonserde.JsonSerDe'
+LOCATION 's3://my-bucket/power-platform/agent_credits/';
+MSCK REPAIR TABLE agent_credits;
+```
+
+## Develop
+
+```bash
+uv sync
+uv run pytest
+```
+
+## Releasing
+
+CI runs the tests on every push and pull request. Publishing a GitHub release whose tag is `v<version>` (for example `v0.1.0`, matching `version` in `pyproject.toml`) builds the package and uploads it to PyPI.
+
+The release uses PyPI trusted publishing, so no token is stored in GitHub. One-time setup:
+1. Add a pending publisher on PyPI under **Your account > Publishing**, with project `power-admin`, owner `emptymalei`, repository `power-admin`, workflow `release.yml` and environment `pypi`.
+2. In the GitHub repo, open **Settings > Environments** and create an environment called `pypi`.

power_admin-0.1.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+power_admin/__init__.py,sha256=gMorSrTk6qwi3VBYf6FbFpc8CBcMXB6YwOerfnlSJ8U,63
+power_admin/auth.py,sha256=RRiuTozFh_e_MfwrMg_fv7MmyjSEhPmQVcS95OiVwBM,6369
+power_admin/cli.py,sha256=1ii_KuNjMesVXwOSvmmlMreiFKwkw7vBb6zOXtOKzQw,8715
+power_admin/collectors.py,sha256=DVtoeGtgsC3jkl26y-NiX61AZe4aWkbt-ALfuf7X6xE,8256
+power_admin/config.py,sha256=dPFGu5sPwxr7Ckv1jKv9VWFEunSDiUfgXyvRx9hBnnA,2679
+power_admin/http.py,sha256=uMb2Bt5iAkONGjxUBX_rBDfgr9vMwxMVDwfIOYJg1TE,2481
+power_admin/storage.py,sha256=Xh_eOGCfFbPzhGn_IB9glg0Kbw8gr4th6A6r8R02p50,2546
+power_admin-0.1.0.dist-info/METADATA,sha256=EJhh2xJj9XJIKXepceXVyFDokQR9cEHqoBvIcVTiPFg,9466
+power_admin-0.1.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+power_admin-0.1.0.dist-info/entry_points.txt,sha256=01Mbd9HmzpOnooHvlJ0WR7PcTMCnOw8F9m4hz_4wGZc,52
+power_admin-0.1.0.dist-info/licenses/LICENSE,sha256=eU-CKYy3Y2UUqcjG6BOFP0GEjetNUvD9Z7x8DLPI6W4,1058
+power_admin-0.1.0.dist-info/RECORD,,

power_admin-0.1.0.dist-info/WHEEL

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

power_admin-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+power-admin = power_admin.cli:app

power_admin-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 L
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.