Skip to main content

SCIM Provisioning

There are now two SCIM 2.0 surfaces in the platform, both mounted at /scim/v2/*:

  • alphaswarm_auth (src/alphaswarm_auth/api/routers/scim.py) is the canonical, tenant-scoped SCIM server going forward — every operation runs under the caller's TenantContext (RLS-partitioned by workspace_id), and the sole IdP adapter is Entra ID (AuthSettings.provider: Literal["msal_entra"]; see ADR-0017). Auth0 is not involved in this path. Authorization requires the canonical scim:write scope (or the admin:cluster super-scope), resolved the same way as every other alphaswarm_auth endpoint (bearer token -> get_current_user -> resolved scopes) — there is no separate SCIM-specific auth stack.
  • The alphaswarm monolith (alphaswarm/api/routes/scim.py) still exposes its own /scim/v2/* surface for Auth0 Actions or scheduled Auth0 jobs, as described below. It remains wired and functional, but new SCIM integrations should target alphaswarm_auth.

Monolith surface: security​

Enable SCIM with:

ALPHASWARM_AUTH_SCIM_ENABLED=true
ALPHASWARM_AUTH_PROVIDER=auth0
ALPHASWARM_AUTH_REQUIRED=true

Authentication is Bearer-only. AlphaSwarm accepts either:

  • a JWT validated against the configured OIDC issuer with audience ALPHASWARM_AUTH_SCIM_M2M_AUDIENCE (or ALPHASWARM_AUTH_M2M_AUDIENCE), or
  • a long random static token whose SHA-256 digest is stored in ALPHASWARM_AUTH_SCIM_BEARER_TOKEN_HASH.

Do not store the raw token in the repository.

Monolith surface: resource mapping​

  • SCIM User maps to users.
  • SCIM Group maps to teams.
  • SCIM Group.members maps to memberships with scope_kind="team".

Create, patch, replace, deactivate, and group membership operations emit security audit events through alphaswarm.auth.audit.emit_audit_event.

Monolith surface: Auth0 integration​

The alphaswarm_platform/terraform/modules/auth0_identity module creates:

  • the AlphaSwarm SPA application,
  • the AlphaSwarm API audience and scopes,
  • an M2M client grant for SCIM and Auth0 sync,
  • default alphaswarm-viewer and alphaswarm-admin roles,
  • a post-login Action that calls /_internal/auth0/sync and injects AlphaSwarm tenancy claims.

For direct enterprise SCIM, point the upstream IdP or Auth0 automation at https://<alphaswarm-host>/scim/v2.