> 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/settings/idp-group-sync.md).

# IDP Group Sync

Harmony can sync user group memberships directly from your identity provider (IDP), giving you accurate, up-to-date group data across the platform without manual maintenance. Once connected, Harmony queries your organization's group directory and refreshes it every 4 hours, so features like Service Desk, Application Management, and App Access always work from current membership information.

Supported identity providers:

* Okta
* Google Workspace
* Microsoft Entra

***

### How IDP Group Sync Works

When IDP Group Sync is enabled, Harmony periodically pulls your organization's group directory from the connected identity provider. Each sync run captures group memberships and enriches them with metadata that powers context-aware automation across the platform.

#### Sync frequency

Harmony syncs group data every 4 hours. There is no manual trigger required - the process runs automatically in the background after your IDP is connected.

#### What gets synced

For each group, Harmony captures the following metadata:

| Field            | Description                                                                       |
| ---------------- | --------------------------------------------------------------------------------- |
| **Group source** | Which IDP the group was learned from (Okta, Google Workspace, or Microsoft Entra) |
| **Group ID**     | A stable, unique identifier for the group within the IDP                          |
| **Group name**   | The human-readable label as it appears in your IDP                                |
| **Display name** | The name shown within Harmony when referencing the group                          |

This metadata is used to ensure accurate group resolution when applying policies, routing tickets, managing app access, and evaluating application assignments.

***

### Where Synced Groups Are Used

Once groups are synced, they become available across several Harmony features:

* **Service Desk** - Route tickets and apply policies based on a user's IDP group membership.
* **Application Management** - Scope application configurations and assignments to specific groups.
* **App Access** - Control which users can access which applications by referencing IDP groups directly.

Because the data refreshes every 4 hours, changes made in your IDP - such as adding a user to a group or removing one - are reflected in Harmony without any manual intervention.

***

### Connecting Your Identity Provider

IDP Group Sync relies on your identity provider being connected to Harmony. If you have not yet integrated your IDP, complete the integration for your provider before expecting group data to appear.

* **Okta** - Connect Harmony to Okta through the Okta integration settings in your Harmony workspace.
* **Google Workspace** - Connect Harmony to Google Workspace through the Google integration settings.
* **Microsoft Entra** - Connect Harmony to Microsoft Entra through the Entra integration settings.

Once the integration is active, the first group sync runs automatically. Subsequent syncs occur on the 4-hour schedule.

***

### Troubleshooting

**Groups are not appearing after connecting my IDP.** The initial sync may take a few minutes to complete after the IDP connection is established. If groups still do not appear after 10 minutes, verify that the connected IDP account has sufficient permissions to read group directory information.

**Group membership changes in my IDP are not reflected in Harmony.** Harmony syncs every 4 hours. If a change was made recently, wait for the next scheduled sync. If the issue persists beyond one sync cycle, check that the IDP integration credentials are still valid and have not expired.

**A group exists in my IDP but is missing from Harmony.** Confirm that the group is visible to the account or service principal used for the IDP integration. Some groups may be excluded if the integration account does not have read access to them.


---

# 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/settings/idp-group-sync.md?ask=<question>&goal=<endgoal>
```

`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.