AGENTS.md — Identity Research for Agent Management Using SPIFFE Control Panel (Portal)

Web-based management UI for live RBAC, admin governance, and A2A demonstrations.

What This Is

A FastAPI-backed single-page app that lets you:

1. Execute test requests between agents and see real-time results
   • normal SPIFFE path to BudgetBackend
   • direct A2A HTTPS path between selected agents
2. View and edit RBAC policies on any agent's sidecar
3. View and edit mTLS allow lists — add/remove SPIFFE IDs with immediate effect
4. Run security scans — automated detection of misconfigurations with one-click fixes
5. Demonstrate live policy changes — edit a rule, re-run a request, show the enforcement change
6. Operate the live environment safely — dependency-aware health, durable policy config storage, and explicit admin-only mutation paths

How It Works

The portal talks to the dedicated admin-control-plane endpoint, which proxies management API calls to BudgetBackend via mTLS. This works because:

• BudgetBackend has internal-only ingress — not reachable from outside
• admin-control-plane has external ingress and exists only for management/recovery traffic
• admin-control-plane forwards /admin/* to BudgetBackend's sidecar /mgmt/* API on port 9443
• BudgetApproval is now just a governed business agent; it is not the recovery path anymore
• Live A2A execution no longer hardwires to BudgetApproval. The portal sends the selected target to the caller app, which then calls the selected target's /a2a/status endpoint.
• Production runtime is live-only. Simulated/demo responses are no longer part of the portal backend contract.

Key Files

portal/
├── app/                  ← Modular FastAPI backend package
│   ├── main.py           ← App factory + middleware + lifespan
│   ├── settings.py       ← Local/cloud config loading and validation
│   ├── auth.py           ← Entra auth + admin/viewer role checks
│   ├── clients/          ← Admin control-plane, agent, and Graph clients
│   ├── services/         ← Policy, scan, CA, and health services
│   └── storage/          ← File + Blob-backed policy config stores
├── index.html            ← Main UI (vanilla JS, no framework)
├── server.py             ← Thin compatibility wrapper / CLI entrypoint
├── portal-config.json    ← Agent endpoints (git-ignored, generated by deploy.sh)
└── deploy-portal.sh      ← Launch portal locally from generated live config

Running

# After deploy.sh completes (generates portal-config.json):
python3 portal/server.py --port 8550 --config portal/portal-config.json
# Open http://localhost:8550

deploy.sh launches the portal only when --portal is supplied.

For cloud-only portal changes, prefer:

./deploy.sh --portal-only

That rebuilds and updates isp-portal and securityportal-mock without restarting agent sidecars or forcing SPIRE re-attestation.

Operational Notes

1. Cloud startup now fails fast on missing ADMIN_CP_URL, MGMT_API_KEY, Entra auth config, or Blob storage settings.
2. Saved policy configs use Azure Blob Storage in cloud and policy-configs.json only for local development.
3. /healthz/live reports process health, /healthz/ready reports dependency readiness, and /api/system-status exposes dependency-level status to authenticated users.
4. reload-config is local-only and should not be used as a cloud runtime mechanism.
5. For new deployments, portal app registrations are env-scoped: Identity Research for Agent Management Using SPIFFE Portal - Management [<env>] and Identity Research for Agent Management Using SPIFFE Portal - Security Portal Mock [<env>].
6. The portal auth groups stay shared tenant-wide: Agent Management Administrators and Agent Management Viewers.
7. Existing deployments stay on legacy Agent Blueprint naming until explicitly migrated.
8. ./deploy.sh --portal-only is the preferred cloud deploy path for portal-only UI/backend changes; do not use it for agent-side or SPIRE-side changes.

This is the Identity Research for Agent Management Using SPIFFE control panel for live demonstrations and operational validation.

Read With This

• docs/developer/portal-runtime.md
• docs/reference/management-apis.md
• docs/reference/authentication-flows.md
• docs/architecture/portal-cloud-deployment.md

portal-config.json Format

{
  "mode": "live",
  "trust_domain": "aim.microsoft.com",
  "resource_group": "rg-<env>",
  "location": "eastus2",
  "portal_port": 8550,
  "agents": {
    "budget-report": {
      "name": "BudgetReport",
      "app_name": "budget-report",
      "url": "https://budget-report.<env>.eastus2.azurecontainerapps.io",
      "spiffe_id": "spiffe://aim.microsoft.com/ests/bp/<bp-oid>/aid/<agent-oid>",
      "entra_agent_id": "<agent-oid>",
      "role": "Read-only Caller",
      "entra_role": "BudgetFrontEnds"
    },
    "budget-backend": { "..." },
    "employee-menus": { "..." },
    "budget-approval": { "..." }
  },
  "control_plane": {
    "name": "Admin Control Plane",
    "app_name": "admin-control-plane",
    "url": "https://admin-control-plane.<env>.eastus2.azurecontainerapps.io",
    "spiffe_id": "spiffe://aim.microsoft.com/ests/bp/<bp-oid>/aid/<agent-oid>",
    "entra_agent_id": "<agent-oid>",
    "role": "Management Control Plane"
  },
  "spire_server_ip": "<vm-ip>",
  "management_api_port": 9443,
  "mgmt_api_key": "<key>"
}

This file is git-ignored because endpoints change per deployment. Generated automatically by deploy.sh.

Agent Discovery (Cloud Mode)

In cloud mode (PORTAL_MODE=cloud), the portal discovers agents from admin-control-plane's /admin/agents endpoint at startup. Agent URLs are derived from CONTAINER_APP_ENV_DNS_SUFFIX at runtime — no static env vars needed. Dynamic agents appear automatically if they're in the RBAC policy.

Auth Token Handling

The api() JS helper retries on 401 by calling acquireTokenSilent. If silent refresh fails (e.g. MSAL cache expired overnight), it falls back to acquireTokenRedirect for an interactive login. Same pattern in security portal mock via the monkey-patched fetch wrapper.

Current Gotchas

• Policy push via the portal uses Content-Type: application/x-yaml (raw YAML), not JSON-wrapped.
• Cloud storage access depends on the portal Container App managed identity having Storage Blob Data Contributor on the portal policy store.
• The UI still accepts legacy #/demo/... deep links for backward compatibility, but production behavior is live-only.
• The portal app registrations are env-scoped for new deployments, while Agent Management Administrators and Agent Management Viewers stay shared tenant-wide by design.