Background

The product access and historical data in cloud products are linked to the Atlassian Account and not the email address specifically. 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 Atlassian cloud at a time. To change the email address of an account, the target email address should not be used by another Atlassian Account.

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

• If an identity provider is configured with Atlassian Access, the email address change can be propagated from the identity provider into Atlassian cloud via 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)

   • Go to https://admin.atlassian.com

     • Open the Managed accounts administration for your organization.

     • Export the accounts.

   • Review if any Atlassian account is already taking up 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 ).

     • The email address can be updated via the Managed Accounts administration web interface or by using the Set Email Organization API. These accounts can be deactivated/deleted later on when the change is completed.

   • 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 perform the email address change in bulk.

• Export the managed accounts to identity the Atlassian Account IDs that can be used for update via API.

• If you are using social logins such (ie. Microsoft and Google), make sure that the email addresses of the accounts have been updated on those providers. If the change is not done on the provider side, the end user’s next social login into Atlassian cloud, will revert back the email address change performed on 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 Atlassian cloud provided that they have previously logged via the enforced SSO. However, depending on the idle session duration of your organization, the end users might not be prompted to immediately re-login to Atlassian cloud.

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

<saml2:NameID 
Format="urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified">
A1_smtp_email@atlasbean.com
</saml2:NameID>

Step 2 : Update the IDP attribute identified from Step 1 to the target email address. On the end users next login into Atlassian cloud, the new email address should propagate to their existing Atlassian Account.

Step 3 : Since you cannot guarantee all your managed accounts to re-login into Atlassian cloud immediately, it is best to update the email address of the managed accounts 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 that are not provisioned, update their email address by following Scenario 1 above.