How-to: change of the main domain in the G Suite for the entire company and with the preservation of all data

There is a need to change the main domain of the company in the G Suite from .ru to .com with the preservation of all data, calendars, aliases and access to third-party resources. Information about moving on the Internet is not very much, but rather, except for the help of Google itself, there was nothing at all, which was the reason for creating this how-to. It will be useful if someone decides to repeat this.

The fact is that initially the company used the domain pixonic.ru. Then the alias pixonic.com was added, but everywhere by default there was mail in the .ru zone. And since many of the company's employees are in correspondence with foreign colleagues and customers, there was a desire to use an international format. To do this, they had to go into the account settings, independently change the primary mailing address and align the signature with the corporate template. Not everyone did it (or did it, but through time) and you can imagine what a mess and confusion were created in the message threads. For external partners, it looked even less presentable due to different signatures.
')
In general, the time has come when it was decided that all correspondence should be conducted using pixonic.com mail. The task fell on us - the system administrators.

At the end of the article there is a link to the whole script, so the text will contain only its pieces.

We use Google for business, so the mail is located on the same service. So, what was available:

1. Domain pixonic.ru.
2. Pixonic.com and pixonic.org aliases.
3. ~ 200 accounts and ~ 80 distribution groups.
4. A bunch of nicknames for some accounts.
5. Calendars, including general for the company.
6. Connected Google analytics.
7. Dozens of terabytes of important information on Google Drive.
8. Third-party services Jira, Slack and others, in which authorization occurred using a Google account.

What was planned:

1. Make pixonic.com the main domain, and pixonic.ru and pixonic.org - its aliases.
2. Relocation of all accounts in pixonic.com with preservation of all correspondence and information on Google Drive.
3. Relocation of postal groups while maintaining the composition and rights of its members.
4. Save all user aliases.
5. Saving access to all shared files in Google Drive for accounts.
6. Saving calendars so as not to lose information about scheduled meetings and events.
7. Saving access in Jira and Slack.
8. To the maximum avoid the loss of mail.

Of course, the first thing we wrote to tech support was asking us to change the main domain. They got the answer - they can't do it and, in general, they advised never to risk it.

Okay. Migrate each user's account manually - a so-called perspective. Moreover, a similar procedure would have to be done for each new employee separately. You can also try to do it through the API, but again - this will not solve all the problems, because many use third-party email clients with old settings. And the problem with new employees is not going anywhere.

In the help on the move from Google itself five points:

1. Add an additional domain and configure MX records.
2. Make a new domain major.
3. Rename users to the new primary domain.
4. Rename groups to the new primary domain.
5. Remove the old primary domain (optional).

It does not look difficult, we must try.

What exactly remains, and what may be lost as a result of such actions, was not indicated. Therefore, we made a test environment, bought another G Suit and added test domains to it.

Then they identified the requirements for the move: the preservation of information, rights and user access. Those. the only problem that the end user had to face was the need to re-enter his new account on all devices.

And they started the tests.

Testing possible scenarios and verification took us almost a month. The test results were very encouraging, so we decided to repeat everything on the working environment.

Action algorithm

All that could be done without hands was done with a Python 3.6 script. From third-party modules, we need google-api-python-client, oauth2client, httplib2, apiclient and pyopenssl. No problem installed using pip.

To use the Google API, you need to create a service account in the developer console . To do this, we create a project (or use an existing one), select “Credentials → Create credentials → Key for a service account”.



We select the “New service account”, name it, assign the role “Owner”, choose the P12 key (regarding the key is not very important, but during the tests I was able to authenticate with JSON only with explicit permission from the specific user on whose behalf operations, which in this case is not suitable).



Authorize the service account in the administrator console in the “Security → Advanced Settings → Manage API Client Access” section.

The API can only work in the area in which it is authorized (a description of all areas can be read here ). I used the following:

• Email (Read / Write / Send) mail.google.com
• www.googleapis.com/auth/activity
• Www.googleapis.com/auth/admin.directory.group
• Www.googleapis.com/auth/admin.directory.user
• www.googleapis.com/auth/drive.metadata.readonly
• www.googleapis.com/auth/gmail.settings.basic
• www.googleapis.com/auth/gmail.settings.sharing

After the API has been verified, you can proceed to the migration work itself.

The basis of the whole script is to obtain the rights and delegate them to any user, depending on the required actions. Those. if you need to change the signature of someone in the mail, then the delegation must be made to the same account; if you get a list of users, then an administrator account, etc.

So it looks to me:

def get_credentials(email): #      e-mail credentials = ServiceAccountCredentials.from_p12_keyfile( SERVICE_ACCOUNT_EMAIL, SERVICE_ACCOUNT_PKCS12_FILE_PATH, 'notasecret', scopes=['https://www.googleapis.com/auth/admin.directory.user', 'https://www.googleapis.com/auth/gmail.settings.sharing', 'https://www.googleapis.com/auth/gmail.settings.basic', 'https://mail.google.com/', 'https://www.googleapis.com/auth/activity', 'https://www.googleapis.com/auth/drive.metadata.readonly', 'https://www.googleapis.com/auth/admin.directory.group']) delegate_credentials = credentials.create_delegated(email) return delegate_credentials.authorize(httplib2.Http()) 

In essence, we call this function before each action, then select the application in which we need to perform manipulations, and run the API. The execution of the API returns either the execution result or the data that was requested.

 http = get_credentials(adminEmail) service = build('admin', 'directory_v1', http=http) data = service.users().aliases().list(userKey=usermail).execute() print(data) 

The beginning of work is denoted by the creation of a backup of everything that we may need, namely: information about users, groups, group members, user aliases, and group aliases.

Everything is simple: we request information, we write it to a file, since Google provides all the information in JSON-format and it’s convenient to work with it.

 def backUpInfo(filename=''): path = os.path.expanduser('~/Documents/backup/') prefix = path+'backup' if not (filename == ''): prefix = path + filename #backupUsers with open(prefix + 'Users.json', 'w') as file: userInfo = getAllInfoUsers() file.write(json.dumps(userInfo, indent=4)) print(prefix + 'Users.json done') #backupGroups with open(prefix + 'Groups.json', 'w') as file: groupInfo = getAllInfoGroups() file.write(json.dumps(groupInfo, indent=4)) print(prefix + 'Groups.json done') #backupUsersInGroups with open(prefix + 'UsersInGroups.json', 'w') as file: groupInfo = getAllUsersInGroups() file.write(json.dumps(groupInfo, indent=4)) print(prefix + 'UsersInGroups.json done') #backupUsersAliases with open(prefix + 'UsersAliases.json', 'w') as file: info = getUsersAliases() file.write(json.dumps(info, indent=4)) print(prefix + 'UsersAliases.json done') #backupGroupsAliases with open(prefix + 'GroupsAliases.json', 'w') as file: info = getGroupAliases() file.write(json.dumps(info, indent=4)) print(prefix + 'GroupsAliases.json done') 

The next step is to remove the com alias and add it as a domain. These actions are performed in the administration console → Domains → Add / remove domains.

When adding a domain, you need to specify the MX records and the service needs some time to check them (in our case it took a couple of minutes). In principle, the end of the test can not wait and continue to work.

After adding a domain, it will be possible to make it basic, which we do (there is no such possibility in the trial version of the G suit, it appears only in the paid version and not immediately after the payment, but only after the trial period expires, which is strange).

Then we have the transfer of users and groups to the new domain. The algorithm is as follows:

• we delegate the rights to the administrator account;
• unload the entire list of users;
• we pass on each user, except the administrator account under which we work;
• and change the primaryEmail field through the API function users (). update ().

Those. User transfer through the API consists in changing the domain in the main email address from .ru to .com. It looks like this:

 def moveUsers(domain): #     users = getUsers() #   ,  adminEmail for a in users: if adminEmail in a[0]: continue try: renameUser(a[0], domain) print('Done: ' + a[0]) except Exception as e: print(sys.exc_info()[0], ":", e) print('Failed: ' + a[0]) print("Users done!!!") 

The users (). Update () function is very useful as it allows you to change any information in a user profile. In the parameters, the user login and changeable parameters in JSON format are transferred to it.

 def renameUser(email, domain): patch = {'primaryEmail': changeMailDomain(email=email, domain=domain)} http = get_credentials(adminEmail) service = build('admin', 'directory_v1', http=http) service.users().update(userKey=email, body=patch).execute() 

Similarly, you can add information to your profile, for example: a Skype account, an additional position and whatever you like.

We carry out a similar operation for groups.

We transfer your account to the new domain. After that, you need to log into your new account and re-authorize the service account. There is nothing to change in it, just take its name from the column “Authorized API Clients”, and the list of necessary areas from the second column.

Now in our old domain should not be anyone. Therefore, go to the list of domains in the administrator console and delete it. And then we add it in place, but as a pseudonym (if you even need an old domain).

Stayed the final touch. After we deleted the com alias in the beginning, all the aliases of users and groups also went away, so we need to restore them from the backup we made at the very beginning. In this case, it makes sense to change the domain to our new one in all aliases, since all alias domains will appear automatically. To do this, we load information from the backup, go through each user and restore all aliases, if they are available using users (). Aliases (). Insert (userKey = email, body = body).

We perform a similar operation for groups.

Well, everything moved.

Link to Github.

PS Some changes are not immediately visible. For example, after deleting the old domain and adding it as a pseudonym, if you go to the admin panel in someone's account, then there will be seen his pseudonyms, which in fact no longer exist. In any case, they will have to be restored.

What is the result?

We moved with a minimum of losses. Work from the time of the backup, until the recovery of pseudonyms took ~ 20 minutes.

Access is not lost, the composition of mail groups has not changed. Nobody complained to us about any problem with the account, they say, I can not log into the account or read any file. Shared calendars remained intact, scheduled events were not lost.

With third-party services is not so happy, although acceptable. Authorization has not flown into them, but who registered at the old mail, under it should go, so there you can not choose to log in via Google+. It didn’t touch us much, because all users were warned about this before and after work. In the case of Slack, the problem can also be solved through the API by changing the addresses of users. In cloudy Jira, alas, this will not work, but if you use a local server, then the problem is solved.

As a bonus, we received a good tool for creating users with ready-made signatures made according to a corporate template. And if necessary, the signature is easy to update without user intervention. In addition, using the API it is convenient to update information in the employee’s profile or, on the contrary, to receive.