Google Workspace Directory Sync

Google Workspace synchronization allows for secure and consistent connectivity between JumpCloud and Google Workspace. Once you’ve authorized Google Workspace sync, automatic provisioning of new JumpCloud accounts into Google Workspace, as well as continual user attribute synchronization from JumpCloud to Google accounts will occur. Pre-existing Google accounts can also be imported into JumpCloud and then managed from JumpCloud.

Note: After reading through this guide, see these additional articles which are part of our series on the Google Workspace Directory Integration:

• Google Workplace Integration Overview

• Sync User Attributes with Google Workspace

• FAQ: Google Workspace Directory Integration

Adding and authorizing the Google Workspace Cloud Directory Integration

Considerations:

• The Google Workspace Directory integration will stay authorized indefinitely if the following conditions are met:

  • The administrator that authorized the integration continues to exist in both JumpCloud and Google Workspace.

  • The integration has been utilized (via an import or export) in the past six months.

• If either of the above conditions aren’t met, the integration will need to be reauthorized via the steps included in this article.

To add and authorize Google Workspace Sync in JumpCloud

To set up the Google Workspace Sync, you must authorize the sync in JumpCloud and grant access to the Google Super Admin Account in Google.

1. Log in to the JumpCloud Admin Portal.

2. Navigate to DIRECTORY INTEGRATIONS > Cloud Directories.

3. Click ( + ). 

4. Select Google Workspace. 

5. Give the Google Workspace directory instance a unique name.​​​​​​

Note: You'll receive an error and will be unable to proceed if you:

• Use invalid characters.

• Don’t specify a unique name for the directory.

• Make the name longer than 255 characters.

• Create a name that only contains white space. 

6. Click authorize sync.

7. Enter the email address for the Google Workspace admin account you want to use for the integration. 

8.  Enter the password for that account if prompted.

9.  Click Allow. 

10. If you have already granted access to the Google Super Admin account, then you can select users and click import to import them from Google Workspace into JumpCloud now or click cancel to complete the import task later. See Importing Google Workspace Users below for more information about importing users.

To grant access to the Google Super Admin Account

After you authorize Google Workspace sync, you need to grant access to the Google Super Admin account. This is a Google best practice and needed for providing a single set of identity management controls across all Google services, including Cloud Identity.

1. Log in to Google using a Super Administrator account.

2. Click Allow.

Tip: This is the minimum configuration required to use the integration.

Configuring the Google Workspace Cloud Directory Sync Integration

To initially import users

After you authorize sync with Google Workspace, you can import users that exist in Google Workspace but do not yet exist in JumpCloud.  A modal opens with a list of existing active Google Workspace user accounts.

You can close this tab to import accounts at a later time, or you can continue importing accounts now.

To enable Google Workspace Group(s) Management

The integration supports the creation and management of distribution groups in Google Workspace from JumpCloud.  This functionality allows you to centralize the management of these groups and users.

Prerequisites

• Before you can export distribution groups to a Google Workspace directory you must have authorized sync for the Google Workspace directory.

Considerations

• After you enable group management, changes made to groups in JumpCloud are synced to distribution groups in Google Workspace. Changes only sync from JumpCloud to Google Workspace. Changes made to groups in Google Workspace aren’t synced to JumpCloud.

• If you disable group and membership management, no further changes will be made to distribution groups in Google Workspace. The groups will remain exactly as they were at the time the functionality was disabled.

• It can take some time for new groups to appear in the Google Groups directory. See Google’s Admin Help: New groups don’t show up in Groups directory.

To enable Google Workspace group management

1. Navigate to DIRECTORY INTEGRATIONS > Cloud Directories.

2. Select the Google Workspace directory you want to manage groups for.

3. In the Google Workspace Sync section of the Details tab, select Enable management of groups and memberships in Google Workspace. 

4. Click save.

5. If you have not already granted the groups permission, you will be redirected to the Google Workspace authorization flow.

   1. Enter the email address for the Google Workspace admin account you are using for the integration if prompted.

   2. Enter the password for the Google Workspace admin account you are using for the integration if prompted.

   3. Click Allow.

Warning: After you enable group management for your Google Workspace directory sync integration in JumpCloud, add the email attribute for user groups bound to that Google Workspace directory. If you don't add an email address to these groups, users in bound groups could be suspended until one is added. 

To specify Distribution Groups

Prerequisites

• Before you can specify distribution groups to sync, you must select the Enable management of groups and memberships option in Google Workspace and click save.

Considerations

• If you remove a distribution group’s email address, the group and its memberships are no longer synced with Google Workspace.

