๐Ÿ“„
Assessments
Resources
Google Workspace
(formerly G Suite)

Connecting to Google Workspace

We recommend that you connect Google Workspace to Trelica using a Super Admin role. This article explains why, and what the compromises are if you use a user with normal Google Workspace admin role.
Trelica connects to Google Workspace using OAuth2. This is a common protocol which controls Authorization (controlling what Trelica is allowed to do with the Google Workspace APIs).
OAuth2 uses something called "Scopes" which lets Trelica ask for specific access rights.
When you connect Trelica and Google Workspace, you get asked by Google Workspace for permission to grant these scopes to Trelica.
Aligned with the principle of least privilege, Trelica requests the most limited set of scopes it can, for the functionality it needs. So, for users, Trelica asks for read-only access, as that's all Trelica needs for basic operations.
We encourage you to use a dedicated user account for integrating Google Workspace with Trelica, and assigning the user account the Super Admin role.

Creating a custom Google role

IT teams sometimes want to limit the usage of Super Admin roles. The alternative approach is to create a custom Google Workspace role.
If you do this then you will need to assign the following privileges
Admin Console:
  • Reports
Admin API:
  • Organization Units > Read
  • Users > Read
  • Groups > Read
  • User Security Management
  • Schema Management > Schema Read
  • License Management > License Read
  • Domain Management
Note that when you select Admin API privileges, Google Workspace automatically assigns corresponding Admin Console privileges.
For Provisioning and Deprovisioning you must enable the following:
  • Users (all)
  • Groups > Create
  • Groups > Update
  • Data Transfer

Limitations of connecting with a non super-admin role

There are a number of limitations imposed by Google if you use a non super-admin role.
These are:
  • Trelica cannot see apps that other Administrator users have connected to with OAuth2 (i.e. 'Sign in with Google').
  • No Google Workspace license data will be available in Trelica.
These limitations are both due to the way Google's API works.

Explanation for lack of OAuth data for other administrators

In Google Workspace, OAuth2 scopes generally exist in pairs - one for read access, and one for read/write access, e.g.
OAuth2 Scope
Description
auth/admin.directory.user
Read/write operations on users
auth/admin.directory.user.readonly
Read only operations on users
One of these scopes is called auth/admin.directory.user.security.
This scope is used so that Trelica can get list of OAuth2 tokens for users, which lets Trelica see where users have used OpenID Connect (commonly known as "Sign in with Google", or "social logins") to connect to other applications and websites.
Unfortunately, this particular scope does not exist with a "read-only" version. It allows "access to all application-specific password, OAuth token, and verification code operations" (https://developers.google.com/admin-sdk/directory/v1/guides/authorizing).
For security reasons, Google enforces a rule that users with this scope cannot use it in relation to user accounts of other users with Administrative privileges, even if the actual API call is read-only.
The exception to this rule is if the user account that connects to Trelica is part of the super admin role.

Explanation for license data limitation

License data can only be retrieved if you connect as a Google Workspace super admin user: the License Management > License Read role privilege that you can grant only works in the Admin console and not via API access, unless you are a super admin.
Please see https://support.google.com/a/answer/1219251?hl=en&ref_topic=9832445 under "Admin privileges definitions / Admin API":
"License managementโ€”Super admins can assign and manage G Suite licenses for the organization, an organizational unit, a group of users, or an individual user. Note: This privilege works only in the Admin console and authorizes only super admins to use the License Manager API."

FAQs

I get an "Error 400: admin_policy_enforced error" when connecting

This means that your Google Workspace administrator has blocked OAuth apps requesting consent. A Google Workspace super admin can either connect to Trelica or they must alter app access settings to allow Trelica to connect.
To do this go to Security > Access and data control > API controls in the Google Workspace Admin console.
  • Ensure that Block all third-party API access is unchecked.
  • Click Manage third-party app access.
  • Under Configured apps, add a filter for ID 702299011990-8mjrfmoi101u51l4cnv4vgm145c8iukv.apps.googleusercontent.com
  • Make sure Access is set to Trusted
It can take several minutes for changes to come into effect.

How is the person type determined?

The person type is determined by the following logic:
  1. 1.
    If the Google "Type of employee" field is set then it is mapped as follows:
    • Employee, Full-time, or Fulltime => Employee
    • Contractor => Contractor
    • Consultant, Vendor or External => External
    • ServiceAccount, Service Account => Service Account
    โ€‹
    โ€‹
  2. 2.
    If the Employee Type is not set, then if any of the following fields have a value, the person is marked as an Employee:
    • Employee ID
    • Manager's email
    • Cost center
    • Department

Which employee attributes does Trelica store?

By default Trelica pulls the following employee information from Google Workspace:
  • Employee ID
  • Job title
  • Type of employee
  • Manager's email
  • Department
  • Cost center
  • Building ID
Trelica also extracts the Google groups that each user is a member of.

How do I take data from custom Google schemas, or remap data?

If you need support for mapping custom schema items, or other changes, please contact [email protected].
Last modified 1mo ago
Copy link
Outline
Connecting to Google Workspace
Creating a custom Google role
Limitations of connecting with a non super-admin role
Explanation for lack of OAuth data for other administrators
Explanation for license data limitation
FAQs