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.
  
  

• Local group management
  The section Local group management helps you when you want some groups being managed/synchronised from the IdP and another set of groups you want to assign/ manage locally in the Atlassian Server or Data Center Application.
  
  

• Only Sync Users that are part of specific groups
  If you do not want all your Users synchronised but only the one's which are part of specific groups.

All group related options can be adjusted in the advanced configuration section of the User Sync Connector.
On a connector click Edit, scroll to the bottom and click Show Advanced Options

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.

This is essentially search and replace. Either simple or quite powerful by using regular expressions.

You can add multiple transformation rules and even decide to remove groups from a user not matching any of these.
The Drop Groups that don't match checkbox will enable that option.

Each transformation rule can be tested as shown in the screenshot below.

Also, you can simply search for a specific group name to do a replacement, using ( ) to filter which part of the group name you want to keep:

Transformation examples

Simple Search and Replace

You can transform group names without using regular expressions.

In "Regular Expression" you type the group name from the IdP and in "Replacement" the group name you want to keep with the transformation.

Simple Regular Expression examples

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

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

Filter/ Synchronize Groups matching certain patterns only

Use the "Drop Groups that don’t match" 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-.*)$ → $1 and check "Drop Groups that don’t match"

Group management

IdP group management

Here you configure in detail how the plugin deals with groups loaded from the Identity Provider. The two settings are:

• Only Assign these Groups
  If you add group names here, the plugin will only assign these from the IdP and drop all others that the IdP sends for a particular User.
  Essentially this is a IdP group whitelist.
  You can also use regular expressions (e.g: to match multiple group names at once, like jira-.* for everything that starts with jira-)

• Never assign these Groups
  If you add group names here, the plugin will never assign the groups from the IdP but assign all others that the IdP sends for a particular User.
  Essentially this is a IdP group blacklist.
  You can also use regular expressions (e.g: to match multiple group names at once, like jira-.* for everything that starts with jira-)

Usually you only use one of the options and not necessarily both at the same time.

Local group management

Here you control how the plugin adds/ removes groups that you may have assigned locally to the user.

• Always assign these Groups
  All groups listed here will be added to every User that the Connector syncs.
  That can be useful to provide application access to users, for example by putting everyone automatically into the jira-users group.

• Keep these Groups
  All groups listed here or any regular expression that matches them are considered groups a user already had and that are being kept.
  You can still remove these groups manually via the default user management in your Atlassian application.

Group management Examples

Some groups from IdP, some groups locally

Idp group management/  Only Assign these groups: ^jira-.*$

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

Local group management/ Keep these Groups: ^((?!jira-users).)*$ 

• keep all existing local 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 jira-users group

Always assign these groups: jira-users - will add jira-users to every synchronised user

Only sync Users that are part of specific groups

To only sync users being member of one or more specific groups, you can add group names or regular expression in 
Required Groups under Groups mandatory to sync a User section:

The example will only sync users who are member of any group starting with jira- on the IdP.
The user can still be 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 adjust further group management. 

Complex Examples

Multiple Groups

Lets assume you have the following requirements:

1. You only want Users synchronised that are part of any Jira groups on your IdP (Azure AD). 
   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
   
   These groups you'd like to all map to respective original Jira groups (jira-developers, jira-users, jira-administrators)
   
   

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

3. You still want to be able to use local groups in Jira (and you have many historic ones).
   To know what is a local group and what is not, you can recognise that it's everything not starting with aad- and not the jira-users, jira-developers & jira-administartors group.

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 manatory to sync
   jira-users
   jira-administrators
   jira-developers
   

   

   
   
   

3. IdP Group Management
   aad-.* 
   jira-users
   jira-administartors
   jira-developers
   
   All those groups assignments from the IdP are honoured. Note that you here already need to use the transformed name i.e. all azure groups start with "aad-"
   
   

4. Keep these Groups
   ^((?!aad-).)*$
   

   

   
   All Groups not starting with aad- will be left alone by the plugin & not removed from the Azure User.