Integrating with Google Workspace

Create a project

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.
   
4. Enter a Project Name. Organization and Location are prepopulated but you can edit these if necessary.
   
5. Click Create.

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

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.
   

Create the service account and credentials

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

1. Open the Service Accounts page.
2. Select the project you just created.
   
3. At the top of the page, click + Create Service Account.
   
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.
   
6. Click Done. 
   

NOTE  Clicking Create and Continue takes you through optional steps 2 & 3.

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

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.

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

1. Access the Google Admin console.
2. In the navigation menu, select Security > Access and Data Control > API Controls.
   
3. In the Domain-wide delegation section, click Manage Domain Wide Delegation.
   
4. Click Add new.
   
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.

6. Copy the comma-delimited list of the following scope URLs required for your BullPhish ID project. 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 (all will be pasted at once).
   
8. Click Authorize.
   
   

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.

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

1. Log into the BullPhish ID portal.
2. In the navigation menu, select Targets & Groups > Directories.
3. Click the + Add Directory Sync button.
   
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.
     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.
     
   • 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.
     
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, Syncing groups and targets.