• If you change a distribution group’s email address, the members of the group are moved to the distribution group of the email address you specify.

Specifying a Google Workspace Distribution Group

1. Navigate to DIRECTORY INTEGRATIONS > Cloud Directories.

2. Select the Google Workspace directory you want to manage groups for.

3. Select the User Groups tab.

4. Enter an Email Address for the Google Workspace distribution group. 

5. Click Save.

When you bind JumpCloud user groups to a Google Workspace directory, users in those groups are added to those same distribution groups in Google Workspace. Distribution group membership, in addition to user attributes and passwords, will be synced. 

To configure domain(s)

Specify one or more domains as part of the integration configuration to have more granular control over which user accounts sync and how the translation rule for the email to User Principal Name (UPN) mapping is applied. There are three (3) possible configurations: no domains, a list of one or more domains but no default, and a list of one or more domains with one of those domains used as a default for the UPN translation rule. Each configuration is described in more detail below.

• If no domains are configured, the user’s company email is not checked and sent as is. The user syncs as long as their email domain matches one of the verified domains in the Google Workspace instance.

• If one or more domains is configured and the No default option is selected, the user’s company email is checked against the domains listed. Only users with matching email domains are synced.

• If one or more domains is configured and one of the domains is selected to Use as default, the user’s company email is checked against the domains listed.

  • If the domain matches one of the domains in the list, the email address is sent as is.

  • If the domain does not match one of the domains in the list, the email value sent as the Primary Email will be the username portion of the company email address and the default domain.

Examples of how domains are used by the integration.

To add domains

1. Log in to the JumpCloud Admin Portal.

2. Navigate to Cloud Directories.

3. Click the Google Workspace directory instance.

4. Click +Add Domain.

5. The first time you add a domain, you will be redirected to the authorization flow to approve the domains permission.

   1. If prompted, enter the email address for the Google Workspace admin account you want to use for the integration and the password for that account on the subsequent screen.

   2. Enter the password for that account if prompted.

Note: If you enabled group management in this session, will will also see the groups permission in the list of permissions.

6. Click Allow. 

7. You will be redirected back to the configuration page of for the Google Workspace integration

8. Click the domain dropdown menu.

9. Select one of the domains from the list.

Note: The list is pulled dynamically from Google Workspace and only includes verified domains. The domain noted with (Primary), is the domain specified as the primary domain for that Google Workspace instance. That label is separate from the ‘Use ad default’ option within the integration configuration in JumpCloud.

10. Repeat steps 4-6 to add additional domains.

11. Click the radio button next to one of the domains to use that domain for the PrimaryEmail translation rule.

12. Click save.

To set a default domain for the integration

1. Log in to the JumpCloud Admin Portal.

2. Navigate to Cloud Directories.

3. Click the M365/AAD directory instance.

4. Click Edit Domains.

5. Click the radio button next to one of the domains to use that domain for the PrimaryEmail translation rule.

6. Click save.

To configure attribute mapping and settings

You can control which attributes sync from the Attribute mapping and settings section. For more information, see Sync User Attributes with Google Workspace

Importing Google Workspace Users

After you authorize Google Workspace sync and grant access to the Google Super Admin account, you can import users from Google Workspace into JumpCloud.

Tip: You can also import users from the JumpCloud Admin Portal from User Management > Users by clicking ( + ), then selecting Import from Google Workspace.

1. Log in to the JumpCloud Admin Portal.

2. Navigate to DIRECTORY INTEGRATIONS > Cloud Directories.

3. Select the integration you authorized when completing the steps in Authorizing Google Workspace Sync above. 

4. From the Details tab, confirm your attribute mapping and settings to ensure you are importing and exporting the proper attributes. See Sync User Attributes with Google Workspace to learn more.

Note: When users are imported from Google Workspace, JumpCloud populates the Username field with the username portion of the imported user's email address as it's configured in Google Workspace. For example, jo.lei@demoexample.com would have a username of jo.lei in JumpCloud. Users are created with only the attributes you want JumpCloud to control, which are those with import selected in the JumpCloud to import or export? column.

5. Click Import Users.

6. On the Import Users from Google Workspace screen, select one or more users to import.

Note: If you want to wait until later to import users, click cancel.

7. Click import users.

Note: Your first ten (10) users are free. Additional users count toward your total number of billable users. You can choose to import users at a later time.

8. You will receive an email with a link to the import results. If you imported fewer than 100 users, you will also see the results in the last step of the import flow.

Note: Users who were successfully imported have a green check mark. Users who weren’t imported have a red exclamation mark, and the Import message explains why a user wasn’t imported. When you close the import modal, you’re returned to the Google Workspace Directory Details panel.

