Automating the Removal of Users from Microsoft Teams Shared Channels with PowerShell

Managing user memberships in Microsoft Teams shared channels is an essential task for IT administrators, especially in large organizations where multiple teams and shared channels are used extensively. This PowerShell script automates the process of identifying shared channels within Teams, filtering out specific users, and removing them from the channel memberships.

In this article, we'll break down the script, which:

Retrieves shared channels from all Teams.
Filters specific users from the channel membership.
Automatically removes those users from the shared channels.

Script Overview

This script automates the process of managing shared channel memberships across Teams. It performs the following actions:

Identifies shared channels in each Microsoft Team.
Filters out users based on specific domains from the channel memberships.
Removes the filtered users from the shared channels where they are found.

Prerequisites:

Before running the script, ensure you have:

The Microsoft Teams PowerShell Module installed.
Administrative permissions to retrieve channel information and manage memberships.
Shared channels configured within Microsoft Teams.

PowerShell Script Breakdown

1. Defining the Function to Process Team Channels

The core of the script is a function called Process_TeamChannel. This function is designed to:

Retrieve all shared channels for a given team.
Identify the type of shared channel (whether it is hosted by the team or incoming from another team).
Filter out specific users based on their email domains.
Remove those users from the shared channel.

Function Process_TeamChannel {
    param (
        [string]$TeamId,
        [string]$OutputCSV
    )

    $channels = Get-TeamAllChannel -GroupId $TeamId -MembershipType Shared

    foreach ($channel in $channels) {
        $ChannelName = $channel.DisplayName
        $HostTeamId = $channel.HostTeamId

        $SharedChannelType = if ($HostTeamId -eq $TeamId) { "Team hosted channel" } else { "Incoming channel" }

The Get-TeamAllChannel cmdlet retrieves all shared channels associated with the team, which is identified by its TeamId.

2. Filtering Users by Domain

The script then retrieves the members of the shared channel using the Get-TeamChannelUser cmdlet. It filters out users who belong to specific email domains (e.g., @whukmig.onmicrosoft.com and @whcommig.onmicrosoft.com).

$Membership = Get-TeamChannelUser -GroupId $HostTeamId -DisplayName $ChannelName
$Membership = $Membership | Where-Object {($_.User -Like "*@XXX.onmicrosoft.com") -or ($_.User -Like "*@XXX.onmicrosoft.com")}

This filtering step ensures that only users from the specified domains are targeted for removal.

3. Removing Users from Shared Channels

Once the users are identified, the script removes them from the shared channel using the Remove-TeamChannelUser cmdlet.

foreach ($Member in $Membership) {
    Write-Output "Removing $($Member.User) from $($_.'Team Name') \ $ChannelName"
    Remove-TeamChannelUser -DisplayName $ChannelName -GroupId $TeamId -User $($Member.User) -Role $($Member.Role)
}

For each user, a message is logged indicating which user is being removed from which shared channel. The actual removal is handled by Remove-TeamChannelUser.

4. Processing All Teams

After defining the Process_TeamChannel function, the script applies this function to all teams within the tenant using the Get-Team cmdlet. It processes each team by passing the TeamId to the Process_TeamChannel function.

# Process all teams
Get-Team | ForEach-Object {
    $TeamId = $_.GroupId
    Process_TeamChannel -TeamId $TeamId
}

This loop ensures that all teams in the environment are scanned for shared channels, and the targeted users are removed from those channels.

Use Case:

This script is particularly useful in scenarios where:

You need to manage shared channel memberships based on specific criteria, such as removing users from certain domains.
You want to automate the removal of users from shared channels, saving time and reducing the potential for human error.
Your organization has a policy to restrict access to shared channels for users from specific email domains or partners.

Example:

Imagine that you need to remove external users (from certain partner domains) who were previously invited to your organization's shared channels. Instead of manually searching for and removing these users from each team and channel, this script automates the entire process, ensuring that your shared channels remain secure and compliant with internal policies.

Best Practices for Running the Script:

Test Before Full Deployment: As with any script that modifies user access, test it in a small environment or with a subset of teams and channels before running it in production.
Monitor for Errors: The script uses Write-Output to log actions and any issues encountered. Ensure that you review these logs after running the script.
Backup Channel Memberships: Before removing users from channels, it’s a good practice to export the current channel memberships to a CSV file as a backup for auditing purposes.

Why Automate Shared Channel Membership Management?

Managing user access across multiple shared channels can be time-consuming, especially if done manually. By automating the process, you ensure that users who no longer need access are promptly removed, improving security and simplifying compliance management.

Conclusion

This PowerShell script provides an efficient way to manage shared channel memberships in Microsoft Teams by automating the process of identifying and removing specific users. By integrating with Microsoft Teams PowerShell, the script ensures that all teams and shared channels are processed, saving time and reducing the risk of errors in large environments.

Whether you're performing routine audits, enforcing compliance, or managing external user access, this script offers a powerful tool for keeping your Teams environment secure and well-organized. By customizing the script to match your organization's needs, you can automate complex tasks and focus on higher-level administrative tasks.