Removing Members from Groups Can be Complicated

Recently, I discussed how to use Microsoft Graph PowerShell SDK cmdlets to copy the memberships of Entra ID groups from one user to another. I commented that in some cases you might want to remove the memberships for the source user but left that code to the reader to develop and incorporate into the script.

Within an hour of publication, I received a couple of messages asking how to remove users from group memberships. It’s a fair question because the cmdlets used for the task differ across group types. Specifically:

• For Microsoft 365 and security groups, use the Remove-MgGroupMemberByRef cmdlet from the Microsoft Graph PowerShell SDK. At least, that’s the facile answer. As explained below, the real answer is more complicated.
• For distribution lists and mail-enabled security groups, use the Remove-DistributionGroupMember cmdlet from the Exchange Online management module.

Some ask why the membership of mail-enabled security groups is managed using Exchange cmdlets. The answer lies in the mail-enabled nature of these groups. Because they are mail-enabled, their source directory is the Exchange ExODS (Exchange Online Directory Store) rather than Entra ID. Synchronization and dual-write updates keep the two directories in step.

In any case, removing a user account from a distribution list or mail-enabled security group is straightforward:

Remove-DistributionGroupMember -Identity $GroupId -Member $UserId -Confirm:$false -ErrorAction Stop
Write-Host ("User {0} removed from distribution list {1}" -f $TargetDisplayName, $GroupDisplayName) -ForegroundColor Yellow

Why Things are More Complicated with Microsoft 365 Groups

Because of the need to respect how group ownership works, things are a little more complex with Microsoft 365 groups, including the groups used for Teams, and Viva Engage. The rules are:

• If you remove a member, you must check if the account is a group owner. If so, you remove the group owner first and then remove the member.
• However, if the account is the only group owner, you can’t remove them because this would leave the group in an ownerless state.

The Microsoft 365 administrative portals don’t permit the removal of the last owner and insist that groups have at least one owner. It’s possible that groups get into an ownerless state if the account of the last owner is deleted. At that point, the groups ownership governance policy can attempt to find a new owner (if the tenant has Entra P1 licenses) or you can write a PowerShell script to look for a new owner.

Code to Remove Members from Microsoft 365 Groups

The logic for removing a group member is therefore:

• Use the Get-MgGroupOwner cmdlet to fetch the set of group owners and check the set to see if the member being deleted is a group owner.
• If yes, and the number of owners is one, exit.
• If yes, and more than one owner exists, run the Remove-MgGroupOwnerByRef cmdlet to remove the owner first and then run the Remove-MgGroupMemberByRef cmdlet to remove the member.

The usual approach for this kind of processing is to create a function, so here’s an example of a function that takes the user identifier, group identifier, and group display name as parameters (the latter is purely for output purposes) to process the removal of a user account from a Microsoft 365 group or security group:

function Remove-UserFromM365Group {
# Remove a user account from a Microsoft 365 group, checking if the user is an owner first. 
# If the user is an owner and they are not the last owner,
# the function removes the user from as both an owner and a member of the group.
    param (
        [Parameter(Mandatory = $true)]
        [string]$UserId,
        [Parameter(Mandatory = $true)]
        [string]$GroupId,
         [Parameter(Mandatory = $true)]
        [string]$GroupName
    )
    
    $Outcome = $null
    [array]$Owners = Get-MgGroupOwner -GroupId $GroupId | Select-Object -ExpandProperty Id
    if ($UserId -in $Owners) {
        if ($Owners.count -eq 1) {
            Write-Host ("The {0} group has only one owner - can't remove the last owner" -f $GroupDisplayName) -Foregroundcolor Red
            $Outcome = "Failed - can't remove the last owner of a group"
            return $Outcome
        }
        Write-Host ("User {0} is an owner of group {1} - removing both owner and member links" -f $TargetDisplayName, $GroupDisplayName) -ForegroundColor Yellow
        try {
            Remove-MgGroupOwnerByRef -DirectoryObjectId $UserId -GroupId $GroupId
        } catch {
            Write-Host ("Failed to remove user {0} as owner from group {1}: {2}" -f $TargetDisplayName, $GroupDisplayName, $_.Exception.Message) -ForegroundColor Red
            $Outcome = "Failed to remove owner"
            return $Outcome
        }
    }
    try {
        Remove-MgGroupMemberByRef -DirectoryObjectId $UserId -GroupId $GroupId
    } catch {
        Write-Host ("Failed to remove user {0} as member from group {1}: {2}" -f $TargetDisplayName, $GroupDisplayName, $_.Exception.Message) -ForegroundColor Red
        $Outcome = "Failed to remove member"
        return $Outcome
    }

    $Outcome = ("User {0} removed from group {1}" -f $SourceDisplayName, $GroupDIsplayName)
    return $Outcome
}

Better PowerShell developers than I could probably tidy the function, but the code works and demonstrates the principles behind removing members from a Microsoft 365 group (or security group), which is what I set out to do. I’ve updated the original script in GitHub, and you can download the complete code from the Office 365 for IT Pros repository.

Figure 1 shows how to run the script, specifying a source account, a target account, and a Boolean parameter controlling whether to remove the transferred memberships from the source account.

Removing Members from Groups Requires Knowledge

The question about removing group memberships is a great example of why it’s important to understand the technology and how Microsoft 365 really works before attempting to automate operations. Many blogs give partial answers. Without knowledge, you can’t fill in the gaps to create a complete answer, which is why we have the Office 365 for IT Pros eBook including the companion Automating Microsoft 365 PowerShell eBook.

Need some assistance to write and manage PowerShell scripts for Microsoft 365? Get a copy of the Automating Microsoft 365 with PowerShell eBook, available standalone or as part of the Office 365 for IT Pros eBook bundle.