You can see the state of new accounts in the Admin Portal Users list. The default user state for imported users will be either active or staged, depending on the Default User State for user Creation value set. 

Imported users must have an active user state and a password set by either you or them before they will have access to their assigned resources. They will continue to have access to Google using their Google password until the activation process is complete for their JumpCloud account, and they are given access to Google Workspace from JumpCloud.

To give JumpCloud users access to Google Workspace

After you authorize syncing for your Google Workspace directory, you can specify users and groups to manage from JumpCloud through the sync by associating them to that Google Workspace directory. Users can be given access to a Google Workspace directory either directly or through a user group.

Prerequisites

• An authorized and activated Google Workspace directory.

• Ensure that any users or groups, either preexisting or new, follow Google’s naming guidelines.

Considerations

• When you remove a user from a Google Workspace directory in JumpCloud, either directly or by removing them from all User Groups that disconnects them from the Google Workspace directory, the user is immediately suspended in Google Workspace and any existing Google sessions expire. After they’re disconnected, the user is unable to log in to any Google Workspace resources that are connected to that directory.

• Don’t add a Google Workspace directory more than once in JumpCloud. If you authorize sync for the same Google Workspace directory more than once, users that are connected to multiple instances of the same Google Workspace directory in JumpCloud could be suspended if you remove them from one of the instances. You can avoid this by deactivating the sync for duplicate Google Workspace directories. 

To connect users to a Google Workspace directory

From the user’s Directories tab

1. Log in to the JumpCloud Admin Portal.

2. Navigate to USER MANAGEMENT > Users.

3. Select a user to view their details.

4. Select the Directories tab.

5. Select the Google Workspace directory to which you want to connect the user.

6. Click save user. Synchronization will be initiated.

From the user group’s Directories tab

1. Log in to the JumpCloud Admin Portal.

2. Navigate to USER MANAGEMENT > User Groups.

3. Select a user group to view their details.

4. Select the Directories tab

5. Select the Google Workspace directory to which you want users in the user group to be synced and have access.

6. Select the Users tab.

7. Check the box next to each user you want added to the group. 

8. Click save. Synchronization is initiated.

Tip: You can also connect a user or user group from the Google Workspace directory sync configuration page. Navigate to Cloud Directories, select the Google Workspace Directory, select the Users or User Groups tab, then select the user(s) or user group(s) you want to give access to the Workspace directory and click save.

Note: Learn how to integrate your Google Workspace directories with JumpCloud in the Google Workspace Integration Overview.

Post connection behavior

After you connect a user to a Google Workspace directory:

• If the user didn’t previously exist in Google Workspace and the email sent as the PrimaryEmail matches a Google Workspace directory domain, a new, active user account is provisioned to Google Workspace 

Note: The Domains configuration for the integration will determine what happens If the user’s company email domain does not match the Google Workspace directory domain or the list of configured domains. 

• If the user resets their JumpCloud password, it’s synced to Google Workspace. When set, existing sessions to Google Workspace apps expire, and the user must log in again.

• After you connect a user to a Google Workspace directory, the flow differs slightly for staged and active users:

  • Staged user flow: A staged user is a user in a ‘staged’ user state with a password status of either ‘password pending’ or ‘active’. 

    • Staged users who do not already exist in the Google Workspace directory will not have access to Google Workspace until you change their user state to active and a password is set in JumpCloud. They will not receive welcome or activation emails until they are in an ‘active’ user state.

    • Staged users who already exist in the Google Workspace directory will remain active in that directory and will continue to have access. 

  • Active user flow: An active user is a user in an ‘active’ user state, has a password, and that password status is set to ‘active’. After you add an active user to your Google Workspace directory in JumpCloud, the user receives an email that tells them which directory they’ve been added to and to synchronize their password by logging in to their User Portal.

After you connect a group to a Google Workspace Directory

• If you enabled Google Workspace group management  and no distribution group with a matching email exists in Google Workspace, a distribution group is created in Google Workspace, and the JumpCloud group name and description are synced to the new Google Workspace distribution group.

• If you changed a user group’s membership in JumpCloud, the changes are synced to Google.

Managing the Google Workspace Directory Sync Integration

After synchronization with a Google Workspace directory is set up, you can perform the following maintenance tasks on the synced directory:

• To rename a Google Workspace Directory

• To disable Group Management

• To manage domains

• To reactivate Google Workspace Sync

• To deactivate Google Workspace Sync

To rename a Google Workspace Directory

You can rename a Google Workspace directory at any time in the Admin Portal. 

1. Log in to the JumpCloud Admin Portal.

