Onboarding
      Back to home
      1. Knowledge Base
      2. Onboarding

      Connecting Google Workspaces and/or G-Suite to ContraForce

      Data from Google Workspaces and G-Suite can be ingested to produce valuable security insights. This article will cover the set up items needed to connect to ContraForce.

      Overview

      The core component of connecting Google Workspaces or G-Suite to ContraForce is a Service Account and a GooglePickleString. In addition to these, there are also settings and configurations that are required within Google Workspaces. This article will help guide ContraForce users through the steps to take within their environment to ensure a functioning connection. Where possible, we reference Google documentation as their documentation is very helpful. 

      Onboarding Google Workspaces/G-Suite requires the Workspace to have the following items properly configured:

      • Enablement of the GCP Admin SDK API

      • An active OAuth consent screen

      • An OAuth 2.0 Client

      • A credentialed service account

      • Domain-wide delegation of authority for the service account

      • The GooglePickleString of the service account

      Several of the items above are configured through a Google Cloud project, which is required to use Google Workspace APIs. For instructions on creating a Google Cloud project from the Workspace Admin console see this article. 

      Enabling the GCP Admin SDK API

      To connect Google workspace data to ContraForce, the GCP Admin SDK API needs to be enabled. Below are steps on how to do this.

      To enable an API in your Google Cloud project:

      1. Open the Google Cloud Console.
      2. Click Me > APIs & Services > Library.
      3. Search the name of the API to be enabled, in this case GCP Admin SDK API. Click the title of the API. 
      4. Click Enable and then save.

      Creating an OAuth Consent Screen

      The next step is to have an active OAuth Consent Screen.

      1. Click the Menu icon then APIs & Services. Within the side menu, you will see an option for OAuth consent screen.
      2. Fill out the required fields granting the scopes below where requested. Google documentation on how to do this can be found here.
        1. https://www.googleapis.com/auth/admin.reports.audit.readonly
        2. https://www.googleapis.com/auth/admin.reports.usage.readonly
      3. Lastly, enter your email address to complete this step. 

      Creating an OAuth 2.0 Client

      After an OAuth consent screen has been created for your project, an OAuth 2.0 client can be created for identifying the application to Google's OAuth servers. You can find further documentation around this process from Google here.

      1. The Client creation page can be reached by clicking the Menu icon then APIs & Services followed by Credentials. 

      2. Click the 'CREATE CREDENTIALS' button at the top of the page and select 'OAuth client ID' from the dropdown.

      3. Select 'Web application' for Application type, give the client a name (this is only used in the context of the Google Cloud Console).

      4. Under Authorized JavaScript origins, enter 'http://localhost' and for Authorized redirect URIs enter 'http://localhost:8081/'. Click Save.
      5. A popup should appear revealing successful creation of the OAuth application

      Creating a Service Account and Service Account Credentials

      Google documentation around creating a service account can be found here. After creating the service account we will also create credentials. Credentials are in the form of a public/private key pair. Google documentation around creating credentials can be found here.

      1. Service Accounts can be created from the Service Account page. From the Google Cloud Console, click the Menu icon, then IAM & Admin, followed by Service Accounts. 
      2. Click Create Service Account. Fill out the details of the service account. 
      3. Once finished, click Create and Continue, Continue, then Done. 
      4. Click on the hyperlink email address of the Service Account that was just created. 
      5. Click on the KEYS title near the top of the page, followed by the ADD KEY button. Select "Create new key".
      6. Select JSON and click create. Your browser should download the Service account credentials. Rename this file 'credentials.json' as we will need them again in a next step. 

      Domain-wide delegation of authority for the Service Account

      Domain-wide delegation of authority for the service account is required to allow the integration to access your organization's data.

      1. Click the arrow next to 'Advanced settings' to display a section that says 'Domain-wide Delegation'. Copy the Client ID to your clipboard and click the 'View Google Workspace Admin Console' to get back to the Google Workspace Admin Console.
      2. From the Google Workspace Admin console, navigate to the API Controls page from the Menu icon, Security, Access and data control, API controls.
      3. Click Manage Domain Wide Delegation. Click Add new.
      4. Paste the Client ID copied in step 2. In OAuth Scopes, enter the link below.
        1. https://www.googleapis.com/auth/admin.reports.audit.readonly,https://www.googleapis.com/auth/admin.reports.usage.readonly
      5. Click Authorize

      Obtaining the GooglePickleString

      The last step in the connection process is to generate the GooglePickleString. The GooglePickleString can be obtained by locally running a Python script in the same directory as the credentials.json file downloaded by your browser within step 6. of the Creating a Service Account and Service Account Credentials section.

      ContraForce will send you the python scripts to be ran as a txt file. 

      Make sure python is installed prior to proceeding. To verify this, open up a command prompt and enter 'python --version'. If it returns a value, it has been installed. If not, it will need to be installed from the above link.

      The script 'get-pip.txt' will need to be ran first. In order for you to execute this script, open up the text file in an editor, hit Save As, and make sure the type is set to All Files and the file name has '.py' appended to update it to a python script. This will need to be done for both scripts. Once this is done, you will be able to install the necessary python packages needed. Open up a command prompt and enter 'pip install google-auth-oauthlib'. Once this is done, you may proceed to the next section.

      Running the script 'get_google_pickle_string.py' will prompt you to paste a URL into a browser window in order to grant the app access from the OAuth consent screen. The process may fail with a message about the ephemeral port not being in the approved Client Redirect URI list for the OAuth Client.

      If that is the case, without stopping the Python script, temporarily add the unauthorized port to the OAuth Authorized Redirect URI list from the Google Cloud Console APIs & Services, Credentials page. If the unauthorized port had been port 50000, the new entry should look like http://localhost/50000/

      After adding the port to the OAuth Client, paste the URL output by the Python script into a browser window again. Upon completion of the authentication flow, the terminal from which the Python script was run should output the GooglePickleString in single quotes.

      Be sure to send the GooglePickleString to ContraForce. We will need this to finalize the connection.