Help CenterThis feature is coming soon!
ThreatLocker now allows users to create a Google Workspace Integration that permits ThreatLocker to access logs within your Google Workspace Organization. With this Integration in place, Cloud Detect can leverage the collected logs to alert and/or lock out accounts based on customizable criteria and thresholds.
Due to the nature of Google Workspace, you must follow a few steps to fully set up your ThreatLocker Integration. To complete your Google Workspace integration, the following requirements must be met:
- Must be a Google Workspace Super Admin
- Must have Google Cloud Access
- Must have a Google Cloud Project for ThreatLocker
- Must have a dedicated user admin account for ThreatLocker, ensuring that you do not have to use a personal administrator account for this Integration
- Must be able to create service account keys
Creating a Google Cloud Project
The purpose of the Google Cloud project for this integration is to enable the Google Workspace APIs.
To start, navigate to your Google Cloud Console using the provided link.
From here, select the Project Picker found at the top left side of the page.
Selecting this option opens a dialogue window titled "Select a resource." From this window, select the New project button found in the top right corner.
Selecting the New Project button will open a page titled New Project. Here, insert your Project Name, Organization, and Parent Resource. Once this information has been entered, select the Create button underneath the entry fields.
Once done, you will be taken out of the New Project creation page. From here, select the Project Picker again to open the Select a resource dialogue window, then select the project you just created.
Selecting this will open the Project.
Enabling APIs for your Project
Within your newly created Google Cloud Project, navigate to the Navigation Menu found in the top left corner of the page.
In the Navigation Menu, hover over the APIs & Services option and select Library.
Now, in the API Library, use the search bar to search for the following APIs:
- Admin SDK API
- Google Workspace Alert Center API
Select both APIs and enable them in your Google Cloud Project.
Creating the Service Account and Copying the Client ID for Domain-Wide Delegation
Navigate to the Navigation Menu found in the top left corner of your project’s page.
Within the Navigation Menu, hover over IAM & Admin and select Service Accounts from the dropdown menu.
Within the Service Accounts page, select the + Create service account button found at the top of the page.
Selecting this button will open the Create service account page. From the Create Service Account section:
- Enter a clear, recognizable name for your Service Account.
- Google will automatically create a Service Account ID based on what you entered for your Service Account Name.
- This name cannot be changed after your information is saved.
- You can enter a Service Account Description, but it is not required.
- Select the Create and continue button once you have entered all desired information.
The following two sections, labeled Permissions and Principals with access, are optional. Once you have entered all desired information, select the Done button.
After Done is selected, you will be brought back to your Service accounts page. From here, select the name of the Service account you just created.
In the Details tab, navigate to the Advanced Settings dropdown and expand it. Then, under Domain-wide Delegation, copy and securely save the Client ID. This will be used again in the Authorization of Domain-Wide Delegation section later in this article.
Creating a Dedicated Google Workspace Admin
Now, navigate to your Google Workspace Admin console using the following link:
From here, using the left-hand side of the page, select Directory, then select Users from the list of dropdown options.
Selecting this option will open the Users page. From here, select the Add new user button at the top of the user list.
This will bring you to the Add new users page. Here, fill out the information to add to your dedicated Google Workspace administrator account for the ThreatLocker Integration. Once this information has been added, select the Continue button at the bottom of the page.
Make sure this email address is recorded. This is the email address that will be used in the Account Email Address field during your integration setup.
Note: Google notes that it can take up to 24 hours for Google services to become available to a newly-created user account.
Assigning Administrator Privileges to Your Dedicated User
Note: If ThreatLocker attempts to perform API actions that your admin account is not authorized to perform, it could lead to unexpected failures. Please take this into consideration when assigning privileges to your administrator account.
After you create the Dedicated User Administrator account for your ThreatLocker Integration, you will need to grant the user administrator privileges. You have two options for applying administrator privileges to the Dedicated User Account:
- Assign the Dedicated User Account the Super Admin role.
- This method is the easiest to apply and the most reliable way to avoid permission errors when setting up your Google Workspace Integration.
- Create a custom administrator role that grants only approved capabilities from your organization.
- This method is more difficult to apply, but it grants the least amount of privilege to the Dedicated User Account.
Note: Only Super Admins can change another admin’s settings. To allow your Google Workspace Integration access to suspend, sign out, or revoke tokens for other administrator accounts, the Dedicated User Account must be set to a Super Admin account.
Super Admin
To assign the Super Admin role to your Dedicated User Account, select the user from your Users list.
On the User Details page, navigate to the Admin roles and privileges section. Select this section to expand it.
From here, the Pre-Built Roles will populate. As this account is new, you will see that no roles have been assigned to it. Navigate to the Super Admin role and switch the Assigned State to Assigned. Once done, select the SAVE button.
Custom Role
To assign a Custom Role to your Dedicated User Account, select the user from your Users list.
On the User Details page, navigate to the Admin roles and privileges section. Select this section to expand it.
Now, from the Admin roles and privileges section, select the CREATE CUSTOM ROLE button found in the top right corner of the Roles list.
Selecting this button will take you to the Admin roles page. From here, select the Create new role button in the top right corner of the page.
You will now be brought to the Create role page. The first section, titled Role info, is used to name and describe the role. Here, enter your role’s name and optionally a description for it. Once done, select the CONTINUE button.
The Select Privileges section is where you will enter the privileges permitted for your custom role. When creating this role, please verify that it includes the necessary privileges for the functions you want your Google Workspace Integration to perform, while keeping in mind the level of information you want filtered through Cloud Detect for alert generation. ThreatLocker recommends implementing, at the very least, the following privilege areas:
- Reports
- Alert Center
- Full Access
- View Access
- View VirusTotal reports
- Full Access
- Users
- Update
- Move Users
- Rename Useres
- Suspend Users
- Update
- User Security Management
- Security Center
- This user has full administrative rights for Security Center
- Ensure all options beneath this option are selected.
- This user has full administrative rights for Security Center
Please note that other privileges can be selected; however, granting fewer permissions will limit the logs that Cloud Detect can collect.
Once you have selected all privileges you want for this role, select the CONTINUE button at the bottom of the page.
The final section lets you review all selected privileges before the role is created. Once you have verified that all information is correct, select the CREATE ROLE button at the bottom of the page.
Once finished, you will be brought to the Admins page for your customer role. Select Assign members at the top of the page.
From here, enter the name of your Dedicated User Account and select ASSIGN ROLE.
This will now assign your custom role to the Dedicated User Account.
Authorization of Domain-Wide Delegation
Still in the Google Admin Console, navigate to the left side of the page and select the Security dropdown. From here, choose Access and data control, then API controls.
Please Note: If the Security dropdown does not appear, select the Show More button at the bottom of this menu to view more options.
In the API controls page, navigate to the Domain wide delegation section and choose the MANAGE DOMAIN WIDE DELEGATION button.
Select the Add new button found at the top of the page. This will open the Add new client ID dialogue window.
In this new dialogue window, enter the following information:
- Client ID - The Client ID that was copied earlier for Domain-wide delegation.
- OAuth scopes - Copy and paste the following comma-delimited scope list as shown below:
Please Note: These scopes allow ThreatLocker to gather logs from Google. Failure to insert all of the above scope list or inputing it incorrectly will result in missing logs.
Once this information has been entered, select the Authorize button at the bottom of the dialogue window.
Once this Client ID has been authorized, you should see it populate in your list of API clients. Hover over the name of the client you just added and select View details.
This will open a sidebar with information about the newly created client. Confirm that all your information has been correctly added here, including the four OAuth scopes that were copied and pasted during your API client authorization.
Generating the JSON Key File
Once you have finished applying the API controls, switch back over to the Google Cloud Console and ensure that you are in the project you created earlier. From here, select the Navigation menu in the top left corner of the page.
From the Navigation menu sidebar, hover over the IAM & Admin option and select Service Accounts from the dropdown.
In the Service accounts page, select the Service Account you created for your ThreatLocker Integration to open the Service account details page. Then, using the top of the page, select the Keys tab. Once selected, choose the Add key dropdown button and select Create new key from the list of options.
A dialogue window will open that permits you to create a private key for your Service Account. Here, ensure that JSON is selected as the Key type before selecting the Create button.
Once Create is selected, the JSON file will be saved to your computer.
Important: Save this JSON file securely, as it can grant access to your Service Account. Do not email the JSON file or store it in a shared folder. This file should be treated the same as a password.
Setting up your Google Workspace Integration in ThreatLocker
From your ThreatLocker Portal, navigate to Manage on the left-hand side of the page and hover over it. Then, select Integrations from the menu.
From here, select the '+ Add Integration' button found in the top left corner of the Integrations page and search for Google Workspace.
When selecting the Google Workspace option from the dropdown, the integration sidebar will open. If this is your first time opening the Google Workspace integration, a notice will appear, requiring you to acknowledge that this integration requires a delegated administrator account that ThreatLocker can present as for the integration.
After acknowledging both this and the ThreatLocker data integrations notice, you can now view the Google Workspace Connector sidebar.
In the API Key Details section, in the field labeled "Enter your admin user account's email address", enter the email address of your newly created delegated administrator account.
Beneath this is a field labeled "Paste or drag/drop the JSON key file for your service account here". Here, take the JSON key file you created in the Google Cloud Console and insert it in the provided area.
If the provided JSON is inserted correctly, a new section titled Service Account Details will populate beneath it. This section includes the information that can be gathered from the inserted JSON key file.
Once you have confirmed that your entered information is correct, select the Create button at the bottom of the Create Google Workspace Connector sidebar.
The Google Workspace integration will now appear as a Configured Integration in your organization. To update your JSON key file or the associated admin account email address, select the configured integration and make changes directly in the fields. Select the Save button when you're done.