> For the complete documentation index, see [llms.txt](https://herd-security.gitbook.io/herd-security-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://herd-security.gitbook.io/herd-security-docs/google-workspace/google-workspace.md).

# Google Workspace

## 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*.

<figure><img src="/files/d7RvgvBSmIoSjG99jnXx" alt=""><figcaption></figcaption></figure>

3. On top left of the modal pop-up, select your organizations domain. Then select *New project.*
4. Name the project *Herd Integration*
5. Select your organization and location.
6. Select any location based on your preference.

<figure><img src="/files/qjlRmZbm8ISZ7oMAuwod" alt=""><figcaption></figcaption></figure>

7. Click the blue **Create** button.

{% hint style="info" %}
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.
{% endhint %}

### 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.

<figure><img src="/files/FDRwIlBUv96CypPllIPU" alt=""><figcaption></figcaption></figure>

2. Select the project *Herd* *Integration*

<figure><img src="/files/7NRzY3np8PJ1YLVQ73Qx" alt=""><figcaption></figcaption></figure>

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

<figure><img src="/files/fnefynw9hIEgwBaS0o7z" alt=""><figcaption></figcaption></figure>

4. In the search box, type in **Admin SDK API.**
5. Once found, select **Admin SDK API**, then click **Enable**.

<figure><img src="/files/OZmTIdLTBHHJWW3Kr1kd" alt=""><figcaption></figcaption></figure>

### 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

<figure><img src="/files/6pVNsAJt0CmMYntyHgZK" alt=""><figcaption></figcaption></figure>

4. 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.
5. Click **Create and Continue**.
6. 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 selecting the Organization domain that the Herd Integration Project is within. This is likely your company's domain.

<figure><img src="/files/WdBHHnOWilX9zswLF0go" alt=""><figcaption></figcaption></figure>

5. When the page updates, select the *+ Grant Access* button
6. 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>@yourcompany.com`
7. Under **Assign Roles** select the dropdown box and search for `Organization Policy Administrator` . Once found, select it. Then **Save.**

<figure><img src="/files/svmmLkuuwqkjB2GYu8tO" alt=""><figcaption></figcaption></figure>

### 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.

<figure><img src="/files/hrvSayjY6Jj8gL5Ut9ep" alt=""><figcaption></figcaption></figure>

### 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.

<figure><img src="/files/7NRzY3np8PJ1YLVQ73Qx" alt=""><figcaption></figcaption></figure>

2. Select the hamburger icon on the top toolbar, and hover over **IAM & Admin** then select **Service Accounts.**
3. Select the Service Account created in Step 4.
4. On the next page, there will be multiple tabs. Select the one that says **Keys.**

<figure><img src="/files/cyanZFcVeQpsF2zF6ysy" alt=""><figcaption></figcaption></figure>

5. Down the page, you’ll find a dropdown that says **Add Keys**. Select it and select **Create New Key.**
6. Select **JSON**, then click **Create**.
7. A JSON key file is downloaded to your computer.
8. 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.

<figure><img src="/files/qwaCj3vCvwona6N9YosH" alt=""><figcaption></figcaption></figure>

### 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.**

<figure><img src="/files/JScbNWpRNNa15bqdMHwP" alt=""><figcaption></figcaption></figure>

5. You’ll be taken to a page titled API Clients. In the top toolbar, select **Add New.**
6. In **Client ID**, paste the **Client ID** of the **`herd-integration`** service account that was created in Step 5.
7. 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 **Settings**, then switch to the **Integrations** tab — the **Google Workspace** card lives in the **Identity** section.
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

<figure><img src="/files/LOxRPAZfCYTiiTXvJ5vX" alt=""><figcaption></figcaption></figure>

5. 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.

<figure><img src="/files/Q1FTHAAncr0fDdcDfE1n" alt=""><figcaption></figcaption></figure>

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