Planning for bulk email address changes on managed accounts

Summary

Specific changes, such as a rebranding or merging of companies, would prompt a need to update the email addresses for a large number of end users. The email address changes should also be applied to the end user’s Atlassian Accounts in the cloud to allow them to continue accessing their data using the new email address. Some common use cases

• We are merging with another company, and the email address domain needs to be changed (that is. user@companyA.com → user@companyB.com)

• We are switching the email address format of our end users. (that is. abc123@company.com → firstname.lastname@company.com )

Solution

Background

Product access and historical data in cloud products are not linked to the Atlassian Account or the email address. Each Atlassian Account is identified by a unique (immutable) ID and an email address. If an Atlassian Account’s email address is updated, the end user can continue to use their existing product access and data with the new email address.

• An email address can only be used by one Atlassian Account in the Atlassian cloud at a time. To update an account's email address, ensure that the new email address is not already linked to another Atlassian Account.

• Admin and identity provider (IdP) initiated email address changes to Atlassian Accounts can only be performed when the email address domain(s) are verified, and the Atlassian Accounts are claimed within a single organization.

• When configured with Atlassian Access, the identity provider updates email addresses in the Atlassian cloud using SAML-SSO and user provisioning.

• SAML-SSO is configured by following the Configure SAML single sign-on with an identity provider guide.

• User Provisioning is configured by following the Understand user provisioning guide.

• Managed accounts that are linked to the identity provider via provisioning are locked for editing on Atlassian side. The Atlassian Account email address can only be updated via the identity provider.

Prerequisites

1. The source and target email address domain(s) should be claimed in the same Atlassian cloud organization.

2. Clean up the Atlassian Accounts that may be holding the target email address.

   • Generate a list of target email addresses to be utilized (ie. taken from the identity provider)

   • “Navigate to the "Admin Console” at https://admin.atlassian.com

     • Open the Managed accounts administration for your organization.

     • Export the accounts.

   • Review whether any Atlassian account is already using the target email addresses. Compare the managed accounts export with the target email addresses list from the identity provider.

     • If the target email address is already used by another Atlassian Account, change the email address of the conflict account to something else (ie. targetemail_FREE@domain.com ).

     • Update the email address using the Managed Accounts admin interface or the Set Email Organization API. After the change is completed, these accounts can be deactivated/deleted.

   • During the switch, advise the end users to avoid using the target email address anywhere in Atlassian cloud to avoid generating new conflicting accounts.

Solution

Scenario 1: SAML-SSO and User provisioning is not enabled for the organization

Update the Atlassian Account email address via the Managed Accounts administration or use the Set Email Organization API to change the email address in bulk.

• Export the managed accounts to identify the Atlassian Account IDs that can be updated via API.

• If you are using social logins such as Microsoft or Google, ensure that the email addresses of the accounts have been updated on those providers. If the change is not made on the provider side, the end user’s next social login the into Atlassian cloud will reback to the email address change performed on the Atlassian side.

Scenario 2: SAML-SSO is enabled for the organization but user provisioning is not

The email address change can propagate from the identity provider accounts into the Atlassian accounts on the user’s next login into the Atlassian cloud, provided they have previously logged in via the enforced SSO. However, depending on your organization’s idle session duration, the end users might not be prompted to immediately re-login to the Atlassian cloud.

Step 1: Identify the IDP attribute that will be used as the Atlassian Account email address during login via SAML-SSO

Step 2: Update the IdP attribute identified from Step 1 to the target email address. When the end user next logs into the Atlassian cloud, the new email address should propagate to their existing Atlassian Account.

Step 3: Since you cannot guarantee that all your managed accounts will re-login into Atlassian cloud immediately, it is best to update their email addresses to the target email address. Follow Scenario 1 above.

Scenario 3: SAML-SSO and User provisioning are enabled for the organization.

Step 1: Identify the IdP attribute that will be used as the Atlassian Account email address during login via SAML-SSO. Please see Scenario 2 above.

Step 2: Identify the IdP attribute that will be used as the Atlassian Account email address when syncing an account.

Step 3: Update the IdP attributes identified from Step 1 and Step 2 to use the target email address. Provisioning will automatically sync the changes to the linked Atlassian Accounts.

Step 4: For managed accounts that are not provisioned, update their email address by following Scenario 1 above.

Scenario 4: Google Workspace integration is enabled (not SAML-SSO and SCIM-User provisioning)

Step 1: Update the primary email address attribute in Google. This should propagate to the linked (locked managed account) Atlassian Accounts.

Step 2: For managed accounts not provisioned, update their email address by following Scenario 1 above.