Prerequisites & Important Notes
Before you begin configuring SCIM provisioning, please read through the following important notes and limitations carefully. Missing any of these is the most common cause of provisioning failures. For background on how SCIM provisioning works, see Microsoft's technical documentation on provisioning.
You cannot map attributes from an Entra Group to a SCIM Group. You must disable SCIM Group mapping in your provisioning settings (covered in Step 7b). Failing to do so will cause HTTP 404 errors that halt your provisioning cycle.
The urn:ietf:params:scim:schemas:extension:scim:2.0:EnterpriseUser:manager attribute is not supported due to bugs in Microsoft Entra's SCIM implementation. Do not map any attribute against it.
You must append ?aadOptscim062020 to the SCIM API URL when configuring the Tenant URL in Entra. Without this flag, features like AppRoleAssignments will not work.
The emails[type eq "work"].value and userName SCIM attributes must be lowercase. You will use ToLower() expressions when mapping these in Step 7.
If you have pre-existing users in Flowcase, ensure your attribute mapping mirrors the existing user information as closely as possible — especially unique identifiers such as email, UPN, and external IDs. Mismatched identifiers can cause duplicate users or overwritten data. Test with Provision on demand (Step 8a) before running a bulk provision.
Department names sent via SCIM must already exist in Flowcase — the SCIM API will not create new departments. You can view your department names via the Flowcase UI or the Countries & Departments API. If you have duplicate department names across countries, you must also map a country attribute (countryCode OR countryName, but never both).
Create Enterprise Application
You need to register a new enterprise application in Microsoft Entra that will serve as the interface to the SCIM API. This application controls which users are synced to Flowcase and how their attributes are mapped.
Navigate to Enterprise Applications
- In your Entra portal, search for "Enterprise" in the search bar.
- Select "Enterprise applications" under the Services section.
Create a Non-Gallery Application
- Click "New application" / "Create your own application" near the top-left of the page. A side panel will open.
- Enter a name for your SCIM application (e.g., "Flowcase SCIM").
- Choose "Integrate any other application you don't find in the gallery".
- Click "Add" to create the application.
Connect to SCIM API
Now configure your enterprise application to communicate with the Flowcase SCIM API.
Set Provisioning Mode
- Open your enterprise application and click "Provisioning" in the left-hand panel.
- Under "Provisioning Mode", select "Automatic".
Configure Admin Credentials
https://your-company.flowcase.com/api/scim/v2?aadOptscim062020
- Set the Tenant URL to the URL generated above.
The ?aadOptscim062020 flag tells Entra to run in compatibility mode. Without it, features such as AppRoleAssignments will not work.
- Set the Secret Token to your API key in this exact format:
token="YOUR_API_KEY_HERE"The token must be wrapped as token="API_KEY" including the double quotes. The API key must have International Manager access.
- Under Settings, set Scope to "Sync only assigned users and groups".
- Click "Test Connection" to verify the configuration.
Create App Roles
App Roles in Entra map to user roles in Flowcase. These roles govern the level of access a user is granted. You need to create an App Role for each Flowcase role you want to assign. See the Roles section of the SCIM API documentation for the authoritative list.
Available Flowcase Roles
| Role Value | Description |
|---|---|
external | External user with limited visibility |
limited_access | Limited access user |
consultant | Standard consultant user |
internationalmanager | International manager with global access |
referencemanager | Reference project manager |
countrymanager | Country-level manager |
departmentmanager:office:<country-code>:<dept-name> | Manager for a specific department (e.g., departmentmanager:office:NO:Engineering) |
departmentmanager:dept:<country-code>:<dept-name-stripped> | Manager for a specific department, with spaces stripped (e.g., departmentmanager:dept:NO:SoftwareEngineering) |
departmentmanager:custom_tag:<category-euid>:<tag-euid> | Manager for a specific custom tag (e.g., departmentmanager:custom_tag:region:north) |
The departmentmanager role uses a different format to the other roles, because it targets either an office/department or a custom tag depending on how the role is formatted.
To target a department, use departmentmanager:office:<country-code>:<department-name>, where <country-code> is the ISO 3166-2 country code for your desired department.
If your department name contains a space, some providers (such as Microsoft Entra) do not allow you to push the role with the space included. In this case, trim the department name of all whitespace (StripSpaces in MS Entra) and use the departmentmanager:dept:<country-code>:<department-name-stripped> format instead.
Navigate to App Registrations
- In the Entra portal, search for your enterprise application name in the search bar.
- Under the "App Registrations" category in the results, click on your application (the one tagged "Application").
Create Each App Role
- Click "App Roles" in the left-hand panel.
- Click "Create App Role".
- Enter a Display Name and Description for the role.
- Set Allowed member types to Both (Users/Groups).
- Set the Value to exactly match a Flowcase role name from the table above (e.g.,
consultant). - Ensure the "Enable this app role" checkbox is ticked.
- Click "Apply".
The Value field of each App Role must exactly match a valid Flowcase role name. These are case-sensitive. For department managers, use the format departmentmanager:DepartmentName.
Repeat the steps above for each Flowcase role you need to assign to your users.
Assign Users & Groups
To synchronize Entra users to Flowcase via SCIM, you must assign them (directly or via groups) to your enterprise application.
If you assign an Entra group, only users directly in that group will be provisioned. The assignment does not cascade to nested/child groups.
Assign Users or Groups
- Navigate to your enterprise application in the Entra portal.
- Click "Users and Groups" in the left-hand panel.
- Click "Add user/group".
- Click "None Selected" under Users and groups and select the users or groups you want to provision.
- Click "None Selected" under Select a role and choose the App Role to assign.
- Click "Assign".
- Repeat if you need to assign additional roles to the same user or group.
Configure Attribute List
Before mapping attributes, you need to define the SCIM attribute list that your enterprise application will use.
Navigate to the Attribute List Editor
- In your enterprise application, go to Provisioning.
- Under Mappings, select "Provision Azure Active Directory Users".
- Scroll down and tick "Show advanced options".
- Click "Edit attribute list for customappsso".
Required Attributes
Add the following attributes to your attribute list:
| SCIM Attribute | Type | Requirements |
|---|---|---|
id | String | Primary Key and Required |
userName | String | Required |
roles | String | Multi-Value |
emails[type eq "work"].value | String | Required |
You can then add any additional SCIM attributes you need. See the full list of supported SCIM attributes for reference.
Do not add urn:ietf:params:scim:schemas:extension:scim:2.0:EnterpriseUser:manager. This attribute is not supported.
Your attribute list should look something like this:
Once done, click "Save" at the top-left of the screen.
Map Attributes & Disable Group Support
Mapping user attributes from Entra to SCIM is one of the most important steps in this guide. Please ensure you take each requirement into account when constructing your mapping.
7a: Map Entra User Attributes
After saving your attribute list, you will be back on the Attribute Mapping screen. Now you need to create mappings between Entra user attributes and SCIM user attributes.
Required Attribute Mappings
The following mappings are required and must be configured exactly as shown:
| Entra Attribute | Type | Expression | Target SCIM Attribute | Match | Precedence |
|---|---|---|---|---|---|
userPrincipalName |
Expression | ToLower([userPrincipalName], ) |
userName |
Yes | 1 |
mail |
Expression | ToLower([mail], ) |
emails[type eq "work"].value |
Yes | 2 |
isSoftDeleted |
Expression | Switch([isSoftDeleted],, "False","True","True","False") |
active |
— | — |
appRoleAssignments |
Expression | AppRoleAssignmentsComplex([appRoleAssignments]) |
roles |
— | — |
department |
Direct | — | urn:ietf:params:scim:schemas:extension:enterprise:2.0:User:department |
— | — |
Optional / Reference Attribute Mappings
The following are common optional mappings. Your Entra instance may have different attribute names — adjust as needed:
| Target SCIM Attribute | Entra Attribute | Type |
|---|---|---|
externalId | employeeid | Direct |
displayName | Join(" ",[givenName],[surname]) or displayName | Expression or Direct |
addresses[type eq "home"].locality | city | Direct |
phoneNumbers[type eq "work"].value | telephoneNumber | Direct |
title | jobTitle | Direct |
preferredLanguage | preferredLanguage | Direct |
locale | locale | Direct |
urn:...:flowcase:2.0:User:countryCodeOR urn:...:flowcase:2.0:User:countryName |
country |
Direct |
Adding a Mapping
- Click "Add New Mapping" at the bottom of the Attribute Mapping screen.
- Set the Mapping Type (Direct, Expression, or Constant).
- For Expressions, enter the expression in the Expression field.
- Set the Target Attribute to the SCIM attribute.
- For required attributes, set the Match and Matching Precedence values.
- Click "OK".
Repeat for all attributes you want to map.
If you have duplicate department names, you must map a country attribute. Use either countryCode (ISO 3166-2) or countryName, but never both. Using both will cause an HTTP 400 error.
The userPrincipalName and mail mappings must use the ToLower() expression. Flowcase requires lowercase emails and UPNs.
If you have pre-existing users in Flowcase, take the time to ensure that unique identifiers such as UPN, email, department, and external ID are the same in Entra as they are in Flowcase. Mismatched identifiers can cause duplicate user profiles or overwrite existing data.
7b: Disable SCIM Group Support
Entra enables SCIM Group support by default. The Flowcase SCIM API does not support SCIM Groups and will return HTTP 404 Not Found errors that halt your entire provisioning cycle. You must disable this.
- In your enterprise application, go to Provisioning.
- Under Mappings, select "Provision Azure Active Directory Groups".
- Set "Enabled" to "No".
- Click "Save".
Provision Users
Now that everything is configured, you can begin provisioning users. We recommend testing with a single user first before starting bulk provisioning.
8a: Test with Provision On-Demand
Before provisioning all users, test with a single user to verify your configuration is correct.
- In your enterprise application, go to Provisioning.
- Click the "Provision on demand" button.
- Search for and select a user or group in the "Select a user or group" field.
- Click "Provision".
After a few moments, the results screen will show the outcome of the provisioning attempt. Review this carefully to ensure all attributes were mapped correctly.
After provisioning a test user, log in to Flowcase and verify the user profile looks correct — check their email, name, department, role, and any other mapped attributes.
8b: Start Bulk Provisioning
Once you are satisfied that on-demand provisioning works correctly, you can start the full provisioning cycle for all assigned users.
- On the Provisioning screen, click "Start provisioning".
Provisioning will run continuously in cycles (approximately every 40 minutes). You can monitor progress via the provisioning logs.
Viewing Provisioning Logs
- On the Provisioning screen, click "View provisioning logs".
The Provisioning Logs screen shows the status of each provisioning attempt:
Deleting Users
When a user is soft-deleted in Microsoft Entra (sent to the recycle bin / AccountEnabled set to false), one of two things will happen depending on your mapping:
- If you do not have a mapping between
isSoftDeletedandactive, the user will be deleted from Flowcase on the next provision cycle. - If you do have a mapping between
isSoftDeletedandactive(as recommended in Step 7), the user will be deactivated in Flowcase instead.
Thirty days after a user is deleted in Entra, they are permanently deleted. At this point, Entra will send a DELETE request to the SCIM API to permanently delete the user in Flowcase. You can also manually delete a user permanently at any time during the 30-day window.
For more information, see Microsoft's provisioning documentation under the section "Configure your application to delete a user".