# Group Membership Management

**Categories:** Identity

Governs how users are added to or removed from identity provider groups, replacing ad-hoc requests with a controlled, auditable workflow

- Triggered when a user requests a group membership change
- Validates the request against current group membership and access policies
- Routes the request through the appropriate approval flow
- Applies the membership change automatically once approved
- Notifies the requester through their preferred communication channel
- Updates the ticket with the full outcome for audit and traceability

## What Group Membership Management does

Group Membership Management is Harmony's automated workflow for adding or removing employees from identity provider groups - including security groups, email distribution lists, and mailing lists. An employee or IT agent asks the helpdesk chatbot, and Harmony searches across all connected IdPs, routes the request for approval, and executes the membership change directly in the identity provider. What previously required an IT ticket, manual lookup, and admin access is handled end-to-end in a single conversation.

## Who Group Membership Management Is For

**Persona:** Employees who need to join or leave a group themselves, and IT admins or managers who manage group membership for others.

**Pain point:** Group membership changes typically require an IT agent to find the right group in the right IdP, verify approval, and manually make the change. Harmony automates the search, approval routing, and execution - removing the need for IT to act as an intermediary for routine membership changes.

## How Group Membership Management Works

**Trigger:** An employee or IT agent asks the helpdesk chatbot to add or remove someone from a group (or DL / mailing list). Alternatively, a ticket tagged as a group membership request is created.

1. **Group search** - The agent searches across all connected IdPs (Okta, Microsoft Entra, Google Workspace) using two parallel queries - the full phrase and a simplified version - and presents matching groups for the user to confirm.

2. **Employee resolution** - For self-service requests, the employee's identity is already known. For requests on behalf of others, the agent resolves each employee by name or email and confirms before proceeding.

3. **Approval routing** - An approval request is sent to the group owner(s) or manager(s) (configurable per provider). If no response arrives within the timeout (default: 48 hours), the ticket is escalated to a human.

**Outcome:** On approval, Harmony adds or removes the employee(s) from the group directly in the IdP and resolves the ticket. If the group is read-only or the provider is disabled, the ticket is escalated for manual handling.

## Capabilities

- **Search groups across multiple IdPs in parallel** - Searches Okta, Microsoft Entra, and Google Workspace simultaneously using a two-call strategy (full name + simplified name) to handle typos and ambiguous queries.
- **Add or remove up to 10 employees in one operation** - Supports bulk membership changes for a single group in a single request.
- **Route approval to the right owner** - Sends approval to group owners (Okta, Entra) or group owners and managers (Google Workspace); configurable per provider.
- **Enforce business justification when required** - Per-provider and per-group configuration controls whether a justification must be collected before the request is submitted.
- **Validate group writability before approval** - Checks whether the group can be modified programmatically before routing for approval, so read-only groups are escalated immediately rather than after wasting approver time.
- **Handle distribution lists and mailing lists** - Supports mail-enabled groups in Microsoft Entra and Google Groups/mailing lists in Google Workspace (legacy Exchange DLs are explicitly out of scope).
- **Escalate gracefully** - If the IdP provider is disabled, the group is non-writable, approval times out, or an error occurs, the ticket is reassigned to a human with a clear explanation.

## Main use cases

**Employee Joining a Team Group** - A new team member asks the helpdesk to be added to the Engineering security group in Okta. The agent searches for the group, confirms the match with the employee, routes the approval to the group owner, and adds the employee to the group once approved - all without IT needing to touch it.

**Manager Adding Multiple Reports to a Distribution List** - A manager needs three new hires added to the Sales mailing list in Google Workspace. The agent resolves all three employees, confirms the group and the list of names, routes approval to the group owner or manager, and executes all three additions in a single operation.

**Employee Leaving a Project Group** - An employee finishing a project rotation asks to be removed from the "Project Apollo" group in Microsoft Entra. The agent finds the group, confirms the action, routes it for approval, and removes the employee from the group on approval.

**IT Admin Managing a Group on Behalf of a Colleague** - An IT agent is asked to remove a departing employee from several groups - but per the one-operation-per-conversation rule, they handle them one at a time. The agent resolves the departing employee, confirms the group, routes approval, and executes the removal. The IT admin initiates the next group in a new conversation.

## Integrations

| Integration | Role in the agent flow |
| --- | --- |
| Okta | Group search, writability validation, and membership management (add/remove) - configured per tenant |
| Microsoft Entra | Group and mail-enabled distribution list search and membership management |
| Google Workspace | Group and Google Groups/mailing list search and membership management |
| Harmony Service Desk | Ticket creation, approval routing, status updates, and escalation |

## FAQ

### What exactly is this - is it a bot, a workflow, or something else?

It's a toolkit (`group_membership`) inside Harmony's single AI Helpdesk agent, using two tools - one to search for groups across connected IdPs, and one to execute the add/remove/approval flow.

### How does it decide which group the requester means?

It runs two parallel searches (the exact phrase and a simplified version) across every connected IdP and presents the matches for the requester to confirm - it never assumes a match without confirmation when more than one group is found.

### What's automatic vs. what gets escalated to a human?

Search, employee resolution, and approval routing are automatic. Execution only happens after approval (or immediately if the tenant doesn't require it for that group). Read-only groups, disabled IdP providers, approval timeouts, and API errors are all escalated to a human with an internal note.

### Can it add or remove more than one person at a time?

Yes, up to 10 employees in a single operation for one group - but only one group per conversation; a second group requires a new request.

### What needs to be set up before this works?

At least one supported IdP (Okta, Microsoft Entra, or Google Workspace) connected and enabled for group management, with group ownership/approval configuration set per provider (and per group, for justification requirements).

## Related platform features

- **Helpdesk chatbot** - The outer container that hosts this toolkit and routes the conversation to it