Moving to a new G Suite organization

[shaynec]

Due to a corporate merger, we will be moving from our current Google G Suite organziation to a new one. Today we utilize our Google G Suite identities for accessing our Atlassian Cloud (Jira/Confluence) services. Is there a procedure to follow to associate the new G Suite accounts with the existing Atlassian User accounts?  E.g.

current

user1@olddomain.com (g suite user) --> user1 (atlassian user)

after migration

user1@newdomain.com (g suite user) --> user1 (atlassian user)

[Dave Meyer · Accepted solution]

Hi @shaynec,

If you add the new domain to your current G Suite organization and update the relevant users email addresses, the email address change will be synced to their Atlassian accounts. Then you can move the new domain and those users over to the new G Suite organization.

Hope this helps,

Dave

[mroz]

Hey @shaynec –

The most important thing to bear in mind to avoid problems is that you should ensure that between each sync, either the users' Google account IDs or their primary email addresses should remain static.

IDs are supposed to be immutable, but because Google will treat the users on the new Google organization as new accounts, their IDs will be different there. You of course are in total control of their primary email addresses. Given these constraints, you have a reasonable degree of flexibility in how you approach this.

Dave's suggestion is certainly the easiest and safest approach, but acknowledging that you might be reluctant or unable to claim the new domain in the old organization, I thought I'd provide a bit more insight.

Please let us know if you need any further clarification :)

Michael

Note: it just occurred to me that I'm not sure you're actually using our Google Suite integration. If you just apply changes in your Google userbase without actively synchronising them to your Atlassian one, this won't work! See the docs here for details.

[shaynec]

Hi @mroz and @Dave Meyer thank you both for your answers. I am still a little confused however about how to prepare for the migration from olddomain.com to newdomain.com. I do not have the ability to claim newdomain.com in the old organization, so I do not think that I can follow @Dave Meyer's suggestion.

What I don't understand though, is the identifying attribute which is used for the federation between a G Suite user account, and an Atlassian cloud account. Is this the primary email address of the user? Or is there some G Suite GUID which is sent over (and mapped??) to an Atlassian Cloud user account?

As I see it, if it is the primary email address, then I suppose this is within my control (or my users' control) to change as part of the migration process between G Suite Accounts. If however, it is some GUID value, then I am not really sure what options I have (if any).

[mroz]

@shaynec,

Yeah, GSuite users have a unique identifier. In fact, it's globally unique to the entire Google userbase, not just your slice of it.

There are actually a series of identifying attributes that we use in an attempt to increase the likelihood of successful synchronisations with the G Suite integration (again, these only apply to the integration, and not to the standard login with Google flow, which is much weaker).

Those identifiers are (in order of importance):

1. the G Suite unique identifier (if it's tracked on the site you're synchronising into; it's not global),
2. the primary email address (global, so this is the most reliable), and then
3. any verified email aliases associated with the user in G Suite against the email address in Atlassian account

That last one is a bit unreliable though for reasons I won't get into, which is why in the steps I've outlined below, I've avoided depending on it. There's a lot of history behind why this works exactly the way it does. This is all likely going to be improved dramatically in the not-too-distant future, but this is what we're dealing with for now.

I do not have the ability to claim newdomain.com in the old organization

I suspected this might be the case. It makes things slightly harder, but not impossible. Do you have the capacity to claim the old domain in your new Google organization? It seems likely that you'll be doing this anyway to preserve your users' old email addresses. If so, one way you can do this would be to:

1. Claim olddomain.com in your new GSuite organization,
2. Ensure that all the users from the old domain exist in the GSuite organization, and that their primary email addresses (this is something only administrators can control) match their previous ones,
3. Connect (docs) your new G Suite organization to an Atlassian site you control, and select either "All users" or (if you have a group that contains at minimum every user from the old organization) select appropriate groups,
4. Start the sync process (depending on the size of your G Suite userbase, this might take a few minutes),
5. Once the sync has completed, change the primary email address of each new user in GSuite to be on the new domain, and manually kick off another sync (the "Sync now" button cleverly hidden in the top right of the G Suite integration interface), then finally
6. Disconnect the G Suite integration and restore the domain claims in your Atlassian organization (the integration will override those).

I didn't want to pollute the steps above, but so you better understand the process, some explanations:

1. You need to claim this domain so that Atlassian will trust your assertion of the Google users' email addresses. We won't accept an assertion of an email address value unless Google convinces us that you control the domain.
2. It's important that the users have their old email addresses as their primary ones, because otherwise you'll end up with duplicate accounts lying around, which will make life hard for your users.
3. Pretty straight-forward; you're just configuring a sync process which will actively pull all your users from Google and populate the Atlassian site with them, updating the users' global Atlassian accounts as necessary.
4. More of the same.
5. This is the actual change step, everything so far has been setup to ensure that nothing goes wrong.
6. At the risk of going into too much detail, the G Suite integration is a bit unique (for now) in that it kind of sits between organizations and sites. It operates a little like an organization that you have zero direct control of but instead can apply changes to via Google. As a consequence, it makes domain claims on behalf of your G Suite instance. As domains can only have one owner at a time, this will supersede your organization's ownership, but that's easily restored once you've finished the process.

Some things to note:

• I skimmed over it, but I'm sure you'll notice that there's a bit of manual process in ensuring that users email addresses match certain values and then updating them again. Automated processes likely exist for this, but I don't have a lot of insight into this, never having operated a G Suite site of more than a handful of users (sorry!)
• Because the G Suite integration will be claiming all of the domains owned by your G Suite organization on Google's behalf, any authentication policies you have set by your organization will stop applying for the lifetime of the connection, and users will instead be required to log in with Google. Since this is likely disruptive, it would probably be best to go through this process at a time when you anticipate low traffic (again, apologies).
• The G Suite integration tool is actually older than Atlassian's concept of organizations but acts a lot like one. That will likely change within the next year, so hopefully next time you have to go through this, there won't be so many gotchas.

Hope that helps,

Michael