Review email domains before the migration

All of your users should have an email address from some domain, for example @atlassian.com. To keep your cloud site secure, you can migrate only users from trusted domains.

Before you migrate, you’ll need to:

Use the migration assistant to view the email domains that we found in your user directory
Review the domains and mark them as trusted. This is required to migrate.
Remove untrusted domains by deleting users or changing their emails to other domains

You need to mark all email domains as trusted to be able to migrate

This includes email domains for all users in your instance, even if you're only migrating specific projects or a subset of users. You can create and run migrations without reviewing and trusting email domains, but the migration will fail until you mark all email domains as trusted. This page explains how to remove untrusted domains from the list.

Review all email domains

You can review your email domains directly in the migration assistant or by using a CSV file. Here’s a sample Review all domains screen from the migration assistant:

A list of sample email domains found in user directory.

Bulk actions: If the number of domains is high, you can use the CSV file to update them in bulk. *This is not available in Bitbucket Cloud.
Search and filter: You can search for specific domains, change ordering by selecting the column names, or filter by decision status. This can help you find the domains that you need to review.
Domains: The list includes all domains found in your user directory, together with some details, such as the number of users from each domain, decision chosen, or action required for a specific domain.

Your goal is to mark all email domains as trusted. If there are domains you don’t trust, you need to get them removed from the list. Just marking them as not trusted won’t let you migrate.

Review email domains using the migration assistant

You can review your email domains in the Jira and Confluence migration assistants.

To review your email domains:

Open the Jira or Confluence migration assistant.
Access the Review all email domains screen:
1. If it’s your first migration, select the Review all email domains card on the home screen.
2. If it’s a subsequent migration, create or run a migration from the Migrations dashboard. A message will appear asking you to review email domains, where you can select Review all email domains.
When prompted, connect to your cloud site. This step is needed so we can display accurate information about users.
Select Begin assessing to find and assess domains from your user directory.
After the assessment is complete, review each email domain and mark it with one of the following decisions:

Decision	When do you make this decision?	What you need to do?
Trusted domain	You're sure that this domain is trusted and doesn’t have any unauthorized users.	You can continue with your migration.
Not trusted domain	You don’t recognize this domain and the emails created by this domain. You don’t trust the organization that creates emails using this domain.	You need to modify users from these domains and update their email addresses to other domains, or delete these users.
No decision made	You're not sure if the domain is trusted or not.	You need to check if the domain can be trusted. Once you have verified your domain, you can mark it as a Trusted domain and continue your migration.

Once you've marked all your domains as trusted, select Done to complete the domain review. If there are domains you can’t trust, read further below for information on how to remove them from the list.

Review email domains using a CSV file

You can also review your email domains in bulk by using a CSV file. This is useful if you have a high number of domains. Any changes you’ve made directly in the assistant will be reflected in the file. Likewise, you can make more changes after uploading the file back. *This is not available in Bitbucket Cloud.

To use the CSV file:

Access the Review all email domains screen. For detailed steps, see the section above.
Select Download CSV file.
Edit the file and mark each domain with a decision. Here are some details about the file:
- The CSV file includes all email domains found in your user directory.
- You can change the decision for each domain, but you can’t add or delete domains.
- The values are: NO_DECISION_MADE, NOT_TRUSTED, or TRUSTED.
When you’re ready, upload the CSV file back. The decisions from the file will be reflected in the assistant.

Once all your domain are marked as trusted, select Done to complete the domain review. If there are domains you can’t trust, read further below for information on how to remove them from the list.

Workaround: Trusting and clearing all domains at once

We recommend that you use the CSV file to review and trust your domains in bulk. Use this workaround at your own risk, only if you’re absolutely sure that you don’t have any suspicious domains.

If you really need to select all domains as trusted or clear all your selections, you can use these URLs in your browser bar. Again, check the warning above.

To select all domains as trusted:

<Base-URL>/rest/migration/latest/debug/email/trust-all-domains

To clear all selections:

<Base-URL>/rest/migration/latest/debug/email/remove-all-domain-rules

How you can remove untrusted domains

Unless you trust all email domains, you won’t be able to migrate.

When you don’t trust an email domain, you need to review users from such a domain in your Server or Data Center instance, and either delete them or change their email addresses to other domains. Once that’s done, the domains won’t appear on the list.

Use one of the following methods to modify user details to be able to unblock the migration:

User administration tools in Jira and Confluence Server or Data Center
Modify users from external directories

Use admin tools to modify users

Use the existing user administration tools in your Server or Data Center products to review all the users with untrusted domains. To do so, search for the untrusted domain and modify, disable, or delete the user.

Select Administration > User management.
On the next Users screen, search for the domain you don’t trust.
From the list that appears, select the user to be modified.
Edit the user details such as the email ID or username.

Modify users in your external directories

Take one of the following approaches to modify the users in your external directories:

Modify the emails of the users with untrusted domains to addresses of domains you trust
Delete the users with emails containing untrusted domains

Modify the emails of the users with untrusted domains to addresses of domains you trust

What to do?	Find the user’s location or origin and then modify their email ID. The possible locations can be LDAP, Crowd, or Jira.
What’s the result?	There is no change in user ownership of data or tracking of user actions within the product.
How do I do this?	For Jira, see Editing users. For Confluence, see Edit User Details. For Bitbucket, see Users and groups.

What to do?

Find the user’s location or origin and then modify their email ID. The possible locations can be LDAP, Crowd, or Jira.

What’s the result?

There is no change in user ownership of data or tracking of user actions within the product.

How do I do this?

For Jira, see Editing users.

For Confluence, see Edit User Details.

