Entra ID support

rcholic · rcholic · commit a7b2d032c820 · 2026-02-17T21:15:32.000-08:00
diff --git a/.env.example b/.env.example
@@ -12,3 +12,15 @@ OKTA_OBO_COMPAT_CHECK_ENABLED=0
 
 # Set to 1/true only if your Okta tenant supports token exchange/OBO.
 OKTA_SUPPORTS_TOKEN_EXCHANGE=0
+
+# Entra OBO compatibility checks (examples/tests)
+ENTRA_TENANT_ID=<your-entra-tenant-id>
+ENTRA_CLIENT_ID=<your-entra-client-id>
+ENTRA_CLIENT_SECRET=<your-entra-client-secret>
+ENTRA_SCOPE=api://predicate-authority/.default
+ENTRA_AUTHORITY_HOST=login.microsoftonline.com
+ENTRA_AUTHORITY_SCHEME=https
+ENTRA_OBO_COMPAT_CHECK_ENABLED=0
+ENTRA_SUPPORTS_OBO=0
+# Optional; required only when running true Entra OBO exchange path.
+ENTRA_USER_ASSERTION=
diff --git a/README.md b/README.md
@@ -131,6 +131,17 @@ See runnable examples in:
 - `examples/mcp_tool_guard_example.py`
 - `examples/outbound_http_guard_example.py`
 
+### Entra quick command (compatibility check)
+
+```bash
+set -a && source .env && set +a
+python examples/delegation/entra_obo_compat_demo.py \
+  --tenant-id "$ENTRA_TENANT_ID" \
+  --client-id "$ENTRA_CLIENT_ID" \
+  --client-secret "$ENTRA_CLIENT_SECRET" \
+  --scope "$ENTRA_SCOPE"
+```
+
 ## Operations CLI
 
 `predicate-authority` provides an ops-focused CLI for sidecar/runtime workflows.
diff --git a/docs/authorityd-operations.md b/docs/authorityd-operations.md
@@ -230,6 +230,43 @@ Notes:
 - omit `--supports-token-exchange` for tenants that do not support OBO/token exchange,
 - script reports whether delegation path should use IdP token exchange or authority mandate delegation.
 
+### Entra OBO compatibility (capability-gated)
+
+```bash
+export ENTRA_OBO_COMPAT_CHECK_ENABLED=1
+
+# Tenant supports OBO and user assertion is available:
+export ENTRA_SUPPORTS_OBO=true
+export ENTRA_USER_ASSERTION="<user-assertion-jwt>"
+python3 -m pytest tests/test_entra_obo_compatibility.py -k "live_check_when_enabled"
+
+# Tenant does NOT support OBO (or app policy not enabled):
+export ENTRA_SUPPORTS_OBO=false
+python3 -m pytest tests/test_entra_obo_compatibility.py -k "live_check_when_enabled"
+```
+
+Run demo script:
+
+```bash
+python examples/delegation/entra_obo_compat_demo.py \
+  --tenant-id "$ENTRA_TENANT_ID" \
+  --client-id "$ENTRA_CLIENT_ID" \
+  --client-secret "$ENTRA_CLIENT_SECRET" \
+  --scope "$ENTRA_SCOPE"
+```
+
+If OBO is supported and you have a user assertion:
+
+```bash
+python examples/delegation/entra_obo_compat_demo.py \
+  --tenant-id "$ENTRA_TENANT_ID" \
+  --client-id "$ENTRA_CLIENT_ID" \
+  --client-secret "$ENTRA_CLIENT_SECRET" \
+  --scope "$ENTRA_SCOPE" \
+  --user-assertion "$ENTRA_USER_ASSERTION" \
+  --supports-obo
+```
+
 ### Secret storage policy (Okta credentials)
 
 - never commit Okta client secrets/API tokens/private keys to repo files,
diff --git a/docs/predicate-authority-user-manual.md b/docs/predicate-authority-user-manual.md
@@ -278,6 +278,57 @@ If your tenant does not support token exchange, omit
 
 ---
 
+## Entra OBO compatibility check (capability-gated)
+
+Use this when validating Entra on-behalf-of delegation support before production rollout.
+
+### 1) Set environment variables
+
+```bash
+export ENTRA_TENANT_ID="<entra-tenant-id>"
+export ENTRA_CLIENT_ID="<entra-client-id>"
+export ENTRA_CLIENT_SECRET="<entra-client-secret>"
+export ENTRA_SCOPE="api://predicate-authority/.default"
+```
+
+### 2) Run compatibility test
+
+```bash
+# OBO not supported/configured:
+export ENTRA_OBO_COMPAT_CHECK_ENABLED=1
+export ENTRA_SUPPORTS_OBO=false
+python -m pytest tests/test_entra_obo_compatibility.py -k "live_check_when_enabled"
+
+# OBO supported and user assertion available:
+export ENTRA_OBO_COMPAT_CHECK_ENABLED=1
+export ENTRA_SUPPORTS_OBO=true
+export ENTRA_USER_ASSERTION="<user-assertion-jwt>"
+python -m pytest tests/test_entra_obo_compatibility.py -k "live_check_when_enabled"
+```
+
+### 3) Run demo script in `examples/`
+
+```bash
+python examples/delegation/entra_obo_compat_demo.py \
+  --tenant-id "$ENTRA_TENANT_ID" \
+  --client-id "$ENTRA_CLIENT_ID" \
+  --client-secret "$ENTRA_CLIENT_SECRET" \
+  --scope "$ENTRA_SCOPE"
+```
+
+If OBO is supported and assertion is available, add:
+
+```bash
+--user-assertion "$ENTRA_USER_ASSERTION" --supports-obo
+```
+
+Expected delegation path output:
+
+- `idp_obo_token_exchange` (if OBO succeeds), or
+- `authority_mandate_delegation` (fallback).
+
+---
+
 ## Local identity registry + flush queue
 
 Enable ephemeral task identity registry and local ledger queue:
