nav[aria-label="Primary Navigation"] { padding: 0; & ul { list-style: none; width: 100%; display: flex; flex-direction: row; justify-content: start; align-items: start; gap: 30px; padding: 0; & li { margin: 0; } & ul li { list-style: none; } } }

Single Sign On - Email Domain Change

Kieren Johnson

We use Atlassian Access, Jira, Jira Service Desk & Confluence and have configured SAML Single Sign On.

We are soon to change our primary email domain used by our SAML service. Will this break our existing Jira configuration? What do we do to migrate all users to the new email address?

Many thanks.

Accepted answers

Ramon Macalinao

Hi Kieren,

Thanks for using Atlassian Community.

The SAML-SSO integration in Atlassian Access can implement the change. When you update the email address of the user on the IDP side, the change will be propagated to Atlassian side on the user's next login.

Once the account on Atlassian side is updated with the new email address, the end user will continue to have access to their Atlassian cloud data prior to the change, that includes Jira, Confluence and JSD on cloud.

Prerequisites :

1. The new domain is claimed on the Atlassian Access organization.

Go to https://admin.atlassian.com
Open your organization
Navigate Directory > Domains
You will find your old domain here. Verify the new domain as well.

2. The target email address should not be an existing Atlassian Account otherwise the change propagation will fail.

Once you add the new domain in your organization, the Managed Accounts section will start to list all Atlassian Accounts under the new domain.

Go to https://admin.atlassian.com
Open your organization
Navigate Directory > Managed Accounts
Filter the list to show only accounts under the new domain.
Review this list and see if there are any accounts that is the target address for the change.
Check with the end users if they are valid and can be freed up / deleted.

TIP : Deleting an account has a grace period of 2 weeks. The quickest method to free up the target email address is to change the account's email address in Managed Accounts to a dummy one.

myuser@newdomain.com -> myuser_OLD@newdomain.com
myuser@newdomain.com is now free and can be used for the email address change.
myuser_OLD@newdomain.com can be deleted and it will clear out after 2 weeks.

Procedure :

Change the email address of the user on the IDP side.
As the end user, login into Atlassian (ie. to your Jira site) via SSO using the new email address. They will probably need to log-out of Atlassian and your IDP to initiate the full login flow.
The change will propagate into Atlassian and the user's account in Atlassian side will be updated with the new email address. The change will also reflect on your Manage Accounts and Jira/Confluence site admin pages.
The end user can continue to work as normal.

Just a watch out if you are using Azure AD, check the attribute mapping for the SAML-SSO setup. The Azure attribute (UPN or mail) that is mapped to the "Unique User Identifier (Name ID)" will be the value that will trigger the change into Atlassian.

I hope this helps.

Cheers,
Ramon

All comments

Ramon Macalinao

Hi Kieren,

Thanks for using Atlassian Community.

Prerequisites :

1. The new domain is claimed on the Atlassian Access organization.

Go to https://admin.atlassian.com
Open your organization
Navigate Directory > Domains
You will find your old domain here. Verify the new domain as well.

2. The target email address should not be an existing Atlassian Account otherwise the change propagation will fail.

Once you add the new domain in your organization, the Managed Accounts section will start to list all Atlassian Accounts under the new domain.

Go to https://admin.atlassian.com
Open your organization
Navigate Directory > Managed Accounts
Filter the list to show only accounts under the new domain.
Review this list and see if there are any accounts that is the target address for the change.
Check with the end users if they are valid and can be freed up / deleted.

TIP : Deleting an account has a grace period of 2 weeks. The quickest method to free up the target email address is to change the account's email address in Managed Accounts to a dummy one.

myuser@newdomain.com -> myuser_OLD@newdomain.com
myuser@newdomain.com is now free and can be used for the email address change.
myuser_OLD@newdomain.com can be deleted and it will clear out after 2 weeks.

Procedure :

Change the email address of the user on the IDP side.
As the end user, login into Atlassian (ie. to your Jira site) via SSO using the new email address. They will probably need to log-out of Atlassian and your IDP to initiate the full login flow.
The change will propagate into Atlassian and the user's account in Atlassian side will be updated with the new email address. The change will also reflect on your Manage Accounts and Jira/Confluence site admin pages.
The end user can continue to work as normal.

I hope this helps.

Cheers,
Ramon

Kieren Johnson

Such a great answer. Full of detail. Thank you.

Ramon Macalinao

Glad to help Kieren and good luck!

Bhavin Shingala_78itvy

Hi Ramon,

We're using standard server licenses. We've Azure AD, Office 365. Following is our Atlassian products version. What is the best way to implement SSO without installing/purchasing Add-on.

Jira 7.12.3
Confluence 7.2.2
Bitbucket 6.9.2

Matthew Arsenault

Very good! I would assume this is the same case with moving to a new AzureAD tenant with a new domain name?

We are in the middle of a M&A and we plan on migrating our users into the parent company. We would like to shift our Atlassian account to the new parent company and migrate atlassian SSO from our current AzureAD tenant to the new parent company AzureAD tenant. This would involve changing all of our users email addresses to the new parent domain and continue authing using SSO. We want to keep all data associated. I don't see this to much different than a domain name change, but wanted to make sure.

Thanks!

Ramon Macalinao

Hi Matthew,

It will not work in that case because the SSO link used by the automatic email address change will be invalidated when switching Azure implementations.

You will need to perform an account migration in that case.

Disconnect the SSO integration with the current Azure AD.
Claim the new parent domain in the same organization
Perform an account migration on Atlassian side.
- Go to https://admin.atlassian.com
- Open your organization
- Navigate Directory > Managed Accounts
- Change the email address of the Atlassian Accounts to use the new parent domain. The email addresses of all your domain account should match the email addresses on the new Azure AD.
Configure SAML Single Sign with the new Azure AD.

I hope this helps.

Matthew Arsenault

Yes, this is very helpful! This still seems very attainable with minimal downtime and impact to the business. Will all existing data and permissions be retained after switching the user email addresses? I assume when you say account migration, you refer to the migration of the identity services and not an entire org migration to a new atlassian account.

Lastly, will this change the primary url seen throughout the atlassian account? Ideally the URL will reflect the new domain we are moving to as we start rebranding the account.

While this seems straight forward I have bigger concerns with integrations and opsgenie.

Thanks!

Ramon Macalinao

Yes, the Atlassian accounts will continue to have access to the sites and their existing data after the change. They are simply identified under the new email address.

The change I mentioned indeed only covers the identity part. For the URL of your cloud sites, you will need to arrange the site rename separately by following this KB article.