Microsoft Entra ID (formerly Azure AD) SCIM 2.0 configuration
User Sync Configuration
Go to your Atlassian product and navigate to the User & Group Sync settings. Click Create Connector and choose SCIM 2.0.
You can change the Name of your SCIM 2.0 Connector. Copy the SCIM Base URL and the Bearer Token. We will need both later for the configuration of the IdP SCIM application.
Don't forget to save "Save and Return" your settings!
We will have a look at the 'Provisioning' and 'Sync' settings later. However, first, we create an Application (SCIM client) in your Azure portal.
Microsoft Entra ID (formerly Azure AD) SCIM Configuration
We assume that you already have SAML configured (or don't need it)
Create a new application
Open the Azure admin portal at https://portal.azure.com
Go to Microsoft Entra ID
Open the Enterprise applications menu
Add a new non-gallery application
Click the + New application button (plus button at the top)
Select Create your own application
Give the application a suitable name What's the name of your app?
Choose Integrate any other application you don't find in the gallery (Non-gallery) and
Click Create for the app to be added.
Configure application
Provisioning Mode
We will need to enable automatic provisioning.
Open the Provisioning menu, and change the provisioning option from Manual to Automatic.
Automatic
The Automatic option will let us configure user account provisioning to specify settings for admin credentials, mappings, starting and stopping, and synchronization. Otherwise (manual mode), e.g. user accounts would not be provisioned to your Atlassian instance.
Admin Credentials
Copy the tenant URL (your SCIM Base URL) and application secret (your Bearer token) for your User Sync Azure SCIM 2.0 Connector, as shown in the below screenshot.
Click the Test Connection button. If everything is working, you will get a notification
Save the configuration
Set the provisioning Status
Set the provisioning Scope to Sync only assigned users and groups (this will leave the provisioning status OFF).
Using the Scope Sync only assigned users and groups will give you better control over which users/groups will be synchronized or not when you have tens of thousands of Azure AD users.
Keep in mind, that you will need to assign users and/or groups later (see Assign users and groups). Otherwise, no users/groups will be provisioned.
Scope
If you change the Scope to Sync all users and groups, all your Azure AD users will be synchronized to your Atlassian instance. That's why we recommend using Scope Sync only for assigned users and groups.
Configure attribute mappings
Mappings control the user account attributes that flow from Azure to SAML SSO.
Under Provisioning settings, expand the Mappings drawer, then click Synchronize Azure Active Directory Users to customappsso.
Now you can change, add, or modify the attribute mapping to your needs.
Assign users and groups
Go to Users and groups and assign the users and groups that should be able to use the application and need provisioning.
Enable provisioning and save
Return to provisioning settings. Enable Provisioning & click save.
Keep in mind, that Microsoft Entra ID (formerly Azure AD) works on a 20-40-minute timer, for re-sync and non-immediate changes. If you need to test any changes or error corrections, it can take some time.
The initial Entra ID sync is triggered immediately after you enable provisioning. Subsequent syncs are triggered every 20–40 minutes, depending on the number of users and groups in the application. See the Provisioning summary report in the Entra ID documentation (https://learn.microsoft.com/en-us/azure/active-directory/manage-apps/check-status-user-account-provisioning#provisioning-summary-report).
Provision on demand
Entra ID allows provisioning users on demand, outside the fixed interval. Unfortunately, group memberships are not getting updated, neither if you select a group or a single user.
User Sync fine-tuning
Back to our SCIM 2.0 User Sync Connector. Let's have a look at the Provisioning Settings tab.
You can configure three main sections in the User Provisioning settings.
Always assign Users to certain Groups
This setting adds every synchronized user to the specified groups, such as an application access group like jira-users.
Group assignments are re-applied during every sync.
If you manually remove a user from one of these groups, they will be re-added in the next sync.
For more advanced use cases, you can use attribute mapping transformations to customize group assignments.
Copy Behaviour
Copy behavior is helpful when integrating User Sync into an existing Atlassian application (e.g., Jira or Confluence) with pre-existing data.
It identifies user records with the same username in a different application directory.
Relevant data such as group memberships, last login time, and user properties are copied to the User Sync directory.
This ensures smooth data migration while maintaining user information.
Attribute Mapping
Attribute Mapping allows you to map data from SCIM 2.0’s API to fields in your Atlassian application.
Use advanced functions to transform, filter, or modify incoming SCIM 2.0 data before applying it.
This enables greater flexibility when aligning external data with your Atlassian application's structure.
Group Provisioning
Group management in User Sync can be complex, especially since Atlassian does not differentiate between groups from SCIM 2.0 and locally created groups.
By default, User Sync considers SCIM 2.0 as the single source of truth for group memberships. This means:
If a user synchronized via SCIM 2.0 is assigned to a local group but not to that group in SCIM 2.0, the next sync will remove the local group membership.
To customize this behavior, you can adjust the settings to suit your use case:
Automatically assign groups to every synchronized user.
Ignore SCIM 2.0 groups and treat all groups as local.
Restrict imported groups from SCIM 2.0 using specific patterns.
Mixed group management: Manage some groups locally and others via SCIM 2.0.
These settings allow you to control how the plugin manages groups received from the Identity Provider (IdP):
Never Remove Users from These Groups
Control which groups User Sync will not remove users from, even if the group is not reported by SCIM 2.0.
Use this for groups you manually assign within Jira to ensure they remain intact.
Only Assign These Groups
Specify group names to whitelist groups from the IdP.
Only the groups listed here will be assigned to users; all other groups sent by the IdP will be ignored.
You can use regular expressions to match multiple group names (e.g.,
jira-.*matches all groups starting withjira-).
Never Assign These Groups
Specify group names to blacklist groups from the IdP.
Groups listed here will never be assigned to users; all other groups sent by the IdP will still be assigned.
Regular expressions are supported (e.g.,
jira-.*matches all groups starting withjira-).
Note: You can use both the whitelist (Only Assign These Groups) and blacklist (Never Assign These Groups) options together. In this case:
The plugin will first check the Only Assign These Groups field (whitelist).
Then it will apply the Never Assign These Groups field (blacklist) to exclude any matching groups.
Note
Using .* in "Never Remove Users From These Groups" and .* in "Never Sync These SCIM 2.0 Groups" will synchronize only user data from SCIM 2.0 while excluding all group memberships. This setup functions similarly to a "remote directory with local groups", as seen in Atlassian LDAP connections.
See https://wiki.resolution.de/doc/usersync/latest/knowledge-base/group-management-and-filtering-with-user-sync for more information.
Cleanup Behavior
The Cleanup Behavior allows you to configure what happens to users who were previously synchronized into your Atlassian application but:
Are deleted in SCIM 2.0,
Are no longer members of any required groups, or
Are dropped due to a transformation in the attribute mapping.
By default, the behavior is to disable these users, as recommended by Atlassian.
Connector Id and Directory
Below are key details related to the SCIM Connector:
Connector ID: A unique identifier used for REST API calls.
Directory ID: The directory ID used by the SCIM Connector, also applicable for REST API calls.
Logging and Profiling
The following setting can assist with troubleshooting:
Log Free Memory During Sync:
When enabled, this option displays the memory consumption and utilization during the sync process. You can view this information in the sync status logs.
