Prepare nested groups for Cloud migration

This page outlines the challenges associated with migrating nested groups to Atlassian Cloud and how you can avoid them. In summary, nested groups aren’t supported in Atlassian Cloud, but you can keep the nested structure in your external user directory and use the flattened one in Cloud.

What are nested groups?

Nested groups are subgroups of other groups. They’re typically used for permission inheritance or to recreate the company’s structure in your external user directory.

Here’s an example of a nested structure that you can have in your external user directory:

• Parent group: Atlassian

• Nested groups: Design, Engineering, Grads

The main benefit of a nested structure is the permission inheritance. The members of nested groups will not only receive permissions from their direct groups, but also from the parent group. This is commonly used to easily grant or revoke permissions. In such a structure, you can just add a user to a single nested group (and have them inherit memberships and permissions from all parent groups) instead of adding them to each group individually.

How are nested groups synced to Cloud?

Atlassian Cloud doesn’t support nested groups and most Cloud identity providers don’t allow syncing a nested structure into any SaaS application.

When you sync your users to Atlassian Cloud over SCIM without flattening, the following happens.

• Groups: All groups are synced, but the nested structure isn’t preserved. The groups live on the same level.

• Group memberships: Users lose memberships in the parent groups. The permission inheritance isn’t respected.

There might be some differences in how different providers approach syncing, so treat this as an example. You can read the details for each provider in the table further below.

Flattening nested groups

To solve this problem, nested groups can be converted into a flat structure while keeping all effective group memberships.

When you flatten nested groups, the following happens:

• Groups: All groups become separate groups, and live on the same level.

• Group memberships: Users are added to each group individually, without relying on permission inheritance. For example, if they were a direct member of a nested group and inherited membership in the parent group, after flattening they will be a direct member of both these groups. This is an ongoing process that’s also applied to any new users and groups.

This can be done manually (by removing the nested structure in your external user directory) or by using an automated process, commonly referred to as a flattener. A flattener will automatically recreate memberships from your nested structure in the flat structure, by adding users to all the required groups.

Determine how to flatten nested groups when migrating to Cloud

You have two ways of flattening nested groups:

• Automatically flatten the nested structure

• Remove the nested structure in your user directory

If you don’t flatten the nested structure in any way, your users will lose some of their memberships after syncing.

Automatically flatten the nested structure

Automatically flattening the nested structure by using an identity provider or syncing method that supports it has the following benefits:

• You can keep the nested structure in your external user directory, where you most likely manage users and add them to groups.

• You use the flat structure, with all effective group memberships preserved, in Atlassian Cloud.

• Any changes you make to the nested structure in your user directory are synced to the flat structure in Cloud, which makes granting and revoking permissions easy, because you handle it like you did before – in the nested structure.

Here’s a summary of how different identity providers handle nested groups:

If your identity provider doesn’t support flattening of nested groups, you’ll need to either switch to one that does or drop the nested structure in your user directory. Learn which identity providers we support

Removing the nested group structure

Removing the nested structure requires you to convert your nested groups into separate groups manually. You then need to add all users to the groups they need individually.

You might want to choose this approach for the following reasons:

• Most Cloud IdPs don’t support syncing nested structures into SaaS applications

Even if Atlassian Cloud supported nested groups, you won’t be able to sync them from your external directory, because most IdPs don’t support that. You might encounter the same problem when trying to sync with other applications unless they’ve built their own custom flatteners.

• Nested groups aren’t a necessity

Nested groups can be convenient, especially to mirror your company structure and grant the appropriate permissions, but switching to a provider that supports flattening might mean more work than flattening your groups manually. This is usually the case for small organizations that use nested groups out of convenience rather than necessity.

When to sync nested groups during migration

In most cases, you will follow these steps, but they might depend on the migration strategy you’ve chosen:

1. Sync your external directory with a Server or Data Center product to update your users.

2. Use a Migration Assistant to migrate users and groups to Atlassian Cloud.

3. Sync your external directory with Atlassian Cloud. Users from your external directory will be mapped to the migrated users by matching their email addresses.

Learn how to determine your user migration strategy

More information and support

We have a number of channels available to help you with your migration.

• for migration planning information, visit the Atlassian Migration Program website

• for technical issues or if you need more support with strategy and best practices, get in touch with our support team

• for peer advice, ask the Atlassian Community

• for expert guidance, work with an Atlassian Partner