Saltar al contenido principal

Entra ID as the AlphaSwarm staff user pool

Microsoft Entra ID is the first user pool for the managed AlphaSwarm platform. AlphaSwarm staff (engineers, operators, compliance, finance, auditors, SOC) sign in to manage.alpha-swarm.ai through the AlphaSwarm staff Entra tenant; Auth0 stays as the customer-facing B2C fallback and the documented degraded-mode entry path.

This page explains what the rollout does and why. The runbook that walks through how lives at how-to/entra-terraform-bootstrap; the long-form plan with phases + risks at docs/plans/entra-internal-tenant-rollout.md; and the architectural decision at ADR-011.

Why Entra, why now​

DriverDetail
MFA + Conditional AccessEntra carries the company's existing MFA + CA enforcement; staff already authenticate to it daily for Microsoft 365.
Audit centralisationSign-in logs land in the corporate SIEM via the existing Entra log stream; no separate Auth0 export to maintain.
Group-driven authorisationGroup membership in Entra → app-role claim on AlphaSwarm tokens. New hires onboard via a single HR-side group action.
No client secrets in CIGitHub Actions OIDC + federated credentials replace the old AZURE_CLIENT_SECRET repo secret.
Customer separationThe AlphaSwarm staff tenant is independent of every customer tenant. Customer tenants continue to flow through the EntraTenantLink B2B approval wizard (AGENTS rule 44).

What is under Terraform control​

  • 3 app registrations: alphaswarm-staff (login app), alphaswarm-manage-api (Resource Server), alphaswarm-ci-github (federated-credential-only).
  • 3 service principals with app_role_assignment_required = true on the manage API + CI app.
  • 7 app roles on the manage API: Admin, Operator, Auditor, Compliance, Finance, Engineer, Viewer.
  • 7 directory groups: AlphaSwarm-Admins, AlphaSwarm-Operations, AlphaSwarm-Auditors, AlphaSwarm-Compliance, AlphaSwarm-Finance, AlphaSwarm-Engineering, AlphaSwarm-SOC.
  • Group → app-role assignments mapping each group to one or more roles.
  • Federated credentials for GitHub Actions OIDC (per-environment
    • per-branch, never wildcards).
  • Named locations representing AlphaSwarm-trusted IP ranges (referenced by Conditional Access policies).

What is NOT under Terraform control​

  • Conditional Access policies. CA policies require an Entra ID P2 license + manual Security review. The Terraform module records policy display names as documentation; the verify helper queries Microsoft Graph at smoke-test time to confirm each named policy exists.
  • Group membership. HR + Security own membership through the Azure Portal (or Entitlement Management). Terraform owns which groups exist + what roles they confer; not who is in them.
  • Customer-tenant Entra integration. Customer tenants flow through the existing EntraTenantLink B2B wizard (AGENTS rule 44). This rollout is internal-only.
  • Privileged Identity Management (PIM). Tracked as future work in the rollout plan §7.

Token shape​

Every staff access token minted for api://alphaswarm-manage-api carries:

ClaimValue
isshttps://login.microsoftonline.com/{alphaswarm_staff_tenant_id}/v2.0
audapi://alphaswarm-manage-api
rolesone or more of Admin, Operator, Auditor, Compliance, Finance, Engineer, Viewer
groupsthe staff member's directory group object ids (security-only)
oidthe user's Entra object id (stable across renames)
tidthe AlphaSwarm staff Entra tenant id
preferred_usernamefirstname.lastname@<alphaswarm-domain>

The application reads roles to gate /manage/* routes; a staff member with no roles is treated as Viewer until promoted by an admin.

Provider-chain priority​

alphaswarm/auth/providers/__init__.py exposes select_provider_for_token which:

  1. Decodes the token's iss claim (no signature check).
  2. If iss matches the AlphaSwarm staff issuer, returns MsalEntraIdentityProvider.
  3. Otherwise falls back to get_active_provider() (Auth0 in production).

The manage.alpha-swarm.ai mounts use this selector instead of the bare get_active_provider() so internal-tenant tokens always route through MSAL first. Customer tokens (different iss) continue to land on Auth0.

Lifecycle​

PhaseWhat happensOwner
0. Pre-flightTenant id confirmed; bootstrap SP provisionedIdentity team
1. Plan + module landalphaswarm_entra_directory module shipped + plan-only validatedPlatform
2. Apply + smokeResources created; staff member tests loginPlatform
3. Cutoverauth_msal_priority set so MSAL wins for staffPlatform + Identity
4. Group onboardingHR populates the seven groupsHR + Security
5. CI cutoverAll workflows switch to OIDC federationDevOps

See the rollout plan for week-level scheduling, exit criteria, and rollback procedures.

How a staff member signs in​

Reading the audit trail​

Every Entra-side mutation lands in two places:

  • The Entra audit log (corporate SIEM via existing log stream). Captures app-registration changes, group-membership changes, CA-policy edits, admin consents.
  • The AlphaSwarm terraform_runs ledger. Captures every Terraform apply on the entra-internal stack with the operator who triggered it, the SHA of the rendered HCL, the previous + new state hashes, and whether the run succeeded or rolled back.

Auditors who need a full reconstruction window query both. The Phase 7 evidence-bundle export already includes terraform_runs rows in its deterministic archive.