diff --git a/examples/README.md b/examples/README.md
@@ -42,3 +42,9 @@ PYTHONPATH=. python examples/authorityd/daemon_endpoint_check.py
 For Okta OBO/token-exchange compatibility setup and troubleshooting, see:
 
 - `examples/README_Okta.md`
+
+## Entra compatibility example notes
+
+For Entra OBO compatibility setup and troubleshooting, see:
+
+- `examples/README_Entra.md`
diff --git a/examples/README_Entra.md b/examples/README_Entra.md
@@ -0,0 +1,55 @@
+# Entra Example Notes
+
+This note covers running the Entra OBO compatibility demo and common setup outcomes.
+
+## Prerequisites
+
+- Populate `AgentIdentity/.env` with:
+  - `ENTRA_TENANT_ID`
+  - `ENTRA_CLIENT_ID`
+  - `ENTRA_CLIENT_SECRET`
+  - `ENTRA_SCOPE` (for example `api://predicate-authority/.default`)
+  - optional for OBO path: `ENTRA_USER_ASSERTION`
+- Load env vars:
+
+```bash
+set -a
+source .env
+set +a
+```
+
+## Run Entra compatibility demo
+
+```bash
+python examples/delegation/entra_obo_compat_demo.py \
+  --tenant-id "$ENTRA_TENANT_ID" \
+  --client-id "$ENTRA_CLIENT_ID" \
+  --client-secret "$ENTRA_CLIENT_SECRET" \
+  --scope "$ENTRA_SCOPE"
+```
+
+If tenant supports OBO and you have a user assertion token:
+
+```bash
+python examples/delegation/entra_obo_compat_demo.py \
+  --tenant-id "$ENTRA_TENANT_ID" \
+  --client-id "$ENTRA_CLIENT_ID" \
+  --client-secret "$ENTRA_CLIENT_SECRET" \
+  --scope "$ENTRA_SCOPE" \
+  --user-assertion "$ENTRA_USER_ASSERTION" \
+  --supports-obo
+```
+
+## Common outcomes
+
+- `obo_reason=tenant_capability_disabled`:
+  - tenant/app is not configured for OBO, fallback delegation path should be used.
+- `obo_reason=user_assertion_required`:
+  - OBO is requested but no user assertion was provided.
+- `unauthorized_client` from token endpoint:
+  - app registration is not authorized for the requested OBO grant/policy.
+
+## Compatibility behavior
+
+- OBO success -> `delegation_path: idp_obo_token_exchange`.
+- OBO unavailable/not configured -> `delegation_path: authority_mandate_delegation`.
diff --git a/examples/delegation/entra_obo_compat_demo.py b/examples/delegation/entra_obo_compat_demo.py
@@ -0,0 +1,103 @@
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+from pathlib import Path
+
+
+def _ensure_repo_root_on_syspath() -> None:
+    repo_root = Path(__file__).resolve().parents[2]
+    root = str(repo_root)
+    if root not in sys.path:
+        sys.path.insert(0, root)
+
+
+def run(
+    tenant_id: str,
+    client_id: str,
+    client_secret: str,
+    scope: str,
+    supports_obo: bool,
+    user_assertion: str | None,
+    authority_host: str,
+    authority_scheme: str,
+    timeout_s: float,
+) -> dict[str, object]:
+    _ensure_repo_root_on_syspath()
+    from predicate_authority import (  # pylint: disable=import-error
+        EntraCompatibilityConfig,
+        EntraTenantCapabilities,
+        run_entra_obo_compatibility_check,
+    )
+
+    result = run_entra_obo_compatibility_check(
+        config=EntraCompatibilityConfig(
+            tenant_id=tenant_id,
+            client_id=client_id,
+            client_secret=client_secret,
+            scope=scope,
+            authority_host=authority_host,
+            authority_scheme=authority_scheme,
+        ),
+        capabilities=EntraTenantCapabilities(supports_obo=supports_obo),
+        user_assertion=user_assertion,
+        timeout_s=timeout_s,
+    )
+    result["delegation_path"] = (
+        "idp_obo_token_exchange"
+        if bool(result.get("obo_ok", False))
+        else "authority_mandate_delegation"
+    )
+    return result
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        description="Entra OBO compatibility demo for delegation flow."
+    )
+    parser.add_argument("--tenant-id", default=os.getenv("ENTRA_TENANT_ID"))
+    parser.add_argument("--client-id", default=os.getenv("ENTRA_CLIENT_ID"))
+    parser.add_argument("--client-secret", default=os.getenv("ENTRA_CLIENT_SECRET"))
+    parser.add_argument(
+        "--scope", default=os.getenv("ENTRA_SCOPE", "api://predicate-authority/.default")
+    )
+    parser.add_argument("--user-assertion", default=os.getenv("ENTRA_USER_ASSERTION"))
+    parser.add_argument(
+        "--authority-host", default=os.getenv("ENTRA_AUTHORITY_HOST", "login.microsoftonline.com")
+    )
+    parser.add_argument("--authority-scheme", default=os.getenv("ENTRA_AUTHORITY_SCHEME", "https"))
+    parser.add_argument("--timeout-s", type=float, default=5.0)
+    parser.add_argument("--supports-obo", action="store_true")
+    args = parser.parse_args()
+
+    missing = [
+        name
+        for name, value in (
+            ("tenant_id", args.tenant_id),
+            ("client_id", args.client_id),
+            ("client_secret", args.client_secret),
+            ("scope", args.scope),
+        )
+        if value is None or str(value).strip() == ""
+    ]
+    if missing:
+        raise SystemExit(f"Missing required arguments/env vars: {', '.join(missing)}")
+
+    payload = run(
+        tenant_id=str(args.tenant_id),
+        client_id=str(args.client_id),
+        client_secret=str(args.client_secret),
+        scope=str(args.scope),
+        supports_obo=bool(args.supports_obo),
+        user_assertion=(str(args.user_assertion) if args.user_assertion is not None else None),
+        authority_host=str(args.authority_host),
+        authority_scheme=str(args.authority_scheme),
+        timeout_s=float(args.timeout_s),
+    )
+    print(json.dumps(payload, indent=2, sort_keys=True))
+
+
+if __name__ == "__main__":
+    main()
diff --git a/predicate_authority/README.md b/predicate_authority/README.md
@@ -5,6 +5,7 @@ It binds identity, policy, and runtime evidence so risky actions are authorized
 before execution and denied fail-closed when checks do not pass.
 
 Docs: https://www.PredicateSystems.ai/docs
