Merge pull request #8 from PredicateSystems/phase2_harden_Entra

Entra ID support

Author: rcholic

.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=

README.md

@@ -131,6 +131,31 @@ 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"
+```
+
+### Local IdP quick command
+
+```bash
+export LOCAL_IDP_SIGNING_KEY="replace-with-strong-secret"
+predicate-authorityd \
+  --host 127.0.0.1 \
+  --port 8787 \
+  --mode local_only \
+  --policy-file examples/authorityd/policy.json \
+  --identity-mode local-idp \
+  --local-idp-issuer "http://localhost/predicate-local-idp" \
+  --local-idp-audience "api://predicate-authority"
+```
+
 ## Operations CLI
 
 `predicate-authority` provides an ops-focused CLI for sidecar/runtime workflows.

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,

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:

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`

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`.

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()