---
title: "Entra - Managing Distribution List Membership"
slug: "manage-entra-distribution-list-membership"
description: "Feature Settings to allow the Entra ID connector to Manage Distribution Lists"
status: "new"
updated: 2026-10-28T21:36:01Z
published: 2026-10-28T21:36:01Z
canonical: "help.claritysecurity.com/manage-entra-distribution-list-membership"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://help.claritysecurity.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Entra - Managing Distribution List Membership

**Estimated time to complete:** 30 minutes (most of it is the prerequisites)

If you run into any problems, please contact your support team or support@claritysecurity.io.

## Overview

If you've connected Entra ID (formerly Azure AD) to Clarity, Clarity can now also add people to and remove them from your classic distribution lists in Exchange Online. These lists already appear in Clarity as groups on your Entra ID application. With this feature turned on, their membership is granted and revoked automatically along with the rest of a person's access, through access requests, access reviews, and automatic assignment rules.

> [!WARNING]
> **Note**
> 
> Unlike other groups, Microsoft doesn't let distribution list membership be changed through Entra ID. It can only be changed through Exchange Online's admin tools. So Clarity makes these changes by running a small, built-in script on a server you control, using the same Script Host setup already used for on-premises Active Directory and Exchange actions.

## What Clarity can and cannot manage

Clarity manages **classic distribution lists** only. A list qualifies when it is mail-enabled and is *not* any of the types below.

> [!NOTE]
> **Note**
> 
> This feature does nothing until you configure it. If you don’t set a Script Host on your Entra ID application, distribution lists stay unmanaged exactly as they are today.

| Group type | Managed by this feature? |
| --- | --- |
| Classic distribution list (mail-enabled) | **Yes** |
| Microsoft 365 group | No (managed the same way as today) |
| Mail-enabled security group | No |
| Dynamic distribution list | No (membership is set by a rule, which Clarity will not override) |
| Group synced from on-premises Active Directory | No (the on-premises directory is the source of truth) |
| Security group | No (managed the same way as today) |

A few more limits:

- Only **membership** is managed. Clarity does not change who **owns** a distribution list.
- Distribution lists can’t be used as **default entitlements** for the application.
- Unsupported list types still appear in Clarity as they do today. They just can’t be requested or assigned automatically.

## Before you begin

Clarity assumes the prerequisites below are in place and does not check them for you. If one is missing, distribution list changes **fail with an error**; they never silently do nothing. Confirm all five with your IT team before you turn the feature on.

### 1. An up-to-date ClarityConnect agent

The distribution list scripts ship with ClarityConnect. Make sure the agent you’ll use is running a current version. If you’re unsure, ask your customer success team.

### 2. A Script Host that can reach Exchange Online

You need a Script Host already set up in Clarity. It must be **active** and linked to **exactly one** ClarityConnect agent.

The server the Script Host points to must have Microsoft’s **Exchange Online Management** PowerShell module installed (version 2 or later). Run this on that server:

`Install-Module -Name ExchangeOnlineManagement -Force`

> [!NOTE]
> Note
> 
> Install the module on the **remote server the Script Host targets**, not on the ClarityConnect agent machine.

3. A service account that can sign in without multi-factor authentication

Clarity connects to Exchange Online with the username and password saved on your Script Host.

Important

This sign-in fails for any account that requires multi-factor authentication or is blocked by a Conditional Access policy that doesn’t allow password-only sign-in. If your service account falls under either, distribution list changes will fail. The usual fix is a dedicated service account that is explicitly excluded from those policies.

### 4. Least-privilege Exchange permissions for that account

The account needs only two Exchange roles: **Distribution Groups** and **Mail Recipients**. Grant them through a dedicated role group instead of a broad administrator role. For example:

```powershell
New-RoleGroup -Name "Clarity DL Membership" -Roles "Distribution Groups", "Mail Recipients" -Members "svc-clarityconnect@contoso.com"
```

Replace the example address with your service account.

### 5. Exchange scripts allowed on the agent

Two script settings on the ClarityConnect agent will block these changes if they’re wrong:

- Script execution must be **enabled** for the agent.
- The **Exchange** script category must be allowed. If the agent limits which categories it runs, Exchange must be on the allowed list and must not be on the blocked list.

## What access the Script Host needs

### Server sign-in account

This is the account in the Script Host’s **Authentication** section. ClarityConnect signs in to the server as this account, copies the script to a temporary file, runs it with PowerShell, and deletes it afterward.

| The account must be able to… | Details |
| --- | --- |
| Sign in to the server remotely | **WinRM:** a member of the server’s local **Remote Management Users** group (or **Administrators**). **SSH:** allowed to sign in through the server’s OpenSSH service. |
| Write temporary files | **WinRM:** its own temp folder. **SSH:** `C:\Windows\Temp`. |
| Run PowerShell scripts | Clarity runs the script with the execution policy set to *Bypass*. A Group Policy that enforces an execution policy for all scripts overrides this and blocks the script. |
| Load the Exchange Online Management module | Install the module for all users (see prerequisite 2) so this account can use it. |

