Skip to main content

SCIM setup — Microsoft Entra ID (Azure AD)

Azure AD is a Certified vendor. The integration is listed in the Azure AD app gallery once the submission package (§8 pre-GA) is approved — until then admins set up the integration manually using the steps below.

Prereqs​

  • MOD tenant on a plan with scim_enabled = true.
  • Azure AD admin access (Application Administrator role minimum).
  • A SCIM bearer token from MOD Dashboard → Admin → SCIM tab.

Steps​

1. Create the Enterprise Application​

  1. Azure portal → Microsoft Entra ID → Enterprise applications.
  2. New application → Create your own application.
  3. Name: "MOD".
  4. Type: "Integrate any other application you don't find in the gallery (Non-gallery)".
  5. Create.

2. Configure provisioning​

  1. The new app → Provisioning → Get started.
  2. Provisioning Mode: Automatic.
  3. Admin Credentials:
    • Tenant URL: https://api.modtechlabs.com/scim/v2
    • Secret Token: the plaintext bearer from MOD's modal.
  4. Click Test Connection.
  5. Expected: "Testing connection to MOD. The supplied credentials are authorized to enable provisioning."

3. Attribute mappings (default)​

Azure AD's default mappings work for v1. Adjust if your tenant uses non-default user attributes.

Azure AD attributeMOD attribute
userPrincipalNameuserName
givenNamename.givenName
surnamename.familyName
mailemails[primary].value
objectIdexternalId
accountEnabledactive

For role-via-group: see MOD Dashboard → Admin → SCIM Mapping.

4. Enable provisioning​

  1. Settings → Provisioning Status: On.
  2. Save.

5. Assign users + groups​

  1. Users and groups → Add user/group.
  2. Expected: Within ~40 min (Azure AD's first sync cycle), MOD receives POST /scim/v2/Users for each assigned user.
  3. Provisioning logs (Provisioning → Provisioning logs) show every request + response for debugging.

Known Azure-AD-specific behaviours​

From the vendor compat matrix:

  • PATCH style — Azure AD sends {op: "replace", value: {dict}} with no path. MOD's _apply_partial handles this. Note that for this no-path style it applies active, userName, and externalId; changes to display name or email come through on the next full PUT/upsert rather than the no-path PATCH.
  • objectId as externalId — a UUID (e.g. 90a40df3-4f15-4d39-8a8b-09a3eb35cba6). MOD stores it opaquely; don't try to parse it as a username.
  • Initial sync cadence — first sync after enabling provisioning is ~40 min in Azure AD. Subsequent syncs are typically every 40 min. You can force-sync with "Start provisioning" but expect a brief delay.

Troubleshooting​

symptomlikely causefix
Provisioning state: "Quarantined"Test Connection failed multiple timesVerify bearer + Tenant URL; re-test
SchemaInvalid in Azure logsMOD response body wasn't SCIM-shapedCheck MOD activity log — surface the response shape; usually a 5xx from MOD
Repeated 429sPlan's rate limit too tightRaise plans.scim_per_token_burst for this plan

Screenshots​

See CORE/docs-site/docs/assets/scim-azure-ad-*.png.