1. Betterworks
  2. Betterworks
  3. NextGen

SCIM User Provisioning - Microsoft Entra (NextGen)

Contents

Overview
Requirements
Generate your Betterworks API token
Setup Instructions
User deactivation and reactivation
Limitations
Troubleshooting
 

Overview

Betterworks supports System for Cross-domain Identity Management (SCIM) 2.0, allowing organizations to automate user provisioning through their identity provider (IdP).

By integrating Microsoft Entra ID (formerly Azure Active Directory) with Betterworks, administrators can automatically create, update, and deactivate user accounts in Betterworks based on changes made in Microsoft Entra ID. This reduces the need for manual user management and helps keep employee information consistent across both systems.


Requirements

To configure SCIM 2.0 provisioning with Microsoft Entra ID, you will need:

  • Betterworks Super Admin access to generate an API token.
  • Microsoft Entra administrator access to configure the integration.
  • Your organization's Betterworks environment URL (e.g. https://app.betterworks.com).


Generate your Betterworks API token

  1. Log in to Betterworks as a Super Admin.
  2. Navigate to  Admin → Integrations → Betterworks API.
  3. Generate an API token to use when configuring the SCIM connection in Microsoft Entra ID.
  4. Store the token securely, as it will be required during setup.

Note: The API token carries Super Admin-level permissions and is not restricted to SCIM operations. Treat it as a sensitive administrator credential and ensure it is stored securely.


Configuring SCIM 2.0 in Microsoft Entra ID

Step 1: Create the enterprise application

1. Log in to the Microsoft Entra admin center.
2. Navigate to Identity → Applications → Enterprise applications
3. Select Create your own application
 

image-20260828-020447.png

4. Name it (e.g. “Betterworks SCIM 2.0”) and select “Integrate any other application you don't find in the gallery (Non-gallery)”

image-20260828-020538.png

5. Click Create.


Step 2: Start automatic provisioning

  1. Open the newly created Betterworks application in Microsoft Entra ID.
  2. Select Provisioning from the left-hand navigation menu.
image-20260828-021125.png

       3. On the Get Started page, click Connect your application.

.             
Step 3: Configure the SCIM connection

Complete the following fields:

Field Value
Tenant URL Your Betterworks environment URL followed by /scim/v2
Secret Token

Here, paste the API token generated in Betterworks.

Note: Enter the API token without the Bearer prefix. Microsoft Entra ID automatically adds this when authenticating requests.
  1. Click Test Connection to verify that the connection is successful.
  2. Once the connection has been verified, click Create.
image-20260828-021457.png


 

Step 4: Configure attribute mappings

The attribute mappings determine which employee information is synchronized from Microsoft Entra ID to Betterworks.

image-20260828-022224 (1).png
image-20260828-022903 (1).png
  1. Navigate to Provisioning → Attribute Mapping.
  2. Select Add Attribute Mapping
  3. Edit the attribute mappings to include only the below attributes supported by Betterworks.
Betterworks SCIM attribute Microsoft Entra ID attribute
userName User's email address or User Principal Name (UPN)
name.givenName Given name
name.familyName Surname
emails[type eq "work"].value Email address
title Job title
active Account active status

Remove any additional default attribute mappings that are not supported by Betterworks, such as department, manager, address and phone number.

  1. Click Save.


Step 5: Assign users

Once the SCIM connection and attribute mappings have been configured, users can be assigned to the Betterworks application in Microsoft Entra ID.

Note: It's recommended to start with a small group of users to confirm that provisioning works as expected before assigning the rest of your organization. Since deactivation is supported, changes to application assignments can also affect existing Betterworks accounts.

  1. Open the Betterworks enterprise application.
  2. Select Users and groups from the left-hand navigation menu.

    image-20260828-023053.png
  3. Click Add user/group.

    image-20260828-023311.png
    You will see a warning about groups.
     
  4. Under Users, click None Selected.
  5. Select the users you want to provision to Betterworks.

    image-20260828-023526.png
     
  6. Click Select to confirm your selection.
  7. Click Assign to complete the assignment.


Step 6: Enable automatic provisioning

After assigning users, automatic provisioning can be enabled.

  1. Navigate to the application's Provisioning page.
    image-20260828-024550.png
  2. Set Provisioning Status to On.
  3. Click Save. Entra runs an initial sync cycle and then continues on its regular incremental schedule, typically every 20–40 minutes.
  4. Return to the Provisioning overview page.
  5. Open Mappings and ensure that group provisioning is disabled.
    image-20260828-024943.png
  6. Click the Provisioning Status toggle to On, then click Save at the top.
    image-20260828-025140.png
  7. Go to the Provisioning tab and click on Start provisioning at the top of the page and Yes to the confirmation box.
    .                                   image-20260828-025230.png

 

User deactivation and reactivation

Deactivating users

Microsoft Entra ID can send deactivation requests to Betterworks when a user's account is disabled or they are removed from the application's provisioning scope.

Once the deactivation has been processed, the corresponding Betterworks account is deactivated.

Reactivating users

If a previously deactivated user needs to regain access to Betterworks, ensure that their Microsoft Entra ID account is active and that they are assigned to the Betterworks enterprise application.

Check the provisioning logs to confirm that the user's account has been synchronized successfully, and verify their account status in Betterworks.

If the account remains inactive, contact Betterworks Support for assistance.


Limitations

The following limitations apply to Betterworks SCIM 2.0 provisioning:

  • Groups and departments: Group and department provisioning is not supported.
  • Manager relationships: Manager information cannot be synchronized through SCIM.
  • Additional employee attributes: Fields such as employee number, hire date and custom fields are not supported.
  • Bulk operations: SCIM bulk operations are not supported.
  • Password synchronization: SCIM cannot be used to synchronize user passwords.
  • SCIM /Me endpoint: This endpoint is not supported.
  • HRIS integrations: SCIM provisioning and Betterworks HRIS Integrations cannot be used simultaneously within the same organization. Existing HRIS Integrations must be disabled before enabling SCIM provisioning.


Troubleshooting

If you encounter issues when configuring or using SCIM provisioning, review the following.

API connection fails

If the connection test is unsuccessful:

  • Confirm that the Betterworks API token is valid.
  • Verify that the Tenant URL matches your organization's Betterworks environment and includes /scim/v2.
  • Ensure that the Secret Token field contains the API token without the Bearer prefix.

A user fails to provision

If an individual user cannot be provisioned:

  • Confirm that the user is assigned to the Betterworks enterprise application.
  • Verify that the user's email address is correct.
  • Ensure that the user's Job title field is populated in Microsoft Entra ID.
  • Review the user's provisioning errors in Microsoft Entra ID.

Reviewing provisioning logs

Microsoft Entra ID provides provisioning logs to help identify synchronization errors.

  1. Open the Betterworks enterprise application in Microsoft Entra ID.
  2. Navigate to Provisioning.
  3. Open Provisioning logs.
  4. Review the provisioning activity and any error messages associated with affected users.

If the issue persists, contact Betterworks Support with the relevant error message and details of the affected user.