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 Entra ID (formerly Azure AD), Okta and G-Suite), 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 User Sync-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 Entra ID (formerly 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.

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

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 Other Settings 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.