feat: add Graph API group membership sync for Entra Agent ID bridge

- Add EntraGraphClient in entra_graph.py for Microsoft Graph API calls
  - get_group_memberships() with pagination and type filtering
  - get_app_role_assignments() for role-based access
  - Proper error handling (GraphAPIError with HTTP status codes)
- Add sync_group_memberships() to EntraAgentRegistry
  - Maps Entra groups to AGT capabilities via configurable scope map
  - Preserves manually assigned capabilities (union merge)
  - Audit log integration
- Add validate_bridge_configuration() to EntraAgentRegistry
  - Validates bridge mapping completeness for Agent365 compatibility
- Add 26 tests covering Graph client, sync logic, and registry integration
- Update Tutorial 31 with Steps 6-7 and refreshed Known Gaps table

Closes microsoft#1173
Addresses microsoft#1174

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: imran-siddique

docs/tutorials/31-entra-agent-id-bridge.md

@@ -242,9 +242,9 @@ registry.suspend_agent(
 )
 
 # When AGT kill switch fires → disable in Entra
-# (This requires Graph API — not yet built into AGT)
-# POST https://graph.microsoft.com/v1.0/applications/{entra_object_id}
-# { "disabledByMicrosoftStatus": "DisabledDueToViolationOfServicesAgreement" }
+# Use Graph API: PATCH /servicePrincipals/{entra_object_id}
+# with { "accountEnabled": false }
+# (Requires Directory.ReadWrite.All or Application.ReadWrite.All permission)
 
 # When sponsor re-approves → reactivate
 registry.reactivate_agent(agent_did="did:agentmesh:a7f3b2c1...")