+Github Repo: https://github.com/PredicateSystems/predicate-authority
 
 Core pieces:
 
@@ -15,3 +16,58 @@ Core pieces:
 - typed integration adapters (including `sdk-python` mapping helpers),
 - control-plane client primitives for shipping proof and usage batches to hosted APIs,
 - local identity registry primitives (ephemeral task identities + local flush queue).
+
+## Quick usage example
+
+```python
+from predicate_authority import ActionGuard, InMemoryProofLedger, LocalMandateSigner, PolicyEngine
+from predicate_contracts import (
+    ActionRequest,
+    ActionSpec,
+    PolicyEffect,
+    PolicyRule,
+    PrincipalRef,
+    StateEvidence,
+    VerificationEvidence,
+)
+
+guard = ActionGuard(
+    policy_engine=PolicyEngine(
+        rules=(
+            PolicyRule(
+                name="allow-orders",
+                effect=PolicyEffect.ALLOW,
+                principals=("agent:orders",),
+                actions=("http.post",),
+                resources=("https://api.vendor.com/orders",),
+            ),
+        )
+    ),
+    mandate_signer=LocalMandateSigner(secret_key="replace-with-strong-secret"),
+    proof_ledger=InMemoryProofLedger(),
+)
+
+request = ActionRequest(
+    principal=PrincipalRef(principal_id="agent:orders", tenant_id="tenant-a"),
+    action_spec=ActionSpec(
+        action="http.post",
+        resource="https://api.vendor.com/orders",
+        intent="create order",
+    ),
+    state_evidence=StateEvidence(source="backend", state_hash="sha256:example"),
+    verification_evidence=VerificationEvidence(),
+)
+
+decision = guard.authorize(request)
+print("allowed=", decision.allowed, "reason=", decision.reason.value)
+```
+
+## Entra compatibility demo (capability-gated OBO)
+
+```bash
+python examples/delegation/entra_obo_compat_demo.py \
+  --tenant-id "$ENTRA_TENANT_ID" \
+  --client-id "$ENTRA_CLIENT_ID" \
+  --client-secret "$ENTRA_CLIENT_SECRET" \
+  --scope "${ENTRA_SCOPE:-api://predicate-authority/.default}"
+```
diff --git a/predicate_authority/__init__.py b/predicate_authority/__init__.py
diff --git a/predicate_authority/entra_compat.py b/predicate_authority/entra_compat.py
diff --git a/tests/test_entra_obo_compatibility.py b/tests/test_entra_obo_compatibility.py
