Google Workspace
Google Workspace is Google's suite of cloud productivity and collaboration tools. Owlie syncs directory users, groups, group memberships, admin roles, organizational units and domains. It can provision user accounts and manage group membership and customer or organizational-unit admin role assignments through the Admin SDK Directory API.
Capabilities
| Capability | Supported | Details |
|---|---|---|
| Sync | Yes | Users, groups and memberships, admin roles and assignments, organizational units and domains. |
| Incremental sync | No | Each run reads the directory from the beginning. |
| Account provisioning | Yes | Create, update, disable, enable and revoke users. Revoke deletes the Google Workspace user. |
| Grant writes | Yes | Group membership, customer admin-role assignment and organizational-unit admin-role assignment. |
| Notifications | No | |
| Custom operations | Yes | Move a user to an organizational unit and sign a user out of active sessions. |
Authentication
Choose one of two methods. OAuth 2.0 connects an administrator through Owlie's managed Google OAuth app. Service Account Credentials uses a Google Cloud service account with domain-wide delegation; you provide its private key and the Workspace admin account to impersonate.
Get credentials from Google Workspace
For OAuth, choose Google Workspace in Owlie and grant the requested Google Workspace permissions. No customer OAuth client credentials are needed. The flow uses Google's OAuth authorization-code flow with PKCE.
For service-account authentication:
- In Google Cloud, create a project, enable the Admin SDK API, and create a service account with a key. Follow Google's service account credential guide.
- In the Google Admin console, authorize the service account's client ID for domain-wide delegation and the OAuth scopes required by the features you plan to use. Follow Google's domain-wide delegation guide.
- In Owlie, enter the service account email, the email address of a Workspace administrator to impersonate, and the private key.
The OAuth option requests these scopes:
| Feature | OAuth scopes |
|---|---|
| User, group, org-unit and domain sync; user provisioning and lifecycle | https://www.googleapis.com/auth/admin.directory.user, https://www.googleapis.com/auth/admin.directory.group, https://www.googleapis.com/auth/admin.directory.domain.readonly, https://www.googleapis.com/auth/admin.directory.orgunit.readonly |
| Group membership sync and writes | https://www.googleapis.com/auth/admin.directory.group |
| Admin role and assignment sync and writes | https://www.googleapis.com/auth/admin.directory.rolemanagement |
| Sign out a user | https://www.googleapis.com/auth/admin.directory.user.security |
The service-account Scopes field can be shortened for the features you use. Directory sync and user provisioning use the user, group, domain-read and org-unit-read scopes above. Group membership reads and writes use the group scope. Admin role assignments use https://www.googleapis.com/auth/admin.directory.rolemanagement; Google recommends the read-only role-management scope when only reading roles and assignments. The default scope list requests only scopes used by connector features. See Google's Admin SDK API scopes for scope details.
Connect Google Workspace in Owlie
The shared connection configuration has no fields. Select an authentication method and enter its required credentials.
| Field | Required | What to enter |
|---|---|---|
| Service Account Email | For service-account authentication | The service account address, such as svc-account@project.iam.gserviceaccount.com. |
| Impersonated Admin Email | For service-account authentication | A Workspace administrator's email address. |
| Private Key | For service-account authentication | The service account's PEM private key. Owlie stores it as a secret. |
| Scopes | For service-account authentication | Google OAuth scopes. The default enables the connector's current sync, provisioning, Grant-write and sign-out features; you can reduce it when using fewer features. |
The OAuth option uses Owlie-managed client credentials and has no customer-entered fields. Test connection lists one user from the Workspace directory.
Entities
| Entity | In Google Workspace | Identifier | Key attributes | Sync | Create | Update | Delete | Grants (as target) |
|---|---|---|---|---|---|---|---|---|
| User | A Workspace directory user and the account entity. | id, primaryEmail | primaryEmail, name, suspended, orgUnitPath, organizations | Yes | Yes | Yes | Yes | No |
| Group | A Workspace email group. | id, email | email, name, description, directMembersCount | Yes | No | No | No | member_of |
| Admin Role | A Workspace admin role. | roleId | roleName, roleDescription, isSystemRole, isSuperAdminRole | Yes | No | No | No | assigned_role |
| Org Unit | A Workspace organizational unit. | orgUnitId, orgUnitPath | name, orgUnitPath, parentOrgUnitId | Yes | No | No | No | org_unit_admin_role |
| Domain | A Workspace domain or alias. | domainName | domainName, isPrimary, verified | Yes | No | No | No | No |
Grant kinds
| Grant kind | In Google Workspace | Principal → target | Writable | Qualifiers | Passes access through |
|---|---|---|---|---|---|
member_of | A user or group belongs to a Google Group. See group membership. | User or group → Group | Yes | role: MEMBER, MANAGER or OWNER. A group principal can only use MEMBER. | Yes, group membership can be transitive. |
assigned_role | An admin role assigned across the customer account. See role assignments. | User or group → Admin Role | Yes | None | Yes, through the assigned role. |
conditional_assigned_role | A conditional customer admin-role assignment. | User or group → Admin Role | No | condition: provider condition string. | No, access is conditional and unresolved. |
org_unit_admin_role | An admin role assigned within an organizational unit. See role assignments. | User or group → Org Unit | Yes | role: required Admin Role reference. | Yes, the role applies within that organizational unit and descendants. |
conditional_org_unit_admin_role | A conditional admin-role assignment within an organizational unit. | User or group → Org Unit | No | role: Admin Role reference; condition: provider condition string. | No, access is conditional and unresolved. |
in_org_unit | A user's current organizational-unit placement, read from the user resource. | User → Org Unit | No | None | No |
org_unit_parent | An organizational unit's parent, read from the org unit resource. | Org Unit → Org Unit | No | None | No |
Google requires a user or group to exist before a Grant can refer to it. A user can have one current organizational-unit placement, and an org unit can have one parent. Conditional admin-role assignments are read-only because Google exposes them through a beta API with edition and role restrictions.
Provisioning behaviour and limits
| Operation | What happens in Google Workspace |
|---|---|
| Provision | Creates a user whose primary email is generated from the identity's email (the email first, then a numbered variant such as jsmith2@example.com when it is taken), a random 24-character password Owlie keeps no copy of, and root org-unit path (/), plus the identity's name. Make sure the identity email uses a domain managed by this Workspace. |
| Password change | Sets the user's new password and turns off changePasswordAtNextLogin, when the resource is linked to the person's password. Needs the admin.directory.user scope and an administrator allowed to reset that user's password. Google can refuse a password that breaks the domain's rules or a change your administrator may not make; Owlie shows a fixed reason for each. |
| Update attributes | Updates the user's profile fields. |
| Disable / Enable | Sets or clears the user's suspended state. |
| Revoke | Removes managed Grants and deletes the user. |
Add / remove member_of | Adds or removes the selected user or group and native membership role. |
Add / remove assigned_role | Adds or removes an unconditional customer-wide admin role assignment. |
Add / remove org_unit_admin_role | Adds or removes an admin role assignment scoped to one organizational unit. |
User organizational-unit placement and organizational-unit parentage sync as Grants but are read-only. Moving a user remains available through the move-org-unit custom operation. The signOut custom operation signs the user out of active sessions.
Google's users.signOut method requires the admin.directory.user.security scope. The OAuth option requests it; existing OAuth installations must reconnect and grant it. For an existing service-account connection, authorize it for domain-wide delegation and add it to the saved scope list before using signOut.
The connector reads Directory API rate-limit responses for userRateLimitExceeded and quotaExceeded as quota feedback. Role-assignment sync fails if a response contains an expiring assignment, because Owlie cannot represent its expiration. Conditional role assignments are modeled and synced as read-only Grants. License assignments and Drive item permissions are not modeled. Google exposes super-admin status as the user's isAdmin field, but Owlie does not manage it as a Grant.
Troubleshooting
The connection test fails with Connection Failed: .... Check that the selected credentials are valid, the delegated admin can access the Directory API, and the configured service-account scopes or OAuth authorization cover directory users.
A membership write says Google membership already exists with a different native role. The person or group is already a member with another Google Group role. Sync the existing membership and request the role that is currently assigned, or change it directly in Google Workspace before retrying.
Changelog
Google Workspace is at version 1. Owlie displays the connector's changelog in the integration catalog.