Chapter 7.3.2: Integrating with Google Workspace

Directory sync allows you to integrate your BullPhish ID client organization with Google Workspace to import targets and groups. Imported groups and targets are automatically synchronized with Google Workspace to keep group information up to date in BullPhish ID. 

This integration allows BullPhish ID to sync targets from Google Workspace, making it easy to manage phishing and training campaigns.

BullPhish ID supports dynamic and nested groups in Google Workspace.

Integrating BullPhish ID with an organization's Google Workspace involves three main steps (to navigate to a specific step, click the applicable link):

  1. Configuring a project in Google Cloud.
  2. Syncing BullPhish ID with Google Workspace.
  3. Syncing the desired groups in BullPhish ID.

Prerequisites  

  • Only partner administrators can configure the integration. 
  • You must have access to both BullPhish ID and Google accounts. 

Configuring a project in Google Cloud

Creating a project

To create a new project in Google Cloud IAM:

  1. In Google Cloud's Identity and Access Management (IAM) Access application, navigate to the Select a project page.
  2. Log into the Google Cloud Platform with your Super Administrator credentials.
  3. In the upper-right corner on the Select a project page, click Create Project.
    Create
  4. Enter a Project Name. Organization and Location are prepopulated but you can edit these if necessary.
    G1.png
  5. Click Create.

Enabling the Admin SDK API for your project

Enabling the Admin SDK API for your project allows you to view and manage resources such as users and groups.

To enable the Admin SDK API: 

  1. Go to the following page: https://console.cloud.google.com/apis/library/admin.googleapis.com.
  2. The project you created is already selected. 
  3. Click Enable.
    G2.png

Creating the service account and credentials

A service account and credentials are required for Google Workspace domain-wide delegation of authority. 

To create the service account and credentials: 

  1. Open the Service Accounts page.
  2. Select the project you just created.
    Create
  3. At the top of the page, click + Create Service Account.

    Create

  4. In the Service Account Name box, enter a name for the service account. The Service Account ID is auto-populated.
  5. In the Service Account Description box, describe what this service will do.
    Create
  6. Click Done
    Note: Clicking Create and Continue takes you through optional steps 2 & 3.
    Create

    The service account is added to the project's Service accounts table.
    Create

  7. Copy the service account's OAuth 2 Client ID by hovering over the ID number and clicking the Copy to Clipboard icon. 

    Important: Make sure you copy the OAuth 2 Client ID, NOT the Key ID. You will need this ID number in the next procedure, Delegate domain-wide authority to your service account.

    Client
  8. In the Actions column, click the three-dot menu and select Manage keys.
    Create
  9. Select Add Key > Create New Key.
    Create   
  10. In the Create private key modal, JSON should be selected. Click Create.

    G4.png
  11. Your new public/private key pair is generated. Save it on your computer. The JSON file is the only copy of this key. In the confirmation modal, click Close.
    Note: For information about service accounts, see the article Managing service account keys

Delegate domain-wide authority to your service account

To allow BullPhish ID access to user data on a Google Workspace domain, you need to grant access to the service account that you created. For more information about domain-wide delegation, see Control Google Workspace API access with domain-wide delegation.

To delegate domain-wide authority to a service account:

  1. Access the Google Admin console.
  2. In the navigation menu, select Security > Access and Data Control > API Controls.
    API
  3. In the Domain-wide delegation section, click Manage Domain Wide Delegation.
    API
  4. Click Add new.
    API
  5. In the Client ID field, paste the OAuth 2 Client ID you copied in step 7 in the previous procedure, Creating the service account and credentials.

    Note:
    If you need to copy the OAuth 2 Client ID, in the navigation menu in Google Cloud IAM, click Service Accounts.

    Add
  6. Copy the comma-delimited list of the following scope URLs required for your BullPhish ID project:

    Note: Copy the whole list at once.

    https://www.googleapis.com/auth/admin.directory.group.readonly,
    https://www.googleapis.com/auth/admin.directory.user.readonly, https://www.googleapis.com/auth/admin.directory.group.member.readonly

  7. In the OAuth Scopes field, paste the scope URLs.
    Note: All scope URLs will be pasted at once.
    Add
  8. Click Authorize.
    Add

Your service account now has domain-wide access to the Google Admin SDK Directory API for all your domain users. You are ready to instantiate an authorized Admin SDK Directory service object on behalf of your Google Workspace domain's users.

Syncing BullPhish ID with Google Workspace

To sync BullPhish ID with Google Workspace, you will use account information that was created when you completed the procedures above.

To sync BullPhish ID with Google Workspace: 

  1. Log into the BullPhish ID portal.
  2. In the navigation menu, select Targets & Groups > Directories.
  3. Click the + Add Directory Sync button.
    Add
  4. In the Add Directory Sync modal, complete the following:
    • Organization: Select the applicable organization
    • Directory Type: Select Google.
    • Impersonation Email: Enter a user's email address who has access to the Admin SDK Directory API. It could be the email address of your account. 
    • Service Account Credentials: Upload the JSON file you saved in step 11 in the procedure Creating the service account and credentials.
    • Directory Sync Preference: Select an option for handling targets in BullPhish ID after they have been deleted from Google.
      Dir sync Google.png
      Impersonation Email Note
      : Only users with access to the Admin APIs can access the Admin SDK Directory API. Therefore, your service account needs to impersonate one of those users to access the Admin SDK Directory API. This means that in the Impersonation Email box, you need to enter the user's email address who has access to Admin SDK Directory API. It could be the email address of your account.
  5. Do one of the following:
    • Click Save.
    • Click Save & Sync.  The sync is executed and the Edit Directory page for the organization is displayed.
      Now you are ready to import and sync groups or targets from Google Workspace. Refer to the article, 7.3.4 Syncing Groups and Targets.

Revision Date posted
Reviewed and edited. 7/24/23

Syncing BullPhish ID with Google Workspace - Step 4: Updated Directory Sync Pref screenshot.

12/4/23

 

Intro para: Added - BullPhish ID supports dynamic and nested groups in Google Workspace.

2/21/24

 

Have more questions?

Contact us

Was this article helpful?
0 out of 0 found this helpful

Provide feedback for the Documentation team!

Browse this section