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.

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

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.

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

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:

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.

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.

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?