Tags über Entra ID Gruppe synchronisieren

<#
.SYNOPSIS
    Updates a Microsoft Teams tag based on the membership of an Entra ID group.

.DESCRIPTION
    This script synchronizes a Teams tag with the members of a specified Entra ID group.
    It adds group members to the tag if they are also members of the team and optionally
    removes tag members who are not in the group.

.PARAMETER TagName
    The name of the Teams tag to update.

.PARAMETER TeamName
    The display name of the Microsoft Team. Use either this or the parameter TeamId.

.PARAMETER GroupName
    The display name of the Entra ID group. Use either this or the parameter GroupId.

.PARAMETER TeamId
    The ID of the Microsoft Team. Use either this or the parameter TeamName.

.PARAMETER GroupId
    The ID of the Entra ID group. Use either this or the parameter GroupName.

.PARAMETER RemoveNotInGroupMembers
    (Optional) If set to $true, removes tag members who are not in the group.
    Default is $false.

.EXAMPLE
    .\Update-TeamTagFromGroup.ps1 -TeamName "Sales Team" -GroupName "Sales Group" -TagName "SalesTag"

.EXAMPLE
    .\Update-TeamTagFromGroup.ps1 -TeamId "00000-00000-00000-0000-0000" -GroupId "00000-00000-00000-0000-0000" -TagName "SalesTag"  -RemoveNotInGroupMembers $true

.NOTES
  Version:        1.0
  Author:         Thomas Thaler
  Creation Date:  2024-11-04
  Purpose/Change: Creation
#>

[CmdletBinding()]
param(
    [Parameter(Mandatory = $true)]
    [string]$TagName,

    [Parameter(Mandatory = $false)]
    [string]$TeamName,

    [Parameter(Mandatory = $false)]
    [string]$TeamId,

    [Parameter(Mandatory = $false)]
    [string]$GroupName,

    [Parameter(Mandatory = $false)]
    [string]$GroupId,

    [Parameter(Mandatory = $false)]
    [bool]$RemoveNotInGroupMembers = $false
)

