Currently, User Sync is available for Jira Server, Jira Data Center, Confluence Server, Confluence Data Center, Bitbucket Server, and Bitbucket Data Center.



We'll talk about different group-related concepts in this Article.

  • Group Transformations
    Here you can apply rules (simple search & replace or regular expressions) if you want group names from the IdP to be transformed into something different in the Atlassian Server or Data Center Application.

  • Group management
    Learn how to assign local groups for each synced user and make sure that they are not removed during a sync

  • Only Sync Users that are part of specific groups
    If you do not want all your users synchronized but only the ones who are members of specific groups.


Most of the group-related settings can be adjusted in the Provisioning settings tab of a User Sync Connector.
Required groups can be configured in the first tab. Just click Edit on the connector you want to configure.

Group Transformations

You can transform group names from the IdP using Group Transformations.
That means a group name is read from the IdP via API and then the transformation is applied before the group name is used in the Atlassian Server or Data Center application.

With UserSync 2.0 we support new ways of transforming groups (and other attributes). 
This can be anything from a simple checkbox in our UI, a "search and replace" on group names, a powerful regular expression, or a Groovy script for advanced use cases. 

To setup group transformations, go to User Sync and click Edit on the connector.
On the Provisioning Settings tab, scroll down to the Attribute Mapping table and click Edit for the Groups row.



Next, click Show Details to show all the options.




There are some built-in transformations already, applied in the same order as displayed in the UI.
You can enable one or more by turning each switch on:

  1. To Lower Case which turns "A gRoup Name" into "a group name"
  2. Regular Expressions allow to apply regular expressions or simple search and replace operations.
  3. Split Attribute can split multiple groups of one attribute into multiple, e.g. like "one,another" to "one" and "another" group.
  4. Add Constant which can add constant values to your groups

In the following section we will demonstrate what you can do with Regular Expressions because it is the most important feature here.

Regular Expression based transformations

Simple Search and Replace

Regular expressions also support simple search and replace operations for group names.
Activate the Regular Expression toggle and click Edit:



In Regular match expression (1), enter the regular expression (or the search term).
In Replacement expression (2) enter the replacement.
With (3) you decide what happens if there is no match and none of the rules can be applied:

  1. Fail the authentication if no transformation applies will produce an error for this user during a sync and the sync will fail for this user
  2. Do not use any of the attribute's value ... will not sync any group if no rule applies
  3. Do not use the specific value will only skip the group which does not match any of the expressions



The following is a simple example that replaces the jira-software group name with jira-users.
If a group name does not match the rule, the group will not be renamed.
With the Regex Replacement Tester, you can see if your rule applies.

(As you can see here, jira-software is replaced with jira-users)

Simple Regular Expression examples

^(.*)$ to idp-$1  (adds idp- as a prefix to all groups)


^global-(.*)$  → $1 (removes global- prefix)

Filter/ Synchronize Groups matching certain patterns only

Please also take a look at the Group Management chapter further below. It also provides some options to filter groups with specific names or patterns.
These might be more suited for your needs, depending on the exact requirements.


Use the "What should happen if ..." feature in combination with a regular expression to only assign groups with a specific name pattern.
For instance, if you only want all groups starting with jira- to be synchronized into the Atlassian application, add a regex like 

^(jira-.*)$ → $0

in combination with "Do not use the specific value of the attribute's values for this user if no transformation applies. If there is only one value, the attribute is dropped!"


Group management

In the group management section you can define

  • from which groups users are never removed (1)
  • which groups are being synced (2) and which are not (3)


The settings are:


  1. Never Remove Users From These Groups
    Specify which groups (or regular expressions matching groups) are never removed from existing users.
    In a scenario with some groups coming from the IdP and some local groups which have been manually assigned to the user within the Atlassian application, you must enter the local group- names or patterns here.
    Without this, the next sync would remove all groups not existing on the IdP, since it is considered the single source of truth.

  2. Only Assign These ... Groups
    If you add group names (or patterns) here, the app will only assign groups matching these and ignore all other groups.
    Essentially this is an IdP group allow list.
    You can also use regular expressions (e.g: to match multiple group names at once, like jira-.* for everything that starts with jira-)

  3. Never assign These ... Groups
    If you add group names (or patterns) here, the app will never assign groups matching these and assign all other groups not matching.
    Essentially this is an IdP group block list.
    You can also use regular expressions (e.g: to match multiple group names at once, like jira-.* for everything that starts with jira-)


If you are looking for the option to add one or more groups to every user being synced, use the first option on the Provisioning Settings tab

Group management Examples

Some groups from IdP, some groups locally

Group Management/  Only Assign These ... Groups: ^jira-.*$

  • This will synchronize all groups starting with jira- from the IdP. 

Group Management/ Never Remove Users From These Groups: ^((?!jira-users).)*$ 

  • keep all existing
  • groups that don't start with jira-users
    So if you have a local group called my-group for example, it would be kept

Always add the local group jira-users to every synced user

Always Assign Users to Certain Groups: jira-software-users

  • this will add the jira-users group to every user during a sync


Only Sync Users That Are Members Of At Least One Specific Group

To only sync users who are member of at least one group from a list of group- names or patterns, you can add these in the first tab of the connector settings
Required ... Groups: Only Sync Users When They Are Member of the ... Groups Below on the ... specific settings tab. 


Click the pen symbol to add something in here. You can also use regular expressions.
Please always refer to the group names used in your identity provider.



The example will only sync users who are members of the group jira-software-users. You could also add an expression like jira-.* to sync every group starting with jira-.
The user can still be a member of other groups, but the name/ expression provided here will decide if the user is synced in the first place.
Please refer to the Group Management part above again to configure more group management options.


Complex Examples

Multiple Groups

Let's assume you have the following requirements:

  1. You only want to sync users who are member of any Jira group on your IdP (i.e. Okta)
    All those groups have the naming format <countrycode>-<application>-<role>, for example:

    de-jira-developers
    de-jira-administrators
    de-jira-users
    fr-jira-users
    uk-jira-developers

    At the same time, you want to map these names to the respective original Jira groups (jira-developers, jira-users, jira-administrators).

  2. You have many other Groups in Okta that you would also like to have in Jira.
    In order to not confuse them, you decide to prefix all of the groups with "aad-".

  3. You still want to be able to use local groups in Jira (and you have many historic ones, not existing on the IdP yet)
    To know what is a local group and what is not, you can recognize that it's everything not starting with aad.
    The members of the jira-users, jira-developers and jira-administrators group are managed on the IdP.

Solution:

  1. We configure the following transformation patterns:
    ^.*-(jira-.*)$ → $1   (achieves requirement no. 1)



    ^(.+)$ → aad-$1 (achieves adding aad- in front of every other group, requirement no. 2)



  2. Groups mandatory to sync/ Required Groups
    Here we need to refer to the names as in the IdP, Okta in our examples.
    We only want to sync users who are at least a member of one of the following groups:

    de-jira-developers
    de-jira-administrators
    de-jira-users
    fr-jira-users
    uk-jira-developers

    These settings can be found on the first tab:








  3. Group Management

    Only the following groups from the IdP should be assigned to a user. Here we need to refer to the transformed group names already.
    So if you've transformed any names into something else, use these instead. 

    For our example it would be

    aad-.* 
    jira-users
    jira-administrators
    jira-developers




    Additionally, all groups starting with aad- should never be removed, thus the following regular expression is used
    ^((?!aad-).)*$
    To add that pattern, you need to click on Create option ... after pasting it to the field and before confirming with OK