Skip to content

About

Removes deleted users from 365 and local AD groups

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

2 Commits

Folders and files

Repository files navigation

Cleanup365-AD

PowerShell scripts for removing departed or disabled users from groups, in Microsoft 365 and in on-premises Active Directory.

Script Where it works What it does
ExchangeOnline/Remove-UserFromAllGroups.ps1 Exchange Online, Microsoft 365, Entra ID Removes one or more named users from distribution groups, mail-enabled security groups, room lists, and optionally Microsoft 365 Groups and Entra ID security groups. Modified version of Vasil Michev's script.
ActiveDirectory/Remove-DisabledUsersFromADGroups.ps1 On-premises Active Directory Finds every disabled user account and removes it from its AD groups, with a backup and a restore mode.

Always run with -WhatIf first. Both scripts change group membership in production directories. Review what they report before running them for real.


Remove-UserFromAllGroups (Exchange Online / Microsoft 365)

Requirements

Permissions

  • Exchange Online: a role that can manage distribution group and Microsoft 365 Group membership, such as Exchange Administrator or Recipient Management.
  • Microsoft Graph: Group.ReadWrite.All and Directory.Read.All. Role-assignable groups also need RoleManagement.ReadWrite.Directory (Privileged Role Administrator).

The script connects to Exchange Online and Graph if no suitable session exists. App-only (certificate) Graph connections are supported.

Usage

# Preview: show every group the user would be removed from, change nothing
.\ExchangeOnline\Remove-UserFromAllGroups.ps1 -Identity jdoe@contoso.com -IncludeOffice365Groups -IncludeAADSecurityGroups -WhatIf

# Remove one user from all group types
.\ExchangeOnline\Remove-UserFromAllGroups.ps1 -Identity jdoe@contoso.com -IncludeOffice365Groups -IncludeAADSecurityGroups

# Several users, CSV to a chosen path, no console output
.\ExchangeOnline\Remove-UserFromAllGroups.ps1 -Identity jdoe,asmith -OutputPath C:\Reports\removals.csv -Quiet

# Dot-source to use the function in a pipeline
. .\ExchangeOnline\Remove-UserFromAllGroups.ps1
Get-User -Filter "Department -eq 'Sales'" | Remove-UserFromAllGroups

Parameters

Parameter Description
-Identity One or more users. Any Exchange identifier works: alias, UPN, SMTP address, GUID, DN or display name.
-IncludeOffice365Groups Also remove the user from Microsoft 365 Groups.
-IncludeAADSecurityGroups Also remove the user from Entra ID security groups (via Microsoft Graph).
-OutputPath CSV file to write. Defaults to a timestamped file in the current folder.
-Quiet No pipeline output. The CSV is still written.
-WhatIf / -Confirm Preview without changes, or prompt per group.

Output

One row per attempted removal, returned to the pipeline and written to the CSV:

Column Meaning
Status Removed, WhatIf, Skipped or Failed
Detail Why a removal was skipped or failed, in plain language
Source Exchange or Graph
User, UserId, Group, GroupName, GroupType What was changed

What it does not do

  • It does not remove group ownership. A user who is an owner of a Microsoft 365 Group fails with a clear message and must be removed as owner first.
  • Dynamic groups and groups synced from on-premises AD cannot be changed here. Entra ID security groups of these kinds are reported as Skipped, and Exchange groups of these kinds as Failed with the reason. Change the membership rule, or change the group in on-premises AD.

Remove-DisabledUsersFromADGroups (on-premises Active Directory)

Requirements

  • Windows PowerShell 5.1 or PowerShell 7+ on Windows
  • The ActiveDirectory module (RSAT: Active Directory Domain Services tools)

Permissions

  • Write access to the member attribute of every group the script will change. Delegated OU permissions are fine. Groups the account cannot change are logged as Failed and the run continues.
  • Privileged groups (only with -IncludePrivilegedGroups) need Domain Admin or equivalent.

Usage

# 1. Preview. Writes the plan CSV and changes nothing.
.\ActiveDirectory\Remove-DisabledUsersFromADGroups.ps1 -WhatIf