For Bitbucket, see Users and groups.

Delete the users with emails containing untrusted domains

Jira
What to do?	Find the user’s location or origin and then delete the user. The possible locations can be LDAP or Crowd.
What’s the result?	When you delete a user, the filters and dashboards owned by this user are also deleted, even if these filters or dashboards are shared with other users. Before you delete a user, you need to know the following: All issues reported by or assigned to the user you are attempting to delete are respectively hyperlinked to a list of the individual issues in the Issue Navigator. You can't delete a user from within Jira if you're using External User Management but you can deactivate the user. If however, this user is a Jira project lead, you can’t deactivate them. You need first to remove them in the project settings. Also, deactivating a user doesn’t mean they won't be migrated. Note that after migration, if such a user is mentioned in a comment or description, their ‘mention’ is turned into ‘@user,’ which is a broken tag, and they won't have product access. You can't delete a user from Jira if they’ve reported any issues, commented on any issues, or been assigned to any issues.
How do I do this?	See Deleting users.

Confluence
What to do?	Find the user’s location or origin and then delete the user. The possible locations can be LDAP, Crowd, or Jira.
What’s the result?	You won’t be able to track the user’s data ownership and actions within the product in Cloud. If you delete users from external directories (and synchronize), they become inactive in Jira. An inactive user becomes active in Cloud, does not have product access, but has site access.
How do I do this?	See Delete or Disable Users.

Confluence

What to do?

Find the user’s location or origin and then delete the user. The possible locations can be LDAP, Crowd, or Jira.

What’s the result?

You won’t be able to track the user’s data ownership and actions within the product in Cloud.

If you delete users from external directories (and synchronize), they become inactive in Jira. An inactive user becomes active in Cloud, does not have product access, but has site access.

How do I do this?

See Delete or Disable Users.

Bitbucket
What to do?	You can delete a user or group from Bitbucket's internal user directory, or the external directory from which Bitbucket sources users, such as an LDAP, Crowd or Jira Software.
What’s the result?	When a user or group is deleted from such a directory, Bitbucket checks to see if that user still exists in another directory: If the user or group does exist in another directory, Bitbucket assumes the administrator intended to migrate the user or group between directories and we leave their data intact. If the user or group does not exist in another directory, Bitbucket assumes the intent was to permanently delete them, and we delete the users permissions, SSH keys and 'rememberme' tokens. Before you delete a user, you need to know the following: In the case of users from an external directory (e.g. JIRA or LDAP) and internal users (from the internal directory), users or groups are preserved for seven (7) days. This includes: SSH keys GPG Keys Access tokens All user related data stored by apps.
How do I do this?	See Deleting users and groups.

Bitbucket

What to do?

You can delete a user or group from Bitbucket's internal user directory, or the external directory from which Bitbucket sources users, such as an LDAP, Crowd or Jira Software.

What’s the result?

When a user or group is deleted from such a directory, Bitbucket checks to see if that user still exists in another directory:

If the user or group does exist in another directory, Bitbucket assumes the administrator intended to migrate the user or group between directories and we leave their data intact.
If the user or group does not exist in another directory, Bitbucket assumes the intent was to permanently delete them, and we delete the users permissions, SSH keys and 'rememberme' tokens.

Before you delete a user, you need to know the following:

In the case of users from an external directory (e.g. JIRA or LDAP) and internal users (from the internal directory), users or groups are preserved for seven (7) days.

This includes:

SSH keys
GPG Keys
Access tokens
All user related data stored by apps.

How do I do this?

See Deleting users and groups.

How to review email domains if you have already migrated to cloud

If you’ve already migrated emails from untrusted domains to cloud, you can either:

Suspend users. This keeps their identity, but blocks the access.
Delete users. All references to deleted users will appear as Former user.

Learn how to remove or suspend users

Advanced: Database queries

You can use the following SQL queries to retrieve information about the number and details of users from all the domains that you marked as trusted.

Queries are for PostgreSQL, you might need to adjust them for other databases.
Queries don’t include customers from Jira Service Management, only regular users.

Number of users from trusted domains

select right(cwd_user.email_address, Strpos(Reverse(cwd_user.email_address), '@') - 1) as email_domain_cwd
     , td."DOMAIN_NAME" as email_domain_from_trusted_list
     , td."RULE" as decision_for_domain
     , count(*)
  from cwd_user
 inner join cwd_directory cd on cd.id = cwd_user.directory_id
  left join "AO_6FF49D_EMAIL_TRST_DMN" td on td."DOMAIN_NAME" = RIGHT(cwd_user.email_address, Strpos(Reverse(cwd_user.email_address), '@') - 1)
 group  BY 1, 2, 3
 order  BY 4 desc;

Details of users from trusted domains

select c.email_address as email
     , c.active as user_status
     , right(c.email_address, Strpos(Reverse(c.email_address), '@') - 1) as email_domain_cwd
     , td."DOMAIN_NAME" as email_domain_from_trusted_list
     , td."RULE" as decision_for_domain
  from cwd_user c
 inner join cwd_directory cd on cd.id = c.directory_id
  left join "AO_6FF49D_EMAIL_TRST_DMN" td on td."DOMAIN_NAME" = RIGHT(c.email_address, Strpos(Reverse(c.email_address), '@') - 1)
 order  BY 4 desc;

Next steps

When you’re ready, check your duplicate groups to know the problems they can cause and how you can mitigate them. Learn how to resolve duplicate group names

Was this helpful?

It wasn't accurate

It wasn't clear

It wasn't relevant

Still need help?

The Atlassian Community is here for you.

Ask the Community