Migrating Primary Domains in Gsuite (Google Workspace) – An Epic Odyssey

Edit: Thanks to UmzuzuJoe for reminding me about the necessity to update groups also.

This post is based on my personal experience changing Gsuite primary domains in a medium sized organization. I hope to give you the basic idea of how your migartion should work and what to exepect – and most importantly: tell you all the details and troubles you will face that are not covered in Google’s official documentation.

However, you should still check out Google’s offical guide here

So, you want to change your primary domain in Gsuite?

First, consider if you REALLY want to change your primary domain. This will cause many side-effects in almost all third party services that log you in using Google.

Do you want to send and receive e-mails as another domain? Consider adding a domain alias.

I won’t discuss this further because Google’s guide already covers this pretty well, but know that migrating primary domains is not simple.

“Yes you cheeky tart, i want to change primary domains in Gsuite.”

Okay, no need to be rude. Let me show you what Google’s instructions don’t.

What do you need to do, in general?

There are three main steps to migrating your primary domain:

1 – Change the primary domain on your Gsuite settings

2 – Rename each user and group individually to the new domain (this is what actually “migrates” them)

3 – Reconfigure applications and platforms that use Google login as needed.

Simple, right? Well, no. The devil is in the details. Let me show you how.

I highly recommend that you change all users to the new domain all at once. This is because many apps/platforms (such as Slack!) do not allow google login using two different domains, so you will have to change everyone at once to avoid keeping people off these apps.

To do this safely you need to map all applications that use google login (that is the “login via Google” button), test and have a rollback plan for each one of them.

This is because many applications map an user’s email as their “primary ID”, so if you try to log in using a different domain they won’t associate it with the same account. All other sorts of batshit clownshoe horsefuck insane problems are bound to appear.

Make a dummy account and add it on all apps/platforms you mapped. Migrate the dummy account, then test all platforms. If you noticed anything wrong, contact the app’s support team. In fact, you should contact all of them just in case – tell them you’re migrating to a new domain and that you would like to know if there are any known issues and what is the best way to go about it.

Also, you should have a rollback plan for each app in case the migration goes absolutely wrong.

Step 1 – Changing the Primary Domain in Google’s settings

This step is fairly easy and has little side-effects.

What happens when you change your primary domain?

Simply changing your primary domain in the domain settings doesn’t have many immediate effects. However, some of them are note-worthy:

• Sending and receiving e-mails may be fucky wucky for a few hours

• If the previous domain was an alias domain, you have to remove it and re-add it as a secondary domain, then change it into the primary domain. This causes all aliases from that domain to be removed. Be sure to re-add them or users will start losing e-mails.

If you need a way to add aliases in bulk, this script is a great way.

Also, Google’s guide says that removing an alias domain may disable it from being added as a secondary domain for up to 24 hours, but in our case it only took 5~ minutes

• New users will, by default, be added to the new domain.

I recommend you don’t create users in the new domain until all the old users have been migrated to the new domain for the same reasons as stated previously on why you should migrate everyone at once.

What should you do?

• Communicate the risks involved in this change to all executives and leaders in you org. Get their approval and their blessing.
• Set a date and time for the change – preferably during the night or on a weekend.
• Communicate to your users about the change and expected issues.

Step 2 – Migrating users and groups to the new domain

This step is really hard and has a lot of side-effects.

What happens when you change a user’s domain?

• Applications that use google login will be affected.

This really depends on the app, but we had many different effects. Some worked perfectly; others created a new account when the user signed in using the new domain; some complained the account couldn’t be found; some detected the change automatically and allowed the login but lost some of the user’s data.

This is why mapping and testing all apps that use Google login is so important. Each one will behave differently and you have to be prepared.

• The user’s old domain will be added as an alias

This is true for when you change a user manually inside Google’s admin panel. I don’t know if the same happens when you change users in bulk mode.

• Some users may be logged out from their Google account on their phones

This seems to happen monstly on Android phones. This is really important because if you have 2FA enabled for all users, those who chose the phone alert method will be locked out of their accounts (Catch-21 style) unless they have backup codes available or also use another method (such as an authenticator app).

• If users need to send e-mail through the old domain, it may be marked as SPAM.

Google is having some issues when sending e-mails using an alias domain – it mixes up the alias domain with the real domain in a bunch of places inside the message and causes SPF and DKIM alignment to fail, which causes DMARC to fail and makes everyone sad.

For groups there are no big side effects, but you should still take necessary precautions and communicate the change to group owners.

What should you do?

• Again, because this is absolutely critical: map and test all applications and platforms that use Google Login. Have a plan, a backup plan and a rollback plan for each one.

• Communicate the change to your executives and leaders. Make sure they understand the impacts and risks associated with the change. Get their blessing and their approval
  
  This is very important if you want to keep your job in case something goes south.

• Set a date and time for the migration.
  
  Preferably on a friday night or saturday morning – if something goes wrong, you have the rest of the weekend to fix it (or update your resumé).

• Warn users about the migration, why it is being done, when and how it is going to be done, what steps they will need to take, and what will happen if they don’t.
  
  For apps/platforms that require user action before or after the migration, be sure to make easy-to-follow tutorials for your users and distribute them.
  
  Try to implement a bottom-down communication plan: warn everyone, but ask managers and other leaders to reinforce the message and make sure their team understands what’s happening.
  
• Have at least two super-admins inside Gsuite
  
  Migrate them one at a time. If anything goes terribly wrong, you still have an admin in the old domain that you can use to fix things.

• If users need to send emails using the old domain, configure their GMail accounts. This is really easy and Google explains how to do it here.

Step 3 – Reconfigure affected applications

Again, this is why you need to map all applications that use Google login – a lot of them will break and require some sort of configuration change.

You should have mapped what those configuration changes are and how you should do them previously, so this should be straightforward but with a unique set of steps for each one of them.

After making all the changes, test the platforms using your dummy account. If any critical app/platform is unusable, you may have to consider a rollback.

Post Mortem – Manage the stragglers and clean up

Many users will probably not have followed (or even read) the necessary steps for the migration – have someone ready to help them at all hours of the day.

Also, don’t forget to delete your dummy account and remove it from all platforms.

Thank you for reading this post – i hope it helps you.
If you have any doubts or would like more details about something, feel free to email me at [email protected].

Views: 238