This account does **not** need any Exchange, Entra ID, or domain administrator rights. It only has to sign in and run PowerShell on this one server.

### Exchange Online account

This is the account in the Script Host’s **Exchange Credentials** section. The script uses it to connect to Exchange Online and change distribution list membership.

| Requirement | Details |
| --- | --- |
| Sign-in method | Username and password, with no multi-factor authentication or blocking Conditional Access policy (see prerequisite 4). |
| Exchange roles | **Distribution Groups** and **Mail Recipients** only. Grant them with a dedicated role group instead of a broad administrator role (example below). |
| List managers | Only needed for lists that have managers set. See [Lists with managers](/docs/manage-entra-distribution-list-membership#lists-with-managers). |

## Setting it up

1. Go to **Applications** and open your Entra ID application.
2. Click **Edit**.
3. Find the field **Distribution List Script Host (optional)**.
  1. If you see “No script hosts are configured. Add one under Script Hosts admin.”, create a Script Host first. Only Script Hosts that are active and linked to exactly one ClarityConnect agent appear in this list.
4. Select the **Script Host** that can reach Exchange Online, then save.

That’s the whole setup. As the help text under the field says, leaving it unset disables distribution list provisioning for the application.

After you save, Clarity checks the distribution lists it already knows about and marks the eligible ones as available to request and revoke. You don’t need to run a new sync or an onboarding script.

**To turn the feature off,** clear the field and save. Eligible lists stop being requestable, and no further changes are sent to Exchange.

## How it works day to day

Once it’s set up, distribution lists work like any other access in Clarity. They can be requested, approved, assigned by rule, reviewed, and revoked. A few behaviors are specific to distribution lists.

### Changes finish shortly after approval, not instantly

Each change is handed to your ClarityConnect agent, which picks it up and runs it against Exchange Online. A granted or revoked distribution list shows as **pending** for a short time before it completes, the same way on-premises access already works in Clarity.

Clarity records a change **only after Exchange confirms it succeeded.** If a change fails, nothing is recorded as granted or revoked, so Clarity always reflects what’s actually true in Exchange.

### Large changes finish gradually

A ClarityConnect agent runs up to about **20 script changes per minute**, and that capacity is shared with any other scripts the same agent runs. Everyday requests won’t notice this. A bulk change, such as a new assignment rule that affects hundreds of people, finishes over a period of time rather than all at once. The changes are queued and will complete, so allow time before treating a pending change as a problem.

### Repeating a change is safe

Adding someone who is already a member, or removing someone who isn’t one, succeeds without an error. Running a request again does no harm.

### Lists with managers

If a distribution list has managers assigned (the **ManagedBy** setting in Exchange), Exchange lets only those managers change its membership. Clarity respects this on purpose and does not bypass it.

If your service account isn’t a manager of that list, the change fails with a message naming the list and its managers. To fix it, either:

- Add your Clarity service account to the list’s managers, or
- Clear the **ManagedBy** setting on the list.

### Service users without a linked identity

Distribution list changes require a Clarity identity. If a list membership belongs to a service user that isn’t linked to an identity, Clarity won’t attempt the change and shows a message explaining why.

### When something goes wrong

Failures appear on the access record and in the audit log with **the exact message Exchange returned**, for example that a mailbox couldn’t be found or that the account lacks permission. You see the real reason instead of a generic failure, so you can act on it directly.

If a change never runs, most often because the ClarityConnect agent is offline, it’s marked as failed with a timeout reason after up to 24 hours. A change that starts but doesn’t finish within about 10 minutes is also marked as failed. Changes never stay pending forever, and they are never reported as successful unless Exchange confirmed them.

## Tips and best practices

- **Set the Script Host last.** Finish all five prerequisites first, then set the field, so the first request has everything it needs to succeed.
- **Test with one list and one person** before turning on assignment rules that affect many people.
- **Use a dedicated service account**, not a person’s account. It keeps the audit trail clear and won’t break when someone changes their password or leaves.
- **Check ManagedBy on your important lists** ahead of time. It’s the most common reason an otherwise correct setup fails.
- **Check the list type first.** If a list can’t be requested, compare it to the table above before raising an issue. Mail-enabled security groups, dynamic lists, and groups synced from on-premises are all excluded on purpose.

## Need Help?

If you have any problems, contact your customer success team. You can also get in touch with our general support [via email](mailto:support@claritysecurity.io), open a [support ticket](https://support.claritysecurity.com/home). Our general support team is available Monday - Friday from 8:00 AM - 6:30 PM CST.