Directory Management

At which directory position the User Sync directory should be set?

The User Sync directory should be set to first directory position. This directory position is important because Jira handles users in relation to the position of the users directory. A user with the same username can exist in multiple directories. When having the same user in multiple directories, only the user of the higher positioned directory is used for Jira. This involves all user specific attributes and group relationships. If a user exists in multiple directories and you would delete (not deactivate) the user from the first directory, the user account from the second directory would be automatically used.

How to handle identical users in the internal directory?

No user changes are required, if you move your User Sync directory to the first position. Through the higher position, the user is automatically used for Jira and the internal user is still existent in the database, but hidden in the Jira users view.

When users get deactivated by the Identity Provider, I noticed that only users from the User Sync directory are deactivated, but not the users from the internal directory. Is this expected?

Yes this is expected. User Sync only handles users in the User Sync directory. Through the higher position of the internal directory, the user is automatically used for Jira and the internal user is still active in Jira. If you move your User Sync directory to the first position, the activity status of the users in this directory take effect and the deactivation of users by the Identity Provider should work like expected.

Upgrade considerations for existing SAML Single Sign On installations

User Sync vs. User Creation and Update via SAML

If you are using a supported Identity Management System (currently Azure AD, Okta and GSuite), we recommend to use User Sync instead of User Creation and Update via SAML.

  • User Sync allows on the fly-updates during login:
    You can enable User creation and update from UserSync-Connector (part of the SAML SSO configurations). This starts a single user update via User Sync (Just-in-time, but not via SAML) when logging in through SAML Single Sign On. This ensures that your users are always up to date after Single Sign On.
  • Scheduled synchronization provides proactive provisioning and de-provisioning of users and groups on regular intervals (sync). Users exist before the first login.
  • Using User Sync for provisioning circumvents several limitations:
    • Groups from G Suite can be updated using User Sync, but not with SAML.
    • User Sync allows updating groups from Azure AD while group names are not available as SAML attributes.
  • The configuration is simplified as no SAML attribute mapping for full name, email address and groups needs to be configured on the Identity Provider.
  • User Sync creates a separate user directory per connector, so the origin of every user is visible in the user management.


What minimum permissions the user and token must have?

Log in to your Okta organization as a user with administrator privileges. API tokens have the same permissions as the user who creates them. User Sync requires the permissions "View users" and "View groups", which are available for all administrator roles.

Do I need to worry about any API rate limits?

Automatic API rate limit detection is currently supported for the Azure- and Okta connector.


For Okta, User Sync provides a Rate Limit Threshold in percent. The default value is 70%.
The returned HTTP headers of an API request contain values for

X-Rate-Limit-Remaining The maximum number of requests you're permitted to make per rate limit window (i.e. hour)
X-Rate-Limit-Limit The number of requests remaining in the current rate limit window

from which the current rate limit ratio is calculated. If it is below the threshold defined in the settings, User Sync will continue querying the API.
If it isn't, it will wait until shortly after the time is reached sent by the API via the X-Rate-Limit-Reset header value (the time at which the current rate limit window resets).

Adjusting the rate limit threshold will hence have an influence on how often User Sync pauses during the sync.
Please note, that Okta preview instances usually come with lower limits than production instances.

Should you still experience issues, please try to gradually increase the Minimal time per user (under Advanced Connector Settings) in the User Sync connector configurations.
This slows down the sync process in millisecond per user and should help to avoid exceeding the limitation (because user sync could be too fast).

Read more about Okta rate limits here:


User Sync checks whether the Retry-After value returned by the API is set and retries at the time specified to cope with rate limits.