2. Navigate to DIRECTORY INTEGRATIONS > Cloud Directories. 

3. Select the Google Workspace directory you want to rename.

4. Click the Pencil icon to edit the directory name.

5. Enter a new unique name for the directory.

6. Click outside of the name field to save the new name.

To disable group management

Important: If you disable group and membership management, no further changes are made to distribution groups in Google Workspace.

1. Navigate to DIRECTORY INTEGRATIONS > Cloud Directories.

2. Select the Google Workspace directory you want to manage groups for.

3. In the Google Workspace Sync section of the Details tab, deelect Enable management of groups and memberships in Google Workspace.

4. Click save.

To manage domains

If you add domains in Google Workspace, want to change which domains sync, or change which domain is used as the default domain for the integration, follow the instructions in this section.

To edit the domains list

1. Log in to the JumpCloud Admin Portal.

2. Navigate to Cloud Directories.

3. Click the M365/AAD directory instance in which you want to create and manage the group(s).

4. Click Edit Domains.

5. Click the radio button next to one of the domains to use that domain for the UserPrincipalName translation rule

6. Click save.

To change the default domain used for the integration

1. Log in to the JumpCloud Admin Portal.

2. Navigate to Cloud Directories.

3. Click the M365/AAD directory instance.

4. Click Edit Domains.

5. Click the domain name and make a new selection

6. Click Click +Add Domain.

7. Click the dropdown menu.

8. Select one of the domains from the list.

9. Repeat steps 5-8 until all changes have been made

10. Click save.

To remove domains from the list

1. Log in to the JumpCloud Admin Portal.

2. Navigate to Cloud Directories.

3. Click the M365/AAD directory instance in which you want to create and manage the group(s).

4. Click Edit Domains.

5. Click the trash icon next to the domain you want to remove from the list

6. Click save.

To change from using a default to not specifying a default domain

1. Log in to the JumpCloud Admin Portal.

2. Navigate to Cloud Directories.

3. Click the M365/AAD directory instance.

4. Click Edit Domains.

5. Click the radio button next to No default. Only users with matching domains sync.

6. Click save.

To reactivate Google Workspace Sync

To resolve connection issues, you may need to reactivate Google Workspace sync. You may also need to reactivate Google Workspace sync to refresh tokens for the Google Super Admin user account that maintains a persistent connection with JumpCloud through OAuth2.0. 

Note: Reactivating either with the same Google admin account or a different Google admin account will not disconnect users from the integration or disconnect their active Google Workspace sessions. It will also not send any notification to users.

1. Log in to the JumpCloud Admin Portal.

2. Navigate to DIRECTORY INTEGRATIONS > Cloud Directories.

3. Select the Google Workspace directory for which you want to reactivate sync and click reactivate sync.

4. Follow Google’s prompts to authorize JumpCloud.

To deactivate Google Workspace Sync

If you no longer want to sync a Google Workspace directory with JumpCloud, you can deactivate sync for it from the Cloud Directories tab of the Admin Portal. 

Warning: If you're experiencing connection issues or need to refresh tokens for privileged users, reactivate sync for the Google Workspace domain rather than deactivating the sync. Deactivation breaks sync for a Google Workspace directory and disconnects all connected users and groups. Only deactivate sync for a Google Workspace directory if you no longer need it to sync with JumpCloud.

1. Log in to the JumpCloud Admin Portal.

2. Navigate to DIRECTORY INTEGRATIONS > Cloud Directories.

3. Select the Google Workspace directory for which you want to deactivate sync and click deactivate sync.

After you deactivate sync for a Google Workspace directory

• Sync ceases between JumpCloud and the Google Workspace directory. 

• User attribute changes are no longer propagated from JumpCloud to Google Workspace.

• All users are removed / disconnected from the Google Workspace directory in JumpCloud and will no longer be managed by JumpCloud.

• Users won’t be affected.

  • All users in Google will remain ‘Active’ and will retain access to their respective Google Workspace applications.

  • All User accounts will remain Active in JumpCloud as well.  

A JumpCloud user bound to Google Workspace does not synchronize as expected.

• If provisioning from JumpCloud to Google, the user might not show up in the Google Apps Admin Console.

• Previously provisioned users don’t synchronize new passwords when reset in JumpCloud.

Cause
The username and/or password doesn't comply with Google's name and password guidelines. 

Resolution
Make sure the Gmail username and password comply with Google's guidelines.

If the above resolutions don't solve the issue, contact your JumpCloud administrator to verify your account status and assist in troubleshooting. If signing up for service, please submit a support request and confirm the email address being used in the form.