Comment on page

Google Workspace Audit Logs

Connecting GSuite requires a GSuite administrator who can add a GSuite app to your workspaces. The integration is seamless and uses Google OAuth2 to provide us with a token.
You will also need to have the runreveal CLI installed and a RunReveal account created before we can start receiving data from Google Workspace using this guide.

Setup OAuth App in Google Workspace

  1. 1.
    Create a project in Google Cloud Console.
  2. 2.
    Select that project by selecting it from the drop-down menu at the top left of the console.
  3. 3.
    Enable the Google Cloud Admin SDK in Google Cloud Console by following this link and clicking "Enable".
  4. 4.
    Before we can create the OAuth App, we need to configure the project to have an OAuth Consent Screen. Open that link then follow along.
  5. 5.
    Select "Internal" as the User Type then hit "Create".
  6. 6.
    "App name" is for you, but we recommend RunReveal so that it can be easily identified.
  7. 7.
    "Support Email" should be someone in your org who can answer questions about access controls, typically the IT administrators or security team.
  8. 8.
    Under Authorized Domains, click [+ADD DOMAIN] and enter
  9. 9.
    For Developer contact information, enter your email or an appropriate IT admin in your org.
  10. 10.
    The remaining fields are optional. Click "Save and Continue" when you're finished.
  11. 11.
    Click "Add or Remove Scopes".
  12. 12.
    Type "audit" into the filter bar at the top of the table and select the checkbox next to the scope ending in admin.reports.audit.readonly then click "Update" at the bottom.
    Check the box adjacent to the admin.reports.audit.readonly scope.
  13. 13.
    If you don't see the scope (admin.reports.audit.readonly) return to step 3.
  14. 14.
    Click "Save and Continue".
  15. 15.
    Now click "Credentials" in the left navigation column (or click the link provided).
  16. 16.
    Click [+Create Credentials] -> and select OAuth Client ID from the list.
  17. 17.
    Select Web Application for the "Application Type".
  18. 18.
    Name the app something recognizable, like RunReveal.
  19. 19.
    For the Authorized Redirect URIs, open the command line on the computer you have the runreveal CLI installed and run: sources gsuite add -n 'GoogleWorkspaceLogs'
  20. 20.
    That command will output the URI you will need to input in the form under where it reads "Authorized redirect URIs". The CLI will then ask for the Client ID and Secret which we'll be getting in the next steps.
  21. 21.
    Click "Create"
  22. 22.
    Copy the OAuth "Client ID" into the runreveal CLI (it would be waiting for input).
  23. 23.
    Do the same now for "Client Secret". Hit enter.
  24. 24.
    Your browser will now open the consent screen to grant access to runreveal. View that page from a Google Workspace Administrators account for your organization.
  25. 25.
    Select the account to authenticate to RunReveal with.
  26. 26.
    On the next screen, click "Allow". It takes a few moments, but when complete it should redirect you to our documentation.
You're done! Logs should now be flowing into your Google Workspace source in RunReveal.

Query your logs

Logs should become available almost immediately after something happens within your Google Workspace, regardless of size. You can query your logs by specifying a sourceType of gsuite when querying runreveal_logs or query the gsuite_audit_logs table.
$ runreveal logs
rr> SELECT * FROM runreveal_logs WHERE sourceType = 'gsuite' LIMIT 1;