# 2. Real run, scoped and with exclusions. Prompts per group.
.\ActiveDirectory\Remove-DisabledUsersFromADGroups.ps1 `
    -SearchBase "OU=Leavers,DC=contoso,DC=com" `
    -MinDaysDisabled 30 `
    -ExcludeUser "tmpl-*","breakglass*" `
    -ExcludeGroup "LIC-*","AADC-SyncScope"

# 3. Undo a run
.\ActiveDirectory\Remove-DisabledUsersFromADGroups.ps1 -RestoreFrom .\2026-11-13_10-00-00_DisabledUserGroupRemoval_results.csv

Add -Confirm:$false for unattended runs.

Parameters

Parameter Description
-SearchBase Only process disabled users under this OU. Defaults to the whole domain.
-MinDaysDisabled Skip accounts whose userAccountControl changed fewer than N days ago. Protects staff on leave and accidental disables.
-ExcludeUser Wildcard patterns matched against sAMAccountName, UPN and DN.
-ExcludeGroup Wildcard patterns matched against group name, sAMAccountName and DN.
-IncludePrivilegedGroups Also process Domain Admins, Enterprise Admins, Administrators, the Operators groups and any group with adminCount=1.
-RestoreFrom Re-add every membership from a previous plan or results CSV.
-Server Domain controller to use. Defaults to the PDC emulator.
-OutputFolder Where the CSV files go. Defaults to the current folder.

Built-in safety

  • Never touched: Administrator (RID 500), Guest, krbtgt and RODC krbtgt_* accounts, DefaultAccount, WDAGUtilityAccount.
  • Never modified: Protected Users and Denied RODC Password Replication Group.
  • Privileged groups are skipped unless you opt in.
  • A plan CSV is written before any change. A results CSV records every outcome. Either file works with -RestoreFrom.
  • Prompts per group by default (ConfirmImpact = High).

Things to check before running

Removing group membership affects every system that relies on those groups. Review these and add exclusions where needed:

  • Group-based licensing. If Entra Connect syncs your groups and Microsoft 365 licences are assigned by group, removal also removes the licence. Mailbox and OneDrive data are deleted after the grace period. Exclude licensing groups unless that is intended.
  • Entra Connect group filtering. If Entra Connect only syncs members of a specific group, removing a user from it deletes their cloud account. Exclude that group.
  • Template accounts. Disabled accounts used as copy templates for new starters lose their groups. Exclude them.
  • Temporarily disabled staff. Use -MinDaysDisabled, and keep the results CSV so you can restore.
  • Break-glass accounts. The built-in Administrator is protected. Exclude any other disabled emergency account by name.
  • AdminSDHolder. Users removed from privileged groups keep adminCount=1 and blocked inheritance. The script lists them so you can clean that up.
  • Group writeback. Groups written back from Microsoft 365 are overwritten on the next sync.
  • Multi-domain forests. Domain local groups in other domains are not visible in a user's memberOf. Run the script once per domain.

Not changed by this script

  • Permissions granted directly to the user on files, folders or applications.
  • The user's primary group (normally Domain Users). Users with a different primary group are reported.

Output files and privacy

Both scripts write CSV files containing user and group names to the current folder unless told otherwise. .gitignore excludes *.csv so these files are not committed by accident. Store them somewhere access-controlled.

Credits and license

Remove-UserFromAllGroups.ps1 is built on Vasil Michev's work. It is a modified version of his Remove-UserFromAllGroups script from michevnew/PowerShell, described in his post on michev.info. The overall approach, the group discovery and the removal logic are his. The changes made here are mostly about error handling, reporting and compatibility, and are listed in CHANGELOG.md.

His original is published under the MIT License, Copyright (c) 2018 Vasil Michev. That license applies to the modified script too, and its full text is in ExchangeOnline/LICENSE. Thanks to Vasil for publishing it.

Disclaimer

These scripts are provided as-is, without warranty. Test them in a non-production environment or with -WhatIf before use.

About

Removes deleted users from 365 and local AD groups

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages