Configure Microsoft Entra ID integration via SCIM

If you use Microsoft Entra ID, you can connect your directory to Systam Studio. After that, you no longer need to create Systam Visit hosts manually. This guide explains how to enable automatic user synchronization with Microsoft Entra ID.

Note: This extension is a paid add-on and requires activation. Contact our support team at support@systam.fi.

Once the setup is complete, Microsoft Entra ID can:

• create users, meaning hosts, in Systam Studio
• update user details in Systam Studio, such as primary workspace, name, email addresses, phone numbers, and active status
• delete users permanently from Systam Studio when access is no longer needed
• keep user data synchronized between Microsoft Entra ID and Systam

Read more about Entra ID and provisioning: What is automated app user provisioning in Microsoft Entra ID.

Important things to note

Prerequisites

Before you start, you need the following:

• a Microsoft Entra tenant
• a Microsoft Entra ID user account with permission to configure provisioning, for example Application Administrator, Cloud Application Administrator, Application Owner, or Global Administrator
• a Systam organization account at app.systam.io and a user account with Organization Owner permissions

Other notes

• Organization Owners are protected. Users assigned the Organization Owner role in Systam are protected. If these users are updated or deleted through SCIM, the provisioning logs will show a 403 Forbidden error.
• Soft delete is not supported. Systam does not support suspended or soft delete status. When a user is removed from synchronization or disabled in Entra ID, Systam deletes the user account permanently. If the user is later added back to synchronization, they are created again as a new user.
• Matching logic. If a user with the same email address already exists in Systam, provisioning links the existing account to the tenant’s SCIM data. Otherwise, Systam creates a new user.

Step 1: Plan the provisioning setup

• Learn how the provisioning service works.
• Define who is included in provisioning.
• Define which data is mapped between Microsoft Entra ID and Systam.

Step 2: Prepare in Systam Studio

Preparation

1. Open Systam Studio and go to Extensions → Microsoft Entra ID. Select Enable.
2. Copy the values shown in Studio for Tenant URL and Secret Token. You will need them for the Entra ID setup.
3. You can also enter your organization’s Tenant ID if you want. This helps with troubleshooting.

Set the synchronization options

In Systam Studio, choose how employees are added to workspaces. You can sync hosts either to one workspace only (primary workspace) or to all workspaces. If you choose all workspaces, employees will still always have a primary workspace. Choose the option that fits your organization before you start provisioning.

• Primary workspaces

Sync hosts to one workspace only.

• All workspaces

Sync hosts to all workspaces.

Note: If you later change the setting to Primary workspaces, hosts are not removed automatically from other workspaces.

Step 3: Add Systam to Microsoft Entra ID

1. Sign in to the Microsoft Entra admin center as an administrator.
2. Go to Identity → Applications → Enterprise applications.
3. Select New application.
4. Select Create your own application.
5. Give the application a name, for example Systam.
6. Select Integrate any other application you don't find in the gallery (Non-gallery).
7. Select Create.

Step 4: Define who is included in provisioning

With the Microsoft Entra provisioning service, you can define who is provisioned to the application. You can limit provisioning either by assignments made to the application or by user or group attributes. If you use application assignments, you can define users and groups with this guide: Assign users and groups to an application.

• Start small. Test first with a small set of users and groups.
• When the provisioning scope is set to assigned users and groups, you can roll out the setup in steps.

Step 5: Enable automatic synchronization

In this section, you configure the Microsoft Entra provisioning service to create, update, and delete users in Systam.

5.1 Admin Credentials

1. Open the Provisioning tab in the Systam application in Entra ID.
2. Go to Manage → Provisioning and set Provisioning Mode to Automatic.
3. Enter the values shown in Systam Studio:
   • Tenant URL
   • Secret Token
4. Select Test Connection to verify the connection.

If the test fails:

• make sure the token was copied correctly
• check that there are no extra spaces

5.2 Attribute mappings

Systam uses a limited set of Microsoft Entra ID user attributes for provisioning. These mappings are configured on the Provisioning tab of the Systam enterprise application.

Identity and status

userName

• A unique identifier for the user in Systam.
• The value comes from the source attribute you define for the userName mapping, usually a sign-in name such as UPN or email address.

active

• Defines whether the user account is active in Systam.
• The value is based on the expression defined in the active mapping.

Contact details

Systam only uses contact details from Microsoft Entra ID when the type is set to work or other. Other types are rejected and may cause provisioning to fail for that user.

• Email addresses
  • The attribute mapped to emails[type eq "work"].value becomes the user’s primary email address in Systam.
  • A work-type email address is required. If the user does not have a work-type email address, provisioning fails for that user.
• Phone numbers
  • If you choose to map phone numbers, phoneNumbers[type eq "work"].value becomes the user’s primary phone number in Systam.
  • A work-type phone number is required if phone numbers are mapped.
  • If you do not want to manage phone numbers in Systam, leave phone numbers completely unmapped.
  • If you map phone numbers, make sure all users in scope have a work-type phone number.

In practice:

• the work email address is always the user’s primary email address in Systam
• when phone numbers are mapped, the work phone number is the user’s primary number in Systam

Example mapping configuration

Step 6: Define the primary workspace

Each employee must have a primary workspace. The primary workspace is used as a default value in different functions. There are three ways to define it.

6.1 Set one primary workspace for all users

If you want to assign only one main workspace to hosts, this is the most reliable option.

Continue from Step 5 by adding one more custom attribute, urn:ietf:params:scim:schemas:extension:systam:2.0:User:primaryWorkspace, which defines the user’s primary workspace.

Add the attribute to the schema

1. Open the Provisioning tab for the Systam application in Entra ID, then open Attribute Mapping.
2. Select Provision Microsoft Entra ID Users.
3. Scroll to the bottom of the page and select Show advanced options.
4. Select Edit attribute list for Systam (or the application name you chose).
5. Add a new attribute at the end of the list:
   • Name: urn:ietf:params:scim:schemas:extension:systam:2.0:User:primaryWorkspace
   • Type: string
6. Select Save.

Map the workspace to a constant value

1. Return to the Attribute Mapping view.
2. Add a new workspace mapping:
   • scroll to the bottom of the list and select Add New Mapping
   • Mapping type: Constant
   • Constant Value: enter the value that Systam will use, for example systam
   • Target attribute: select the custom attribute urn:ietf:params:scim:schemas:extension:systam:2.0:User:primaryWorkspace
3. Select OK.
4. Select Save.

Set it in Studio

1. Open Systam Studio and go to Extensions → Microsoft Entra ID.
2. Scroll down to Define primary workspace attribute mappings.
3. Click Add configuration and enter the constant value you defined earlier.
4. Select which workspace should be the primary one and save the changes.
5. Done. Continue to Step 7.

6.2 Set the primary workspace based on an Entra group

If you want to assign the main workspace based on an Entra group, do it like this.

1. Define which groups are in scope for provisioning and save the group IDs.
2. Open Systam Studio and go to Extensions → Microsoft Entra ID.
3. Scroll down to Define primary workspace group mappings.
4. Click Add configuration and enter the provisioned group ID in the first field.
5. Select which workspace should be the primary one.
6. Repeat until every provisioned group is mapped to the correct workspace.
7. Save the changes.
8. Done. Continue to Step 7.

6.3 Set the primary workspace based on an attribute

If you want to assign hosts very precisely to different workspaces based on a specific attribute, such as office location or country, use this option.

This setup can be used together with Entra group mapping. The integration checks the attribute first and only then checks the Entra group data. The group value is ignored if the primary workspace is found from the attribute.

Continue from Step 5 by adding one more custom attribute, urn:ietf:params:scim:schemas:extension:systam:2.0:User:primaryWorkspace, which defines the user’s primary workspace.

Add the attribute to the schema

1. Open the Provisioning tab for the Systam application in Entra ID, then open Attribute Mapping.
2. Select Provision Microsoft Entra ID Users.
3. Scroll to the bottom of the page and select Show advanced options.
4. Select Edit attribute list for Systam (or the application name you chose).
5. Add a new attribute at the end of the list:
   • Name: urn:ietf:params:scim:schemas:extension:systam:2.0:User:primaryWorkspace
   • Type: string
6. Select Save.

Add the workspace mapping

1. Return to the Attribute Mapping view and review the default mappings.
2. Add a new workspace mapping:
   • scroll to the bottom of the list and select Add New Mapping
   • Source attribute: select the Entra ID attribute you want to use for the user’s primary physical location or workspace, for example department, officeLocation, or an extension attribute
   • Target attribute: select the custom attribute urn:ietf:params:scim:schemas:extension:systam:2.0:User:primaryWorkspace
3. Select OK.
4. Select Save.

Set it in Studio

1. Open Systam Studio and go to Extensions → Microsoft Entra ID.
2. Scroll down to Define primary workspace attribute mappings.
3. Click Add configuration and enter a value that may come from the attribute you mapped earlier.
4. Select which workspace should be the primary one and save the changes.
5. Repeat until every value you want has been mapped.
6. Done. Continue to Step 7.

Step 7: Test and start synchronization

Test a single user

• Select Provision on demand.
• Select a test user.
• Run the action.

Enable automatic synchronization

• Set Provisioning status to On.
• Select the scope you want to use.

Monitor the status

• Check the provisioning logs.
• Monitor the provisioning status.

More information

• Managing user account provisioning for Enterprise Apps
• What is application access and single sign-on with Microsoft Entra ID?