@@ -299,13 +299,58 @@ def verify_tool_call(agent_did: str, tool_name: str, params: dict) -> bool:
     return True
 ```
 
+## Step 6 — Group Membership Sync via Graph API
+
+Automatically map Entra group memberships to AGT capabilities:
+
+```python
+from agentmesh.identity.entra_graph import EntraGraphClient, build_group_scope_map
+
+# 1. Get a Graph API token (via managed identity, workload identity, etc.)
+token = entra_agent.get_agent_token(scope="https://graph.microsoft.com/.default")
+
+# 2. Create the Graph client
+graph_client = EntraGraphClient(access_token=token)
+
+# 3. Define group-to-capability mapping (keyed by Entra group object ID)
+group_scope_map = build_group_scope_map({
+    "aaaaaaaa-1111-2222-3333-444444444444": ["read:customer-data", "read:reports"],
+    "bbbbbbbb-1111-2222-3333-444444444444": ["write:reports", "export:csv"],
+})
+
+# 4. Sync — fetches groups from Graph, maps to capabilities, preserves manual caps
+capabilities = registry.sync_group_memberships(
+    agent_did=identity.did,
+    graph_client=graph_client,
+    group_scope_map=group_scope_map,
+)
+print(f"Updated capabilities: {capabilities}")
+# ['export:csv', 'manual:cap', 'read:customer-data', 'read:reports', 'write:reports']
+```
+
+> **Note:** The Graph API call requires `GroupMember.Read.All` or `Directory.Read.All` permission on the Entra application. Group sync only updates AGT **capabilities** — Entra API **scopes** remain unchanged.
+
+## Step 7 — Validate Bridge Configuration
+
+Before going to production, validate the bridge mapping is complete:
+
+```python
+valid, issues = registry.validate_bridge_configuration(agent_did=identity.did)
+if not valid:
+    print(f"Bridge configuration issues: {issues}")
+    # e.g., ['Missing entra_app_id — Agent365 may not resolve the agent']
+else:
+    print("Bridge configuration OK — ready for enterprise deployment")
+```
+
 ## Known Gaps and Limitations
 
 | Gap | Status | Workaround |
 |-----|--------|------------|
-| **Graph API provisioning** | Not in AGT | Create Entra Agent ID via Azure Portal or Graph API, then register mapping in AGT |
-| **Agent365 native integration** | Not yet tested | Agent365 sees Entra Agent ID — AGT bridge maps the DID; should work but needs validation |
+| **Graph API group membership sync** | ✅ Built | `EntraGraphClient.get_group_memberships()` + `EntraAgentRegistry.sync_group_memberships()` — maps Entra groups to AGT capabilities |
+| **Agent365 native integration** | Configuration validated | `EntraAgentRegistry.validate_bridge_configuration()` checks bridge mapping completeness; end-to-end Agent365 testing pending |
 | **Bidirectional lifecycle sync** | One-way (manual) | Use Azure Event Grid or Logic Apps to sync Entra state changes → AGT kill switch |
+| **Graph API service principal disable** | Not in AGT | Use Graph API directly: `PATCH /servicePrincipals/{id}` with `accountEnabled: false` |
 | **Entra bridge in non-Python SDKs** | Python-only | TS, .NET, Rust, Go SDKs need `EntraAgentRegistry` and `EntraAgentID` ported |
 | **DID format inconsistency** | `did:agentmesh:*` (Python, .NET) vs `did:agentmesh:*` (TS, Rust, Go) | Both formats work; standardization planned for v4.0 |
 | **Cryptographic token verification** | Claim-level only | Add `azure-identity` for JWKS-based signature verification |

packages/agent-mesh/src/agentmesh/identity/entra.py

@@ -12,12 +12,18 @@
 
 from __future__ import annotations
 
+import logging
 from datetime import datetime, timezone
 from enum import Enum
-from typing import Any, Optional
+from typing import TYPE_CHECKING, Any, Optional
 
 from pydantic import BaseModel, Field
 
+if TYPE_CHECKING:
+    from agentmesh.identity.entra_graph import EntraGraphClient
+
+logger = logging.getLogger(__name__)
+
 
 class EntraAgentStatus(str, Enum):
     """Entra Agent ID lifecycle states."""
@@ -280,6 +286,95 @@ def get_audit_log(self) -> list[dict[str, Any]]:
         """Return the full audit log."""
         return list(self._audit_log)
 
+    # -- Graph API integration (Issue #1173) -----------------------------------
+
+    def sync_group_memberships(
+        self,
+        agent_did: str,
+        graph_client: "EntraGraphClient",
+        group_scope_map: dict[str, list[str]],
+    ) -> list[str]:
+        """
+        Sync Entra group memberships to AGT capabilities for an agent.
+
+        Fetches the agent's group memberships from Microsoft Graph API,
+        maps them to AGT capabilities using ``group_scope_map``, and
+        updates the agent's capabilities (preserving manually assigned ones).
+
+        Args:
+            agent_did: The agent's AgentMesh DID.
+            graph_client: An authenticated ``EntraGraphClient`` instance.
+            group_scope_map: Mapping of Entra group object IDs to lists
+                of AGT capability strings.
+
+        Returns:
+            The updated list of capabilities.
+
+        Raises:
+            KeyError: If the agent is not registered.
+            GraphAPIError: If the Graph API call fails.
+        """
+        from agentmesh.identity.entra_graph import sync_memberships_to_capabilities
+
+        identity = self._agents.get(agent_did)
+        if not identity:
+            raise KeyError(f"Agent {agent_did!r} not found in registry")
+
+        groups = graph_client.get_group_memberships(identity.entra_object_id)
+
+        new_caps = sync_memberships_to_capabilities(
+            groups=groups,
+            group_scope_map=group_scope_map,
+            preserve_existing=identity.capabilities,
+        )
+
+        identity.capabilities = new_caps
+        self._log_event("sync_group_memberships", identity, {
+            "groups_found": len(groups),
+            "capabilities_after": new_caps,
+        })
+        return new_caps
+
+    # -- Bridge validation (Issue #1174) ---------------------------------------
+
+    def validate_bridge_configuration(
+        self, agent_did: str
+    ) -> tuple[bool, list[str]]:
+        """
+        Validate that an agent's Entra bridge configuration is complete.
+
+        Checks that all required fields for enterprise identity bridging
+        are populated. This validates the **configuration** (not live
+        connectivity to Entra or Agent365).
+
+        Returns:
+            Tuple of (valid, issues) where issues is a list of problems found.
+        """
+        identity = self._agents.get(agent_did)
+        if not identity:
+            return False, [f"Agent {agent_did!r} not found in registry"]
+
+        issues: list[str] = []
+
+        if not identity.entra_object_id:
+            issues.append("Missing entra_object_id")
+        if not identity.tenant_id:
+            issues.append("Missing tenant_id")
+        if not identity.sponsor_email:
+            issues.append("Missing sponsor_email (required for Agent365)")
+        if not identity.agent_did:
+            issues.append("Missing agent_did")
+        if identity.status != EntraAgentStatus.ACTIVE:
+            issues.append(
+                f"Agent status is {identity.status.value}, expected active"
+            )
+        if not identity.entra_app_id:
+            issues.append(
+                "Missing entra_app_id — Agent365 may not resolve the agent"
+            )
+
+        return (len(issues) == 0, issues)
+
     def _log_event(
         self,
         event_type: str,