Directory Management

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

The User Sync directory should be set to the first directory position.

This position is crucial because Jira handles users based on the order of directories. A user with the same username can exist in multiple directories, but Jira will always prioritize the user from the higher-positioned directory. This affects all user-specific attributes and group memberships.

If you delete (not deactivate) a user from the first directory, Jira will automatically use the user account from the next directory.

How to handle identical users in the internal directory?

No changes to users are required if you move the User Sync directory to the first position. With the higher directory position:

• The User Sync directory's user will automatically take precedence in Jira.
• The internal directory user remains in the database but is hidden in the Jira user view.

Why are users from the internal directory not deactivated when deactivated by the Identity Provider?

This behavior is expected.

• User Sync only manages users in the User Sync directory.
• If the internal directory is in a higher position, Jira will still consider the internal directory user as active.

Solution: Move the User Sync directory to the first position. This ensures that the activity status of users managed by the Identity Provider takes precedence, and deactivation works as 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 (e.g., Entra ID (formerly Azure AD), Okta, or G Suite), we recommend using User Sync instead of the legacy User Creation and Update via SAML method.

Advantages of User Sync

1. On-the-Fly Updates During Login

   • You can enable User Creation and Update from the User Sync Connector within the SAML SSO configuration.
   • This triggers a just-in-time single-user update (handled by User Sync, not SAML) during SAML-based Single Sign-On.
   • Users are always up-to-date immediately after login.

2. Scheduled Synchronization

   • Proactive provisioning and de-provisioning of users and groups occur at regular intervals.
   • Users are provisioned before their first login.

3. Circumventing Limitations

   • G Suite: Groups can be updated using User Sync, but not through SAML.
   • Entra ID (Azure AD): Group names are unavailable as SAML attributes but can be updated with User Sync.
   • Simplified Configuration: No need to configure SAML attribute mappings (e.g., full name, email, or groups) in the Identity Provider.

4. Improved Visibility

   • User Sync creates a separate user directory per connector.
   • The origin of each user is visible in user management.

Okta

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 connectors.

Okta

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. You will find the setting via Okta Specific Settings > Rate Limit Threshold.

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 Slowdown Delay in the User Sync connector configurations. This pauses the amount in milliseconds after each user to reduce load during the sync. Be aware that this increases the sync duration.

To access that option, you need to type the support on your keyboard while in the edit mode of the connector.

A popup will show the following message:

The Support tab contains a few more options, and the one we are looking for:

Change the setting Slowdown Delay (as needed) and save the configuration.

Read more about Okta rate limits here: https://developer.okta.com/docs/api/getting_started/rate-limits#okta-api-endpoints-and-per-minute-limits

Azure

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.