How Confluence users and groups are migrated

The Confluence Cloud Migration Assistant lets you migrate your Confluence users from Server or Data Center to Cloud. You can migrate users on their own or with space data.

User migration options

With the Confluence Cloud Migration Assistant, you have two options for migrating your users and groups:

Improved user management in admin.atlassian.com

We’ve been rolling out changes to user management that may affect your migration experience. From your organisation at admin.atlassian.com, if the Users list and Groups list are under the Directory tab, you have the improved user management experience. This means that the users and groups across sites will be merged under the organisation.

User data migrated with a subset of users

When you choose Migrate users related to the selected spaces, we will still migrate some user data connected to the spaces you are migrating. This is to make sure that mentions, comments, and page history stay active.

User data that will be migrated every time includes:

• full name

• username (discarded after migration)

• email address

We'll only migrate this information for users who have permission to access the spaces that you're migrating. We'll not give these users product access. They will appear in your cloud site user list. However, if the group they're added to has been granted permission to access this space, it will also get migrated along with the user.

If you choose to migrate users later, their product and group access will be updated.

Also, if you choose not to migrate users and groups and you have a space permission granted by a group that doesn’t exist in cloud, the Confluence Cloud Migration Assistant will not migrate the respective space permission. To avoid this scenario, we recommend that you create the specific group in the cloud site before migration.

How user and group data is linked

User accounts in cloud are identified by unique email addresses.

When using the Migration Assistant to migrate, a new account will be created in your cloud site for each of your users. If an email address already exists in your cloud site, it won’t be migrated. Instead, we will link all data connected to that user to their account in cloud.

If you have users that already exist in your destination cloud site, then the following will occur:

• if a user has product access in Cloud, but has disabled status in your Server site, they will continue to have product access in cloud after migration

• if a user does not have product access in Cloud, but is enabled and has product access in your Server site, they will be granted product access through the migration process

Your groups will also be linked to existing groups in cloud (if they are already there). Group linking is identified by group name and could result in permission escalation during migration. Make sure you check your groups before migrating. Learn how user groups and permissions are migrated

Re-migrated groups and possible permission escalation

When you re-migrate a group to cloud, we won’t update its existing memberships or the group itself. We only add new users that appeared in the group since the last migration. This can result in permission escalation. For example:

1. You migrate an Admins group to cloud.

2. Later, in Server or Data Center, you remove some users from this group, and re-migrate the group.

3. The changes in memberships won’t be reflected in cloud, because we keep what was already migrated intact. The removed users will still be members of the cloud’s Admins group.

4. However, if you add new users to the group, we’ll add them to the cloud’s group. That’s because it’s an addition of new memberships, not a modification of existing ones.

You should take that scenario into consideration when doing phased migrations. It might happen that you migrate a project or space thinking it can only be viewed by Admins, but in reality – the cloud’s Admins might have more users than its server counterpart.

Always assume that what was already migrated will stay as-is, without further updates.

Whenever you need to make changes to groups in Server or Data Center, manually make the same changes to their equivalent cloud groups.

How users from your knowledge base are migrated

If you use Confluence as the knowledge base for Jira Service Management (formerly Jira Service Desk), your Jira Service Management users may also be migrated along with your Confluence users. This will happen if you can see your Jira Service Management users in the cwd_user table in Confluence.

Pre-migrating users and groups to reduce downtime

If you migrate your users before your space data, you will save time on migration day. This is because the Migration Assistant will not need to re-migrate those users. This is particularly helpful if you are migrating all of your users. 

Learn how to migrate Confluence users and groups in advance

Test migrations

For a test migration or User Acceptance Testing (UAT), we recommend that your test cloud site isn't part of the production organization. This is to ensure smooth migration of the relevant users and groups. All sites within a single organization would share the same users and groups.

Deleted or inactive users and directories

Any deleted users or users in inactive directories that are referenced in your Confluence data will appear as Former user after migration. If you need to migrate the references to these users, reactivate them (or the directory) before migrating.

Users with disabled status in your server instance will be migrated as active but without any product access or group membership. This means they will not be counted as active Confluence users for billing purposes. Learn how users are managed in cloud

Permissions, groups, and product access

When you migrate users, they’ll be added to their groups when they get to cloud. The first time you migrate, you will need to review and approve group permissions. When you approve group permissions any active users in your cloud site will be added to your bill.

Global settings and global site permissions are not migrated with this tool. You’ll need to set these manually before or after migration.

Learn how user groups and permissions are migrated

Email notifications

We won’t send an invitation to your users even if you choose to give your users access during the migration. To invite your users you can choose to send an invitation from the Administration space after you have migrated, or send a link for them to log in themselves.

Billing changes in Cloud

Confluence Cloud is subscription-based and billed on a per-user basis. If you plan to migrate your users, make sure you check the licensing options or calculate the cost with our pricing calculator. By default, Cloud subscriptions are billed on a monthly basis however you can choose annual billing if you prefer. 

Third-party identity providers

If you're intending to use an external identity provider in cloud, make sure you've read the guidance on migrating users and groups. Learn more about user migration strategies

We recommend synchronizing your identity provider with Confluence before migrating. This is to make sure that your users and groups are up to date before you transfer any data.