Configure the Google Workspace Integration

The next step in creating a secure and consistent connection between JumpCloud and Google Workspace is configuring the integration. You can control the user data that syncs, which platform should be the source (JumpCloud or Google), whether distribution groups are managed from JumpCloud, the email domains that are allowed to sync, and if there is a default domain that should be used.

Prerequisites

• A JumpCloud administrator account
• JumpCloud Device Package or higher
• An authorized and active Google Workspace instance
• A Google user account with the following roles:
  • Groups Admin (pre-built role)
  • User management Admin (pre-built role)
  • Custom role with ‘Domain Management’ admin API privileges
• You have read through the considerations in Get Started: Google Workspace Integration

Attribute Considerations

• The JumpCloud owned attributes (email, firstname, lastname) are required by Google and bidirectionally sync
• Optional attributes sync one way:
  • Attributes set to Import will not be exported from JumpCloud to Google Workspace 
  • Attributes set to Export will not be imported from Google Workspace to JumpCloud
  • Attributes set to Exclude will not be imported or exported
  • Different attributes in the sync can be set to Import or Export, e.g., you can set password to Export and costCenter to Import in the same sync
• The default setting for optional attributes, except user state and password, is Exclude
• The default setting for the user state and password attributes is Export
• The password and manager attributes can only be set to Export or Exclude
• Address attributes – both the JumpCloud and Google Workspace APIs allow multiple addresses for a given type. On export, existing Google Workspace addresses for a given type will be replaced with JumpCloud addresses of that type

Configure User Attributes

After you've authorized the Google Workspace instance in JumpCloud, choose the user attributes you want to import, export or exclude. This functionality allows you to centralize the management of these users.

Attribute Data Flow

How does attribute data flow between Google Workspace and JumpCloud after integration? 

• When you import a user from Google Workspace – if data exists for a user’s attributes in Google Workspace when they are imported, data is written to the equivalent user attributes in JumpCloud
• Importation of these attributes must be done before the user exists in JumpCloud
• When you connect that user to Google Workspace in JumpCloud – attributes in Google Workspace are automatically overwritten with data from JumpCloud for the attributes set to Export. Further, any subsequent changes made to the user’s attributes in JumpCloud are automatically pushed to the corresponding attributes in Google Workspace

User Attribute Import

First name, Last name, and Company email will always be imported from Google Workspace. With the exception of user state and manager, you can choose the optional user attributes that you would like to import from Google Workspace for new users and updates. Your chosen attributes will be mapped from Google Workspace to the corresponding JumpCloud attribute.

User Attribute Export

First name, Last name, and Company email will always be exported to Google Workspace. You can choose the optional user attributes you would like to export to Google Workspace. Your chosen attributes will be mapped from JumpCloud to the corresponding Google attribute. If you choose to stop exporting data for an attribute, it is no longer synced with Google Workspace. Subsequent changes made to that attribute in JumpCloud aren't exported to Google Workspace.

User Attributes

Required attributes

These attributes are “JumpCloud owned” and always imported from Google Workspace to JumpCloud, and exported from JumpCloud to Google Workspace for bound users:

• email
• firstname
• lastname

Optional attributes

Attributes that can only be optionally exported to Google Workspace:

• password *
• manager

Attributes that can optionally be exported to or imported from Google Workspace:

• user state *
• addresses (home)
• addresses (work)
• alternate email
• costCenter
• department
• employeeIdentifier
• employeeType
• jobTitle
• phoneNumbers (home)
• phoneNumbers (mobile)
• phoneNumbers (work)
• phoneNumbers (work_fax)
• phoneNumbers (work_mobile)

(*see Impact of the user state and password settings for additional considerations when making selections for these attributes)

API Attribute Name Table