try {
    # List of required modules
    $requiredModules = @(
        'Microsoft.Graph.Authentication',
        'Microsoft.Graph.Groups',
        'Microsoft.Graph.Users',
        'Microsoft.Graph.Teams'
    )

    # Install and import required modules
    foreach ($module in $requiredModules) {
        if (-not (Get-Module -ListAvailable -Name $module)) {
            Install-Module $module -Scope CurrentUser -Force
        }
        Import-Module $module -ErrorAction Stop
    }


    # Connect to Microsoft Graph with required scopes if not already connected
    if (-not (Get-MgContext)) {
        Connect-MgGraph -Scopes "Group.Read.All","User.Read.All","TeamworkTag.ReadWrite","Team.ReadBasic.All"
    }

    # Check if TeamId and/or TeamName parameter has been provided
    if (!$TeamId -and !$TeamName) {
        Write-Error "TeamId or TeamName parameter has to be present."
        exit 1
    } elseif ($TeamName -and !$TeamId) {
        # Get the Team ID based on the Team Name
        $team = Get-MgTeam -Filter "displayName eq '$TeamName'" -All
        $teamId = $team.Id
        if (!$team) {
            Write-Error "Team with name '$TeamName' not found."
            exit 1
        } elseif ($team.Count -gt 1) {
            Write-Error "Multiple teams with name '$TeamName' found."
            exit 1
        }
    } elseif ($TeamId -and $TeamName) {
        Write-Warning "TeamId and TeamName have been provided. TeamId will be used to proceed."
    } else {
        # Validate that the Team ID exists and is a team
        $team = Get-MgTeam -TeamId $TeamId -ErrorAction Stop
        $teamname = $team.DisplayName
        if (!$team) {
            Write-Error "The provided TeamId '$TeamId' is not a valid Team."
            exit 1
        }
    }

    if ($GroupName -and !$GroupId) {
        # Get the Group ID based on the Group Name
        $group = Get-MgGroup -Filter "displayName eq '$GroupName'" -All

        if (!$group) {
            Write-Error "Group with name '$GroupName' not found."
            exit 1
        } elseif ($group.Count -gt 1) {
            Write-Error "Multiple groups with name '$GroupName' found."
            exit 1
        }

        $groupId = $group.Id
    } elseif (!$groupname -and !$GroupId) {
        Write-Error "GroupId or GroupName parameter has to be present."
        exit 1
    } elseif ($GroupId -and $GroupName) {
        Write-Warning "GroupId and GroupName have been provided. GroupId will be used to proceed."
    } else {
        # Validate that the Group ID exists
        $group = Get-MgGroup -GroupId $GroupId -ErrorAction Stop
    }

    # Get the group members
    $groupMembers = Get-MgGroupMember -GroupId $groupId -All -ErrorAction Stop
    $groupMemberIds = $groupMembers.Id

    # Get the team members
    $teamMembers = Get-MgGroupMember -GroupId $teamId -All -ErrorAction Stop
    $teamMemberIds = $teamMembers.Id

    # Filter group members to those who are also team members
    $validGroupMemberIds = $groupMemberIds | Where-Object { $teamMemberIds -contains $_ }

    # Identify group members not in the team
    $groupMembersNotInTeam = $groupMemberIds | Where-Object { -not ($teamMemberIds -contains $_) }

    # Warn about group members not in the team
    foreach ($userId in $groupMembersNotInTeam) {
        $user = Get-MgUser -UserId $userId -ErrorAction SilentlyContinue
        if ($user) {
            Write-Warning "User '$($user.DisplayName)' (ID: $userId) is in group '$GroupName' but not in team '$TeamName'. Skipping addition to tag."
        } else {
            Write-Warning "User with ID $userId is in group '$GroupName' but not in team '$TeamName'. Skipping addition to tag."
        }
    }

    # Get or create the Tag
    $tag = Get-MgTeamTag -TeamId $teamId -Filter "displayName eq '$TagName'"

    # Check if tag exists
    if (-not $tag) {
        $tagMembersArray = @()
        foreach ($userId in $validGroupMemberIds) {
            $tagMember = @{
                "userId" = $userId
            }
            $tagMembersArray += $tagMember
        }

        # Create the tag with all group members
        $tag = New-MgTeamTag -TeamId $teamId -DisplayName $TagName -Members $tagMembersArray -ErrorAction Stop
    }
    else { 
        # Update existing Tag with new members
        $tagId = $tag.Id

        # Get the tag members
        $tagMembers = Get-MgTeamTagMember -TeamId $teamId -TeamworkTagId $tagId -All -ErrorAction Stop
        $tagMemberMap = @{}
        $tagMemberUserIds = @()

        foreach ($member in $tagMembers) {
            $tagMemberMap[$member.UserId] = $member.Id
            $tagMemberUserIds += $member.UserId
        }

        # Determine users to add (must be in Team)
        $usersToAdd = $validGroupMemberIds | Where-Object { -not ($tagMemberUserIds -contains $_) }
        
        # Add users to tag
        foreach ($userId in $usersToAdd) {
            New-MgTeamTagMember -TeamId $teamId -TeamworkTagId $tagId -UserId $userId -ErrorAction Stop
        }

        # Remove users from tag if parameter is true
        if ($RemoveNotInGroupMembers)   {
        $usersToRemove = $tagMemberUserIds | Where-Object { -not ($validGroupMemberIds -contains $_) }
            foreach ($userId in $usersToRemove) {
                $tagMemberId = $tagMemberMap[$userId]
                Remove-MgTeamTagMember -TeamId $teamId -TeamworkTagId $tagId -TeamworkTagMemberId $tagMemberId -ErrorAction Stop
            }
        }
    }
    Write-Host "Tag '$TagName' in team '$TeamName' has been updated based on group '$GroupName'."
}

catch {
    Write-Error "An error occurred: $_"
    exit 1
}