alphaswarm_admin — Microsoft Entra Agent Identity

Last refreshed: 2026-05-27. Status: implementation of the alphaswarm_admin Entra refactor (.cursor/plans/alphaswarm_admin_entra_refactor_039f2aeb.plan.md). See also: entra-internal-tenant.md and identity.md.

The alphaswarm_admin BFF authenticates to alphaswarm_controller, the AlphaSwarm monolith, and (eventually) any other downstream service via a per-deployment Microsoft Entra Agent Identity instead of a shared client_credentials service principal. Each deployment (dev / staging / prod) gets its own sub claim in minted tokens so audit trails and RBAC routing remain clean even when the same Blueprint backs every environment.

This page is the operator + agent reference for the model.

Three-layer object graph

Layer	Resource	Provider
1	Agent Identity Blueprint	azapi_resource against Microsoft.Graph/applications/microsoft.graph.agentIdentityBlueprint
2	BlueprintPrincipal (mandatory second step)	azapi_resource against Microsoft.Graph/servicePrincipals/microsoft.graph.agentIdentityBlueprintPrincipal
3	Per-environment Agent Identity	azapi_resource against Microsoft.Graph/servicePrincipals/microsoft.graph.agentIdentity
4	Federated Identity Credential	azuread_application_federated_identity_credential on the Blueprint
5	App role assignment	azapi_resource against Microsoft.Graph/servicePrincipals/appRoleAssignedTo

Terraform module: alphaswarm_platform/terraform/modules/alphaswarm_admin_agent_identity/.

Two-step fmi_path exchange

At runtime each pod mints an Agent-Identity-bound access token via the two-step exchange documented in the entra-agent-id skill:

The exchange lives at alphaswarm_core.auth.providers.msal_entra.MsalEntraValidator.acquire_agent_token.

CredentialResolver integration

The admin BFF wires the Agent Identity flow through the existing SecretStore chain so route handlers never see the token directly.

from alphaswarm_core.credentials.stores import (
    EntraAgentIdentityCredentialResolver,
    EntraAgentIdentitySecretStore,
)
from alphaswarm_core.auth.providers.msal_entra import MsalEntraValidator

store = EntraAgentIdentitySecretStore(
    validator=MsalEntraValidator(
        tenant="<staff-tenant-uuid>",
        audience="api://alphaswarm-controller",
    ),
    resolvers=(
        EntraAgentIdentityCredentialResolver(
            credential_key=CredentialKey(
                service="alphaswarm-admin-to-cp",
                purpose="client_credentials",
            ),
            audience="api://alphaswarm-controller",
            blueprint_app_id=<blueprint app id>,
            agent_identity_id=<per-env agent identity object id>,
            fmi_path="alphaswarm-admin-prod",
        ),
    ),
)

alphaswarm_admin/integrations/broker.py::build_default_brokers does this automatically when ALPHASWARM_AUTH_AGENT_IDENTITY_ENABLED=true AND the three Agent Identity env vars are populated. When any of the fields are empty the broker falls back to the legacy env-only client_credentials path so local-dev sandboxes keep working.

Receiver-side recognition

alphaswarm_controller.auth.deps._payload_to_user extracts the RFC 8693 act claim and surfaces actor_kind="agent" plus actor_upstream_sub on the resolved AuthenticatedUser. Recognition is feature-flagged behind ALPHASWARM_AUTH_AGENT_TOKEN_RECOGNITION_ENABLED until the end-to-end path is verified — when off, every token resolves to actor_kind="user" and the legacy audit shape is preserved.

The monolith side (alphaswarm/api/routes/_internal_audit.py) logs the actor_kind + actor_upstream_sub on every persisted terraform_runs ingest call so the audit ledger stays correlatable with the Agent Identity that minted the token.

Identity on AWS ECS Fargate

When alphaswarm_admin runs on ECS Fargate (the ecs-fargate-control-plane module) two identities are in play, and they are orthogonal:

• AWS control — the /admin/platform/ecs/* surface calls AWS ECS + CloudWatch using the task's AWS IAM role, not Entra. The module grants that role a tightly scoped self-management policy (enable_self_management = true). No Entra token is involved in the AWS control path.
• Control-plane M2M — outbound calls to alphaswarm-cp /manage/* still need an Entra-minted token. ECS Fargate has no native OIDC issuer for the WIF JWT the two-step fmi_path exchange needs, so the ECS-hosted admin routes M2M through the controller's /auth/m2m/token shim by setting ALPHASWARM_AUTH_THROUGH_CONTROLLER=true. The controller (EKS-hosted, with a projected service-account token) holds the Agent Identity federation and mints on the admin's behalf.

The Agent Identity Blueprint + per-environment identities this module provisions therefore back the EKS-hosted control plane and any admin pod that can present a federated SA token. The module.alphaswarm_admin_agent_identity.agent_identity_env output emits the per-environment ALPHASWARM_AUTH_AGENT_* block ready to drop into a task definition or ConfigMap for those deployments.

Operator workflow

# 1. Pre-check (one-time): grant the Terraform-execution SP the Graph
# permissions the entra-agent-id skill lists.

# 2. Snapshot + apply (step-up MFA gated; AGENTS rule 42 + 52).
python scripts/identity/seed_admin_agent_identity.py --apply
alphaswarm-cli manage terraform apply \
    --workspace-id admin-entra \
    --spec-version-id <output from --apply>

# 3. Plumb outputs into CredentialResolver.
alphaswarm-cli credentials import \
    --service alphaswarm-admin \
    --purpose entra_agent_identity \
    --field blueprint_app_id=<output> \
    --field agent_identity_id_prod=<output>

# 4. Flip the feature flag on each deployment.
ALPHASWARM_AUTH_AGENT_IDENTITY_ENABLED=true
ALPHASWARM_AUTH_AGENT_BLUEPRINT_APP_ID=<output>
ALPHASWARM_AUTH_AGENT_IDENTITY_ID=<output>
ALPHASWARM_AUTH_AGENT_FMI_PATH=alphaswarm-admin-prod

Rollback

The Terraform module is gated by var.enabled; flipping it to false removes the per-environment Agent Identities + role assignments while keeping the Blueprint + BlueprintPrincipal in place for fast re-enable. The alphaswarm_admin BFF falls back to the legacy client_credentials path automatically (via EnvSecretStore at priority 100).

For the human-login path, the legacy Vite SPA at alphaswarm_admin_ui/ retains its Auth0 branch for 30 days post the refactor — set the ALPHASWARM_ADMIN_LEGACY_AUTH0_FALLBACK=1 feature flag to surface it.