> For the complete documentation index, see [llms.txt](https://docs.harmony.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.harmony.io/integrations/identity-provider/google-workspace.md).
# Google Workspace
Google Workspace (formerly G Suite) is a collection of cloud computing, productivity, and collaboration tools developed by Google. Connecting Google Workspace to Harmony enables automated user provisioning, intelligent license optimization, and seamless access management across your Google ecosystem.
The integration uses secure OAuth-based authentication to establish and maintain the connection between your Google Workspace account and Harmony. Once connected, Harmony automatically saves your credentials and keeps your data in sync - no manual steps required.
#### What the Google Workspace integration enables
| Capability | Description |
| --------------------- | --------------------------------------------------------------------------- |
| User Provisioning | Automate user lifecycle management across Google services |
| License Management | Track and optimize Google Workspace licenses to reduce costs |
| Group Management | Sync organizational units and groups for access control |
| Application Discovery | Identify all Google Workspace apps, SAML apps, and OAuth integrations |
| Automation Workflows | Build custom workflows using the Google Workspace Admin API |
| Multi-Tenant Support | Connect up to two Google Workspace tenants and automate across both of them |
***
#### Prerequisites
Before connecting Google Workspace to Harmony, ensure you have:
1. **Google Workspace Super Admin access**
2. **A Harmony account** with admin privileges
{% hint style="info" %}
Super Admin privileges are required to authorize the Harmony integration.
{% endhint %}
***
#### Connect Google Workspace
1. **Navigate to Integrations**
1. Log into your Harmony dashboard
2. Navigate to **Settings → Integrations**
3. Find **Google Workspace** under **Identity Provider**
4. Click **Connect**
2. **Authorize Google Workspace**
1. You'll be redirected to Google to authorize the connection
2. Sign in with your **Google Workspace Super Admin account**
3. Review the requested permissions
4. Click **Allow** to authorize
5. You'll be redirected back to Harmony
Once you complete the OAuth authorization flow, Harmony automatically receives and stores your integration credentials - no additional configuration is needed to activate the connection.
3. **Verify Connection**
Confirm that Google Workspace shows **Connected** status in your Harmony integrations page.
***
#### Connect Multiple Google Workspace Tenants
If your organization operates more than one Google Workspace environment, you can connect multiple tenants to Harmony and manage them all from a single place. This removes the previous limitation of one connection per provider and enables cross-tenant automation for workflows like offboarding.
{% hint style="warning" %}
Harmony supports up to **two** Google Workspace connections per organization.
{% endhint %}
**To add an additional tenant:**
1. Navigate to **Settings → Integrations**
2. Find **Google Workspace** and click **Add Another**
3. Complete the OAuth authorization flow using the Super Admin account for the additional tenant
4. Give the connection a custom display label (for example, "Google Workspace - Primary" or "Google Workspace - Legacy") so each tenant is easy to identify
Each tenant connection has its own credentials and label, and you can build automation workflows that span all connected tenants.
{% hint style="info" %}
You can disconnect any individual tenant at any time without affecting your other Google Workspace connections. When credentials are revoked or removed, Harmony automatically detects this and cleans up the stored credentials.
{% endhint %}
***
#### Approve Harmony in App Access Control
If your Google Workspace organization restricts third-party app access, you need to explicitly approve Harmony before users can sign in with Google.
1. **Navigate to App Access Control**
In your Google Admin Console, go to **Security → API Controls → App Access Control**.
2. **Configure a new app**
Click **Configure new app** (labeled **1** in the screenshot below).
3. **Search for Harmony by App ID**
In the **Configure new app** dialog, search for Harmony using its Application ID:
```
128010343499-ima1svvf9amk9677o78nuevsv1v799ab
```
4. **Select Harmony from the results and complete the configuration**
Follow the remaining steps (Scope → Access to Google Data → Review) and set access to **Trusted** for the relevant organizational units.
{% hint style="info" %}
You only need to complete this step if your organization has restricted third-party app access. If Harmony is already listed under **Configured apps**, no action is required.
{% endhint %}
***
#### What Harmony Syncs from Google Workspace
Once connected, Harmony automatically syncs:
**Users**
* User profiles (name, email, photo)
* User status (active, suspended, archived)
* Organizational units and departments
* Manager relationships
* Last login and creation dates
* License assignments
* 2-Step Verification status
**Groups**
* Group names and descriptions
* Group members and managers - including users who belong to the group through nested or indirect group relationships (transitive memberships are resolved automatically)
* Group settings and permissions
* Distribution lists
{% hint style="info" %}
Nested group membership is fully resolved, meaning users who are members of a group through another group are included. This ensures routing rules, assignment policies, and any features that rely on group membership correctly account for all members regardless of nesting depth.
{% endhint %}
{% hint style="success" %}
Harmony syncs data every 24 hours by default.
{% endhint %}
***
#### Application Discovery
Harmony automatically discovers applications connected to your Google Workspace environment, giving you a complete picture of your SaaS and application landscape without any manual inventory work.
**OAuth and SSO Apps**
Third-party and internal applications authorized via OAuth in your organization are automatically collected and appear alongside your other discovered software in Harmony's Software Discovery.
**SAML Apps**
Google Workspace SAML-based applications are now discovered automatically alongside OAuth apps. Harmony ingests SAML login activity from the Google Admin Reports API to surface these applications and their users.
* SAML-connected apps appear as application instances in the **Instances & Manage** tab
* Each instance shows the users who have authenticated via SAML SSO
Previously, Harmony could only discover apps granted via OAuth tokens. SAML apps had no discovery path and created a blind spot in your application inventory - this is now resolved automatically.
***
#### Group Membership Management
When using the **Group Membership Management** request type, you can search for Google Workspace groups by either display name or email address.
* Searching by a full email address (for example, `engineering@company.com`) will correctly match and return the corresponding group
* The `@` and `.` characters in email addresses are handled correctly throughout the search
* Previously, groups could only be found by display name, which made it difficult to locate the right group when only the group's email address was known
***
#### Reliability Improvements
Harmony includes several improvements to keep your Google Workspace data accurate and up to date:
* **Automatic retries for Google API errors** - When Google returns temporary service unavailability errors, Harmony automatically retries the request, reducing the chance of missing data due to transient outages on Google's side.
* **More reliable out-of-office sync** - The Google Calendar out-of-office sync process handles employee data more efficiently in the background, reducing the risk of memory-related failures or interruptions during scheduled syncs. Out-of-office statuses are less likely to be delayed or missing, particularly for organizations with large numbers of employees.
***
#### Troubleshooting
Connection fails during authorization
**Solutions:**
1. Ensure you're signing in with a Super Admin account
2. Verify your organization allows third-party app access in Admin Console
3. Try clearing browser cache and cookies, then retry the authorization
4. Check if your organization has conditional access policies that might block the connection
User sync incomplete
**Solutions:**
1. For large directories (10,000+ users), allow extra sync time
2. Review sync logs in Harmony for specific errors
3. Contact Harmony support if specific users are consistently missing
Cannot provision new users
**Solutions:**
1. Verify you have available licenses to assign
2. Check that domain is verified in Google Workspace
3. Confirm user email format matches verified domains
4. Ensure API access is enabled in Google Workspace Admin Console
***
#### Best Practices
Leverage Organizational Units
Use organizational units for structured management:
* Mirror your company's org structure
* Apply policies at the OU level
* Automate user placement based on department
* Simplifies bulk operations and policy enforcement
Enable 2-Step Verification
Enforce baseline security in Google Workspace:
* Require 2-Step Verification for all users
* Use security keys for admin accounts
* Enable advanced protection for high-risk users
* Monitor sign-in attempts and alerts
Regular Access Reviews
Periodically review access and permissions:
* Audit user group memberships quarterly
* Review license assignments for optimization
* Remove inactive or unnecessary user accounts
* Validate shared drive access and permissions
***
Need help? Contact [**support@harmony.io**](mailto:support@harmony.io) for assistance with your Google Workspace integration.
***
#### Data & Privacy
Key privacy principles
For information about how Harmony handles your data, see our [Privacy Policy](https://harmony.io/privacy).
* Google Workspace credentials are encrypted at rest and in transit
* Only directory data necessary for IT operations is accessed
* No personal emails or private documents are read
* User activity data used only for license optimization
* Integration can be revoked at any time from Google Admin Console or Harmony
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://docs.harmony.io/integrations/identity-provider/google-workspace.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.