Tutorial 31 — Bridging AGT Identity with Microsoft Entra Agent ID¶

┌─────────────────────────────────────────────────────────────────────┐
│                        ENTERPRISE CONTROL PLANE                      │
│                                                                      │
│  ┌──────────────┐    ┌──────────────────┐    ┌──────────────────┐  │
│  │  Agent365     │    │  Microsoft Entra  │    │  Microsoft       │  │
│  │  Dashboard    │◄──►│  Agent ID         │◄──►│  Purview         │  │
│  │              │    │                  │    │  (Compliance)    │  │
│  └──────┬───────┘    └────────┬─────────┘    └──────────────────┘  │
│         │                     │                                      │
│         │         ┌───────────┴───────────┐                         │
│         │         │  Entra Object ID       │                         │
│         │         │  + Sponsor             │                         │
│         │         │  + Conditional Access   │                         │
│         │         │  + API Permissions      │                         │
│         │         └───────────┬───────────┘                         │
│         │                     │                                      │
│         │              IDENTITY BRIDGE                               │
│         │         ┌───────────┴───────────┐                         │
│         │         │  EntraAgentRegistry    │                         │
│         │         │  did:mesh ↔ Entra OID  │                         │
│         │         └───────────┬───────────┘                         │
│         │                     │                                      │
│  ┌──────┴─────────────────────┴─────────────────────────────────┐  │
│  │                  AGT RUNTIME GOVERNANCE                        │  │
│  │                                                                │  │
│  │  ┌─────────┐ ┌──────────┐ ┌─────────┐ ┌──────────────────┐  │  │
│  │  │ Policy  │ │ Trust    │ │ Audit   │ │ MCP Security     │  │  │
│  │  │ Engine  │ │ Scoring  │ │ Logger  │ │ Gateway          │  │  │
│  │  └─────────┘ └──────────┘ └─────────┘ └──────────────────┘  │  │
│  └──────────────────────────────────────────────────────────────┘  │
└─────────────────────────────────────────────────────────────────────┘

from agentmesh import AgentIdentity
from agentmesh.identity.entra import EntraAgentRegistry, EntraAgentBlueprint

# 1. Set up the Entra registry for your tenant
registry = EntraAgentRegistry(tenant_id="your-tenant-id")

# 2. (Optional) Register a blueprint for consistent agent creation
registry.register_blueprint(EntraAgentBlueprint(
    display_name="Data Analyst Agent",
    description="Reads customer data and generates reports",
    default_capabilities=["read:customer-data", "write:reports"],
    require_sponsor=True,
    max_delegation_depth=2,
    conditional_access_policy="ca-policy-id-for-agents",
))

# 3. Create the AGT identity
identity = AgentIdentity.create(
    name="data-analyst-agent",
    sponsor="alice@contoso.com",
    capabilities=["read:customer-data", "write:reports"],
)
print(f"AGT DID: {identity.did}")  # did:agentmesh:a7f3b2c1...

# 4. Register the bridge mapping
#    The entra_object_id comes from your Entra Agent ID provisioning
#    (via Azure Portal, Graph API, or Agent365)
entra_identity = registry.register(
    agent_did=identity.did,
    agent_name="data-analyst-agent",
    entra_object_id="aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",  # From Entra
    sponsor_email="alice@contoso.com",
    capabilities=["read:customer-data", "write:reports"],
    scopes=["https://graph.microsoft.com/.default"],
    blueprint_name="Data Analyst Agent",
)

from agentmesh.identity.entra_agent_id import EntraAgentID

# Auto-discover from Azure IMDS (on AKS, VMs, Container Apps, etc.)
entra_agent = EntraAgentID.from_managed_identity(agent_did=identity.did)

# Or from environment variables
entra_agent = EntraAgentID.from_environment(agent_did=identity.did)

# Get the DID ↔ Entra mapping
mapping = entra_agent.to_did_mapping()
# {
#   "agent_did": "did:agentmesh:a7f3b2c1...",
#   "entra": {
#     "tenant_id": "your-tenant-id",
#     "client_id": "your-client-id"
#   },
#   "mapping_version": "1.0"
# }

# 1. Create Kubernetes service account with Entra federated credential
apiVersion: v1
kind: ServiceAccount
metadata:
  name: agent-workload
  namespace: agents
  annotations:
    azure.workload.identity/client-id: "your-client-id"
  labels:
    azure.workload.identity/use: "true"

---
# 2. Pod spec with workload identity
apiVersion: v1
kind: Pod
metadata:
  name: data-analyst-agent
  namespace: agents
  labels:
    azure.workload.identity/use: "true"
spec:
  serviceAccountName: agent-workload
  containers:
    - name: agent
      image: your-registry.azurecr.io/data-analyst-agent:latest
      env:
        - name: AZURE_TENANT_ID
          value: "your-tenant-id"
        - name: AZURE_CLIENT_ID
          value: "your-client-id"

# 3. Create the federated credential in Entra
az identity federated-credential create \
  --name agent-fed-cred \
  --identity-name agent-managed-id \
  --resource-group agent-rg \
  --issuer "https://oidc.prod-aks.azure.com/your-oidc-issuer" \
  --subject "system:serviceaccount:agents:agent-workload" \
  --audiences "api://AzureADTokenExchange"

# Validate incoming Entra token
claims = entra_agent.validate_token(incoming_token)
# Validates: expiry, not-before, issuer (v1/v2 endpoints), audience

# Look up AGT identity from Entra object ID
agt_identity = registry.get_by_entra_id(claims["oid"])
if agt_identity and agt_identity.is_active():
    # Proceed with AGT policy enforcement using the mapped DID
    agt_identity.record_activity()

# When Entra suspends an agent → suspend in AGT
registry.suspend_agent(
    agent_did="did:agentmesh:a7f3b2c1...",
    reason="Entra Conditional Access violation"
)

# When AGT kill switch fires → disable in Entra
# 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...")

# AGT audit record
audit_record = entra_identity.to_audit_record()
# {
#   "agent_did": "did:agentmesh:a7f3b2c1...",
#   "entra_object_id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
#   "tenant_id": "your-tenant-id",
#   "sponsor_email": "alice@contoso.com",
#   "status": "active",
#   "capabilities": ["read:customer-data", "write:reports"],
#   "scopes": ["https://graph.microsoft.com/.default"],
#   "last_activity": "2026-04-16T01:00:00Z"
# }

from agentmesh import PolicyEngine

# Load AGT policies
policy_engine = PolicyEngine(config_path="governance.yaml")

# Combined verification: Entra scope + AGT policy
def verify_tool_call(agent_did: str, tool_name: str, params: dict) -> bool:
    # 1. Check Entra scope
    allowed, reason = registry.verify_access(
        agent_did=agent_did,
        required_scope="https://graph.microsoft.com/Files.Read"
    )
    if not allowed:
        print(f"Entra denied: {reason}")
        return False

    # 2. Check AGT policy
    decision = policy_engine.evaluate(agent_did, tool_name, params)
    if not decision.allowed:
        print(f"AGT policy denied: {decision.reason}")
        return False

    return True

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']

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