Google Workspace

This guide walks you through connecting Herd with Google Workspace, allowing your organization to sync users and groups for training and simulation management using your existing directory.

Google Workspace Overview

Herd allows organizations using Google Workspace as their Identity provider to sync users and groups for training and simulation assignment and management. Herd utilizes Google’s Admin SDK API through the Google Cloud Console.

Please Note: You’ll need to have administrator privileges in Google cloud and Google Workspace to complete this integration.

Step 1 – Create a Google Cloud project

Begin by creating a separate Google Cloud Project for this integration. This will allow for simple management and no conflicts with other Google Cloud integrations you may add in the future.

  1. Open Your Google Cloud Console, as an administrator.

  2. On the top toolbar, click the box that says, Select A Project.

  1. On top left of the modal pop-up, select your organizations domain. Then select New project.

  2. Name the project Herd Integration

  3. Select your organization and location.

  4. Select any location based on your preference.

  1. Click the blue Create button.

Note: It may take several minutes for the project to create. It must be fully created before moving on to step 2. Check the progress within your Google Cloud notifications.

Step 2 - Select the Project

Ensure you’ve selected the Herd project created in Step 1.

  1. Select the box on the top toolbar with your organization name.

  1. Select the project Herd Integration

You’ll be operating in this new project for the rest of the integration.

Step 3 – Enable the Admin SDK API

For this integration, we’ll utilize Google’s preexisting Admin SDK API.

  1. Select the hamburger stack symbol, to the left of the Google Cloud logo, in the top toolbar.

  2. Within the navigation, go to APIs & Services and select Enabled APIs & Services.

  3. Select the + Enable APIs and services. At the top of the section. You’ll be taken to Google API Library

  1. In the search box, type in Admin SDK API.

  2. Once found, select Admin SDK API, then click Enable.

Step 4 – Create a Service Account

A dedicated service account, with domain-wide access, is needed to sync all group membership.

  1. Check the top toolbar and ensure you’re within the Herd project

  2. Select the hamburger icon to open the left side navigation, go to IAM & Admin and select Service Accounts.

  3. Select + Create service account on the top toolbar

  1. Enter a service account name, for example: herd-integration Then put a service account description For Herd Integration. The service account ID should automatically populate.

  2. Click Create and Continue.

  3. Skip role and user access (leave defaults) and click Done.

This creates the dedicated identity Herd will use to access your domain data via APIs.

Step 5 - Save Service Account Details

You’ll need the new service account OAuth2 Client ID For Step 8

  1. Copy and save the OAuth 2 Client ID. It is within the row that populated on the service account page and should be a 20-character string of numbers, for example: 234567890192872817

Step 6 - Grant IAM Permissions To Service Account

  1. Select the hamburger logo on the top left, next to the Google Cloud logo.

  2. Hover over IAM & Admin and select IAM.

  3. On the top toolbar, select the Herd Integration project in the box right of the Google Cloud logo.

  4. Switch to the Organization level, by select the Organization domain that the Herd Integration Project is within. This is likely your companies domain.

  1. When the page updates, select the + Grant Access button

  2. With the Add Principals box, add the email of the account you’re currently logged into as an administrator in the google cloud console. This is likely your generic organizational email. Example: <user>@google.com

  3. Under Assign Roles select the dropdown box and search for Organization Policy Administrator . Once found, select it. Then Save.

Step 7 - Disable Legacy Service Key Creation Policy

By default, Google Cloud has an IAM policy that doesn’t allow the creation of JSON keys for service accounts, which is needed for the next step of this integration. We’ll need to disable this IAM policy.

  1. On the top toolbar, select the box with your Herd project and go back to the your organization.

  2. Select the hamburger logo, hover over IAM & Admin and select Organization Policies.

  3. Scroll down slightly to the filter box above the table that lists all active and inactive policies. Copy and paste: iam.disableServiceAccountKeyCreation and hit enter.

  4. Select the policy name Disable Service Account Key Creation, it’ll match the ID that we pasted above.

  5. On the right, select the pencil icon with Manage Policy.

  6. Select the radio button next to Inherit Parents Policy.

  7. Click Set Policy.

  8. The status should show “Not Enforced” in the box below.

Step 8 – Create and Download JSON Key

  1. On the top toolbar, select the box with your organization and go back to the Herd Integration Project.

  1. Select the hamburger icon on the top toolbar, and hover over IAM & Admin then select Service Accounts.

  2. Select the Service Account created in Step 4.

  3. On the next page, there will be multiple tabs. Select the one that says Keys.

  1. Down the page, you’ll find a dropdown that says Add Keys. Select it and select Create New Key.

  2. Select JSON, then click Create.

  3. A JSON key file is downloaded to your computer.

  4. Copy and save the key for use in the next step.

    Treat this JSON file as a secret and store it securely. It grants API access when combined with domain-wide delegation.

  • Note: If you get an error that the organizational policy is blocking the service account key creation, go back and ensure that step 6 was performed properly.

Step 9 – Configure domain-wide delegation in the Admin console

  1. Open a new tab in your browser and go to the Google Admin console as a super admin:

    https://admin.google.com

  2. On the left side toolbar, look for the Security dropdown. Note that it may be hiding under a “show more” button.

  3. Select Security → Access and data control → API Controls.

  4. On the bottom of the newly loaded page, look for the box named: Domain-wide Delegation. Select Manage Domain Wide Delegation.

  1. You’ll be taken to a page titled API Clients. In the top toolbar, select Add New.

  2. In Client ID, paste the Client ID of the herd-integration service account that was created in Step 5.

  3. In OAuth scopes, enter the following scopes:

    • https://www.googleapis.com/auth/admin.directory.user.readonly

    • https://www.googleapis.com/auth/admin.directory.group.readonly

    • https://www.googleapis.com/auth/admin.directory.customer.readonly

  • Note: You’ll need to enter each row separately. Entering them on one line will not work.

  1. Click Authorize.

These scopes grant read-only access to users, groups, and customer information, which is sufficient for Herd to discover and sync users and groups.

Step 10 – Connect Herd to Google Workspace

  1. Open a new tab and login to your Herd Security admin console.

  2. On the left side toolbar, select Administration.

  3. Scroll down to the Google Workspace Integration section and select the dropdown arrow next to Google Workspace Configuration Settings.

  4. Provide the following values:

    1. Google Workspace Domain: yourcompany.com

    2. Admin Email: The Admin Email within the same domain that is a super admin within Google Workspace.

    3. Service Account JSON Key: Paste the key that was created in Step 8

  1. Select Save Google Workspace Configuration

Step 11 - Confirm User Sync

  1. On the same page, select the Sync Google Workspace Users

  2. If successful, a status box with the last time grouped sync will appear.

You can now successfully assign trainings to groups of users from your Google Workspace!

PreviousAPI Documentation

Last updated