Google User Provisioning (GUP)

Google User Provisioning (GUP) Guide

Google User Provisioning (GUP) is an automated method for importing users from your Google Workspace tenant directly into your KnowBe4 console. This integration allows you to use data from Google Workspace to provision users in your KnowBe4 console. Changes that you make to your users’ information and statuses in Google Workspace will sync automatically to your KnowBe4 console. Once you have configured the integration, you’ll be able to manage all your users from one place.

This integration requires you to have access to a Google super-admin account. The admin account must have the permissions to configure the six Google scopes that are required by this integration. For the full list of required scopes, see the What You Will Need section of this article. If you are not a Google customer, KnowBe4 also offers other methods of automated user provisioning. For further information about alternative user provisioning methods, see our SCIM Configuration Guide or our Active Directory Integration (ADI) Configuration Guide.

How GUP Works

Using your Google Customer ID and your KnowBe4 Client ID, you can configure a direct connection between your Google Workspace environment and your KnowBe4 console. Once this connection has been established, you can configure which of your Google Workspace users and groups you would like to sync into your KnowBe4 console. Changes that you make to your users in Google Workspace will be reflected automatically in your KnowBe4 console.

This sync is an automated process that occurs repeatedly throughout the day. Syncs will occur every six hours at minimum. The sync is a one-way process, and any changes made to users in your KnowBe4 console will not sync to your Google Workspace environment. Changes made to users directly in your KnowBe4 console will be overwritten by the data in Google Workspace. Any users in your KnowBe4 console who are not present in Google Workspace will be archived during the next GUP sync.

Note: You have the option to prevent any specific users from being managed by GUP. To prevent specific users from being managed by GUP, create a CSV file with a list of users that you don’t want to be managed by GUP. Enter “false” under the Provisioning Managed heading for those users.

Prerequisites

  • You must have admin access to your organization's KnowBe4 console.
  • You must have super-admin access to Google Workspace.

Configuring Your Google Workspace Connection

In order to configure GUP, you’ll need to connect your KnowBe4 console to your Google Workspace tenant.

What You Will Need

You will need to gather the KnowBe4 Client ID and list of six scopes from your KnowBe4 Account Settings in order to complete the connection to Google Workspace. This information can be found by navigating to your Account Settings, clicking User Management > User Provisioning, and then toggling the Google button, as shown in the screenshot below:

Additionally, you will also need your Google Customer ID and Google super-admin email address when configuring the connection in your KnowBe4 Account Settings. This information is located in your Google Admin center. You can find it by logging in at admin.google.com, and then clicking Account > Account Settings. Your customer ID is shown at the top of the list.

Once you have the information listed above, you can begin configuring the Google Workspace connection.

Google Workspace Configuration

To connect Google Workspace and your KnowBe4 console, follow the steps below:

  1. Log in at admin.google.com.
  2. From the home page of your Google Admin center, click Security > Access and data control > API controls.
  3. Click Manage Domain Wide Delegation.
  4. On the next screen, click Add New.
  5. You will need to enter the KnowBe4 Client ID from your Account Settings, along with the list of six scopes.
    Note: Each scope will need to be separated by a comma.
    Once you have entered this information, click Authorize. You should now see KnowBe4's GUP listed in the API clients list.

KnowBe4 Account Settings Configuration

Once you have completed the above steps, you can configure the connection from your KnowBe4 console to Google Workspace.

  1. Log in to your KnowBe4 console.
  2. Navigate to your Account Settings by clicking your username, then clicking Account Settings in the drop-down menu.
  3. Click User Management > User Provisioning, and then toggle the Google button.
  4. Enter your information into the Google Workspace Customer ID and Google Workspace Admin Email Address fields. Instructions for locating your Google Workspace Customer ID can be found in the Configuring Your Google Workspace Connection section above. Once you have entered the information, click Save.If your connection was successful, you will see a “Connection saved” message, as shown in the screenshot above. You can then click Configure Google Provisioning User Scoping to begin configuring the users that you would like to import into your KnowBe4 console. For further instructions, see step 1 in the next section.

Configure Google Provisioning

