Skip to main content

Microsoft Entra SCIM Integration

This guide explains how to configure Microsoft Entra provisioning for Specmatic Insights SCIM.

It uses the required mapping:

  • Provision userName (email) and active.
  • Groups are supported by Insights, but not required for this setup.

Current Limitations​

  • Insights roles and identity types are not provisioned directly through Entra SCIM user/group attributes.
  • After group sync, role and identity type mapping is configured in Insights from the Collaborators page.

For the user-facing meaning of those role and account type combinations, see Role Permissions.

For SCIM protocol details, see SCIM Reference.

Prerequisites​

  • Org admin access to Specmatic Insights
  • Admin access to Microsoft Entra admin center
  • A SCIM token from Insights:
    1. Go to Settings -> Identity Access
    2. Enable SCIM
    3. Select Rotate Token
    4. Copy the one-time token value

Use a non-gallery app. This is required for custom SCIM endpoint configuration and custom attribute mappings.

  1. In Entra admin center, go to Identity -> Applications -> Enterprise applications.
  2. Select New application.
  3. Select Create your own application.
  4. Enter an app name (for example, Specmatic Insights SCIM).
  5. Choose Integrate any other application you don't find in the gallery (Non-gallery).

After creation, Entra opens a Get started with application provisioning wizard. Continue from that wizard.

Step 2: Configure provisioning endpoint​

  1. In the Get started with application provisioning wizard, select Get started (or open Provisioning from the app menu).
  2. Set Provisioning Mode to Automatic.
  3. Set Tenant URL to:
https://insights.specmatic.io/<orgId>/scim/v2
  1. Set Secret Token to the SCIM token from Insights.
  2. Select Test Connection and save.

Step 3: Configure user provisioning mappings (required)​

  1. In Provisioning -> Mappings, open Provision Microsoft Entra ID Users.
  2. Keep Target Object Actions enabled for create, update, and delete (default).
  3. Remove default mappings you do not want to send.
  4. Keep only these target attributes:
    • userName
    • active
    • externalId (recommended)
  5. Configure userName source to an Entra email identity:
    • Recommended: userPrincipalName
  6. Keep active mapped from Entra account state.
  7. Save mappings.

Required: Keep userName and active mappings. externalId is optional but recommended. Remove all other user attribute mappings in Entra for this integration.

Mapping guidance​

  • userName must be an email address for Insights.
  • Insights currently supports only this required mapping for this flow; extra profile attributes must not be sent.
  • active controls user lifecycle (provision/deprovision state).
  • externalId is also supported. If you choose to map it, use an immutable Entra identifier that does not change over time (recommended: objectId).

Example required mapping​

Source attribute (Entra)Target attribute (SCIM)
userPrincipalNameuserName
Switch([IsSoftDeleted], , "False", "True", "True", "False") (default active expression)active
objectIdexternalId (recommended)

Step 4: Configure scope and assignments​

  1. In Provisioning settings, set Scope to:
    • Sync only assigned users and groups (recommended)
  2. Go to Users and groups in the enterprise application.
  3. Assign only the users (and optionally groups) that should be provisioned.

Step 5: Group provisioning (optional)​

If you only want group lifecycle provisioning:

  1. In Provisioning -> Mappings, open Provision Microsoft Entra ID Groups.
  2. Disable group provisioning or remove group mappings.
  3. Save.

If you want SCIM groups as well, keep group provisioning enabled and follow group schema/behavior from SCIM Reference.

Step 6: Map synced SCIM groups to Insights role and identity type​

After Entra sync starts and groups appear in Insights:

  1. In Insights, open Settings -> Collaborators -> SCIM Groups.
  2. Select one or more synced groups.
  3. Apply one of these mappings:
    • Mark as User (Human)
    • Mark as Admin (Human)
    • Mark as User (Service account)
    • Mark as Admin (Service account)

This mapping controls the effective org membership role and identity type for users hydrated from those groups.

Use Role Permissions to choose the right target combination for each synced group.

Step 7: Start provisioning​

  1. Return to Provisioning.
  2. Select Start provisioning.
  3. Monitor View provisioning logs for create/update/deprovision operations.

Validate behavior​

Expected behavior with this required mapping:

  • Entra creates/updates users with userName and active.
  • If mapped, externalId is synced and should remain stable for identity correlation.
  • Deprovisioning is reflected through active=false (or delete based on Entra policy).
  • Group sync is optional, but required if you want role/identity assignment through group mapping.
  • Once groups are synced, admins complete role/identity mapping in Insights from Collaborators -> SCIM Groups.

Troubleshooting​

  • 401/403 from SCIM endpoint:
    • Verify bearer token from Insights and re-test connection.
  • 400 on create/update:
    • Verify userName resolves to a non-empty email-like value.
    • Verify active mapping is present.
    • If externalId is mapped, verify it resolves to a non-empty immutable identifier (recommended: objectId).
  • Users not syncing:
    • Ensure scope is assigned users and groups and assignments exist.
    • Check Provisioning logs in Entra for mapping errors.

References​