The following table outlines how attribute data is exported from JumpCloud’s API and UI to Google Workspace's API and UI. The attribute listed in the JumpCloud API Attribute Name column is synced to the attribute listed in the Google Workspace API Attribute Name column. The attribute listed in the JumpCloud UI Attribute Name column is synced to the attribute listed in the Google Workspace UI Attribute Name column. See our API documentation for more information.

To select attributes to export or import

1. Log in to the JumpCloud Admin Portal.
2. Go to DIRECTORY INTEGRATIONS > Cloud Directories.
3. Select the Google Workspace directory you want to select user attributes for.
4. In the Attribute mapping and settings section, select the non-default user attributes you want to import or export with Google Workspace.

5. Click Save.

Directory Insights Events

Anytime you change the direction of an attribute, a Directory Insights event is generated. Previously, these events were:

• translationrule_create
• translationrule_delete

If you see an event with these names in your Directory Insights logs, they will roll off once your maximum retention period is exhausted. Going forward, the Directory Insights events generated from attribution selections are:

• integrationattribute_exclude
  • Generated when an attribute is set to “Exclude”.
    • Ex: You change the Department attribute from “Import” to “Exclude”
• integrationattribute_include
  • Generated when an attribute is set to “Import” or “Export”.
    • Ex: You change the Department attribute from “Exclude” to “Import”
    • Ex: You change the Department attribute from “Import” to “Export”

These events will capture attribute ownership/direction changes, including the admin that made the change, and the directory integration in which the change occurred.

Configure User Password Settings

In the Admin Portal, there are Password Configuration Settings that allow you to customize what happens to a user’s account in Google Workspace when their JumpCloud password gets locked out or expires. These settings are impacted by your selections for password and user state attributes in the Attribute mapping and settings section.

To access the Password Configurations settings

1. Log in to the JumpCloud Admin Portal.
2. Navigate to Settings > Security > Password Configurations > Google Workspace.
3. Under your Google Workspace instance, select your desired options for Password Expiration and Account Lockout.
4. After any changes are made, click Save.

Impact of the user state and password settings

The table below shows how the settings for password and user state attributes impact the the Password Configurations settings for password expiration and account lockout.

Configure 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 group memberships in JumpCloud.

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
• Managing a Google dynamic group from JumpCloud is not supported. Making manual changes to members of a Google dynamic group is not allowed and will fail with an Error 412: Condition not met, conditionNotMet error.
  • You can sync a JumpCloud dynamic group to a static group in Google
  • If you have a group in JumpCloud with the same name and email as a dynamic group in JumpCloud, do not add the email for the group in the Users Group tab to prevent group memberships errors

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.
   • Enter the email address for the Google Workspace admin account you are using for the integration if prompted.
   • Enter the password for the Google Workspace admin account you are using for the integration if prompted.
   • Click Allow.

To specify Distribution Groups

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

To specify a Google Workspace Distribution Group

1. Navigate to DIRECTORY INTEGRATIONS > Cloud Directories.
2. Select the Google Workspace directory to which you want to manage groups.
3. Select the User Groups tab.
4. In your desired group, add an email address in the Distribution Group Email field.

5. Click Save.

When you associate 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. See Giving JumpCloud Users Access to Google Workspace to learn how to associate user groups to a Google Workspace Directory.

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 DIRECTORY INTEGRATIONS > Cloud Directories.
3. Select the Google Workspace directory instance.
4. In the Google Workspace Domain(s) section, click +Add Domain.
5. The first time you add a domain, you will be redirected to the authorization flow to approve the domains permission.
   • 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.
   • Enter the password for that account if prompted.

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.

10. Repeat steps 4-6 to add additional domains.
11. Click Save.

To enable a default domain

1. Log in to the JumpCloud Admin Portal.
2. Navigate to DIRECTORY INTEGRATIONS > Cloud Directories.
3. Select the Google Workspace directory instance.
4. In the Google Workspace Domain(s) section, select the radio button next to one of the domains to use that domain for the PrimaryEmail translation rule (default domain).
5. Click Save.