Now that you have successfully connected your KnowBe4 console to Google Workspace, you can begin provisioning your users. If you have not yet established the Google Workspace connection, see the Configuring Your Google Workspace Connection section above.

Prior to running your first sync, we strongly recommend keeping your KnowBe4 console in Test Mode in order to verify that you are happy with the results of your sync. Test Mode enables you to see the users who would be included in your sync before they are added to your KnowBe4 console. This will allow you to make any necessary adjustments to your configuration prior to any users actually being provisioned. For further information about placing your console into Test Mode, see the User Provisioning section of our KnowBe4 Console Account Settings: User Management article.

User Scoping

To begin configuring your User Scoping, follow the steps below:

  1. After logging in to your KnowBe4 console, navigate to Users > Provisioning.
  2. In the top-right corner, click the Configure Google Provisioning button.

Before continuing, you’ll need to determine how you would like to sync your users into your KnowBe4 console. You’ll have the option to sync by domain and group membership, OU scoping, or a combination of both methods. We generally recommend that customers start by adding a domain and then configuring users and groups for syncing. This method is the only method that allows you to sync group membership information into your KnowBe4 console.

If you would like to sync users by adding a domain and configuring groups for syncing, proceed to the Syncing By Domain and Group Membership section below. If you would like to use OU scoping to sync your users, navigate to the Syncing By OU Scoping section.

Note: Both methods can be used simultaneously to sync users.

Syncing By Domain and Group Membership

You can use this method if you would like to sync groups of users or individual users. You can choose to include or exclude groups or users, as well as sync group membership information about your users into your KnowBe4 console.

  1. Click the +Add Domain button.This will allow you to select a domain from which to import your users. In order to import a user into your KnowBe4 console, you will need to select the Google domain in which they currently reside. The list of currently available domains will appear in the drop-down menu. Once you have selected a domain, click Save.
    Note: The domain must be an Allowed Domain on your account. For further information regarding adding an Allowed Domain, see our Add and Verify Domains article.
  2. You will now see the domain included in the User Scoping section. Click the arrow next to the domain name to expand the drop-down menu.Here, you’ll see options for configuring the users and groups you want to include in the sync. You also have the option to exclude groups and users from syncing. Excluding a group or user will take precedence over including them. For example, if you include a group for syncing but exclude a specific user who resides in that group, all users in the group will be provisioned except for that specific user.
    1. Manage Groups: This button allows you to select groups from your Google Workspace environment. You can specify which groups you would like to include for syncing, and you can also choose to exclude specific groups from the sync. This option may be useful if there are nested groups that you would like to exclude from a larger group. A nested group is a Google group that is a member of another group, and it will be included by default during the sync unless it is manually excluded.

      Group names must be unique in order to sync into your KnowBe4 console, even if they are located in different domains.

      Note: You will need to type the name of the group that you would like to include or exclude in order to select them from the drop-down menus. You must type at least two characters of the group name in order for it to appear in the menu.
      When you have finished configuring your included and excluded groups, click Save
    2. Manage Users: This button allows you to select users from your Google Workspace environment. You can specify which users you would like to include for syncing, and you can also choose to exclude specific users from the sync. The Sync All Users in this Domain check box will allow you to provision all users who are associated with the domain. Users that have been excluded from syncing will not be provisioned when this check box is selected.
      Note: You will need to type the email address of the user that you would like to include or exclude in order to select them from the drop-down menus. You must type at least five characters of the user’s email in order for it to appear in the menu.
      When you have finished configuring your included and excluded users, click Save.
  3.  Once you have configured your groups and users, click Save Configuration.
  4. The button will change to Sync Now. If you will not need to configure OU scoping or Field Mapping in addition to your user and group settings, you can click this button to begin syncing your users from Google Workspace. If you would like to also configure OU scoping or Field Mapping in addition to your group membership configuration, continue to the sections below.

Syncing By OU Scoping

If you would like to configure GUP to sync users using OUs, click the Enable OU Scoping toggle switch. This will give you the ability to specify OUs from your Google Workspace environment for inclusion in your sync. You can use this method in addition to configuring users and groups for syncing, or you can use the OU scoping method on its own.

OU scoping supports nesting when searching for users. For example, if you are including an OU for syncing, GUP will include all users who are part of that OU, as well as any users contained within OUs that are nested under it. If you sync users using only OU scoping, group membership information will not be synced to your KnowBe4 console. If you would like to sync group membership information from Google Workspace, you will need to specify user and group information as outlined in the Group and User Inclusion or Exclusion section above.

To configure OU scoping for your users, follow the steps below:

  1. Click the Enable OU Scoping toggle switch.
  2. This will enable menus for Including or Excluding OUs. You can select the OUs that you would like to include or exclude in your sync.
  3. Once you have configured the OUs for syncing, click Save Configuration.
  4. When you are satisfied with your configuration choices, click Sync Now to run your sync.

Alternatively, if you would like to configure field mapping for your users prior to running your first sync, see the Field Mapping section below before continuing with syncing.

Field Mapping

The GUP sync supports syncing standard Google user attributes into your KSAT console. Configuring the Field Mapping section for your users is optional. By default, the GUP sync will include and map the following Google attributes to their corresponding KSAT attributes:

Google User Provisioning Default Attributes
Google Directory Attribute KSAT Attribute
givenName First Name
familyName Last Name
workPhone Phone Number
externalID Employee Number
orgTitle Job Title
orgName Organization
orgDepartment Department
None Mobile Phone Number
None Location
None Division
None Custom Field 1
None Custom Field 2
None Custom Field 3
None Custom Field 4
Note:Certain values such as the Manager Email and Manager Name field will sync by default if populated in your Google Workspace tenant.

If you would like to make adjustments to the default attributes that are included in the sync, follow the steps below:

  1. Navigate to the Configure Google Provisioning page, as shown in steps 1 and 2 in the User Scoping section above.
  2. In the Field Mapping section, click the drop-down arrow next to Mapping Rules.
  3. This action will expand the Field Mapping section.
    1. Google Directory Attribute: This column includes your users’ data and attributes as they appear in your Google Workspace environment. You can click the drop-down arrow next to the name of a Google Directory Attribute to open the drop-down menu that contains additional attributes for selection. The attribute that you select on the left side of the screen will be mapped to the adjacent KSAT Attribute on the right side. At this time, primary attribute types are the only attributes that are supported for syncing.
    2. KSAT Attribute: This column includes your users’ attributes as they will appear in their User Information subtab in your KnowBe4 console. Selections that are made in the Google Directory Attribute column will be mapped to these attributes.

      For example, in the screenshot below, the “workPhone” attribute from Google Workspace will be mapped to the Phone Number attribute in your KnowBe4 console.

      You can choose to map any available Google Directory Attribute to the KSAT Attribute of your choice by changing the Google Directory Attribute in the drop-down menu, as shown in the example below.

  4. Once you have made your Field Mapping selections, click the Save Configuration button at the top-right corner of the page.
  5. The button will change to Sync Now. You can click this button to run your sync, as shown in step 6 of the User Scoping section above.
    Note: Once you are satisfied with the results of your GUP test mode syncs you will need to disable Test Mode in your Account Settings in order for your Google users to begin syncing to your KnowBe4 console.

Troubleshooting

In this section, you will find error messages related to GUP, along with potential causes.

GUP Error Messages
Error Message Cause
Google Admin email connection is no longer valid.

This error message can have several causes:

  • The Google super-admin email address that was used to configure the Google Workspace connection has been archived in your Google Workspace tenant.
  • The Google super-admin email address that was used to configure the Google Workspace connection no longer has super-admin permissions.
  • One or more of the scopes that were used to configure the Google Workspace connection have been removed.
Google domain connection is no longer valid. This error message occurs when the domain used in the provisioning configuration no longer exists in your Google Workspace tenant.
Invalid admin email. This error message occurs when entering your Google super-admin email address in your KnowBe4 Account Settings. This message means that the email address formatting is incorrect.
Sync error.

The Credentials tab will show if there’s an error in your sync. If no errors are present, the Domains, Credentials, and OU sync subtabs will be hidden.

If you have any questions or experience any issues with your configuration, submit a ticket at https://support.knowbe4.com/hc/en-us/requests/new.

Can't find what you're looking for?

Contact Support