Practical Microsoft Graph PowerShell for Microsoft Teams

Practical Microsoft Graph PowerShell for Microsoft Teams

Managing Microsoft Teams if you’re an IT Pro can often be a complicated process that requires multiple services to be combined. When provisioning a team, services such as Azure Active Directory (AAD), SharePoint Online, and Exchange Online connect to the core plumbing. It means that for you as an IT administrator, you need to connect to potentially all the connected services to manage a team in Microsoft Teams.

From a user interface perspective, this means using multiple administration consoles or multiple PowerShell modules that need installing, importing, and connecting independently.

Install-Module -Name AzureAD

Install-Module -Name Microsoft.Online.SharePoint.PowerShell

Install-Module -Name ExchangeOnlineManagement




Import-Module -Name AzureAD

Import-Module -Name Microsoft.Online.SharePoint.PowerShell

Import-Module -Name ExchangeOnlineManagement




Connect-AzureAD

Connect-SPOService

Connect-ExchangeOnline

Microsoft does, however, provide a Teams Administration portal that is now an easy place to manage most of the configuration and management tasks you need to complete within Microsoft Teams. However, as with most things within Microsoft 365, many configuration settings are either unavailable within Microsoft Teams, or only available within the Microsoft Graph or PowerShell.

How to install the Microsoft Teams PowerShell module

The good news is that Microsoft provides a specific PowerShell module for managing Microsoft Teams called “MicrosoftTeams.” You can easily install the Microsoft Teams PowerShell module using the following command:

Install-Module -Name MicrosoftTeams -Force -AllowClobber

Import-Module -Name MicrosoftTeams

Once installed, you can then manage specific configurations and settings for Microsoft Teams. A simple example would be creating a new team in Microsoft Teams with the following PowerShell command:

New-Team `

-DisplayName "My New Team" `

-Description "My New Team Description"

Most of the commands are prefixed with “Team” or “Teams,” denoting they are for Microsoft Teams; however, some of them use either “CsTeam” or “CsTeams” in the name, which are legacy commands ported over from the older Skype for Business PowerShell module.

Many of the PowerShell commands wrap existing Microsoft Graph API capabilities, which means that when Microsoft adjusts the APIs, the PowerShell commands also need updating. It often leads to the deprecation of commands, especially when resolving them would require significant effort or when a similar command is available within the Microsoft PowerShell Graph SDK.

How to leverage the Microsoft Graph PowerShell SDK

The Microsoft Graph PowerShell SDK serves as an API wrapper for the Microsoft Graph APIs, exposing the complete API set for use in PowerShell. It comprises multiple PowerShell modules that directly map to Microsoft Graph API commands.

The primary module is “Microsoft.Graph,” which contains all the core connection commands needed for using the Microsoft Graph. Additional modules target specific tasks such as managing users, mail, sites, compliance, and of course teams and groups. Each module contains the same name as the primary with the category appended. You can see this in the example list below:

Users: Microsoft.Graph.Users

Mail: Microsoft.Graph.Mail

Sites: Microsoft.Graph.Sites

Compliance: Microsoft.Graph.Compliance

Teams: Microsoft.Graph.Teams

All modules (approx. 35) automatically import when the primary module imports. To import the primary and additional modules, you use the following PowerShell command:

Install-Module Microsoft.Graph

Import-Module Microsoft.Graph

Once this is completed, executing the following command will display all the imported modules:

Get-InstalledModule Microsoft.Graph.*
imported modules

You can view all the Microsoft Teams commands using the following command:

Get-Command -Module Microsoft.Graph.Teams
Microsoft Teams commands

The first task is to connect using the Microsoft Graph PowerShell SDK, which requires you to set the scopes (permissions) required to manage any specific services. To view the available scopes (permissions), you can use the following command:

Find-MgGraphPermission teams -PermissionType Delegated
Microsoft Graph permissions

To connect to Microsoft Teams using the required permissions, you can use the following command:

Select-MgProfile -Name "beta"

$scopes = @(

"Group.ReadWrite.All",

"GroupMember.ReadWrite.All",

"TeamsApp.ReadWrite.All",

"TeamsAppInstallation.ReadWriteForTeam",

"TeamsAppInstallation.ReadWriteSelfForTeam",

"TeamSettings.ReadWrite.All",

"TeamsTab.ReadWrite.All",

"TeamMember.ReadWrite.All"

)

Connect-MgGraph -Scopes $scopes

Now that you have a connection to Microsoft Teams, you can start configuring and managing Microsoft Teams. The most common commands to use are the following:

Add-MgChatMember

Add-MgTeamMember

Get-MgTeam

Get-MgTeamChannel

New-MgTeam

New-MgTeamChannel

Remove-MgTeam

Remove-MgTeamMember

Update-MgTeam

PowerShell is often the best approach to deploying any settings within Microsoft Teams. The current commands available within the Microsoft Graph PowerShell SDK provide a mix of functions from viewing policies and configuration to setting some of the more obscure values related to calling. Some of the most helpful management commands are below:

Before you can retrieve any details of a team, you need to know the ID of the one you are looking for. You can retrieve the list of Groups, then grab the ID of the “unified” group (team connected) you wish to use with the command below:

 Get-MgGroup | Format-List Id, DisplayName, Description, GroupTypes

Once you identify the team to work with from the list, you can populate a reuse variable:

$group = Get-MgGroup -Filter "DisplayName eq 'Sales Planning'"

Now you can reuse the “Group ID” command to work with the team:

# Retrieve Teams by ID

$team = Get-MgTeam -TeamId $group.Id

Write-Host $team.DisplayName




# View All Properties About Selected Team

$team = Get-MgTeam -TeamId $group.Id

$team | Select-Object *




# View All Members of a Team

$team = Get-MgTeam -TeamId $group.Id

$members = Get-MgTeamMember -TeamId $team.Id

$members | Select-Object DisplayName




# Create a New Group Then Convert to a Team

$group = New-MgGroup `

-DisplayName "New Group" `

-MailEnabled:$False `

-MailNickName "newgroup" `

-GroupTypes "Unified" `

-SecurityEnabled




Using Namespace Microsoft.Graph.PowerShell.Models

[MicrosoftGraphTeam1]@{

Template = [MicrosoftGraphTeamsTemplate]@{

Id = 'com.microsoft.teams.template.OrganizeHelpDesk'

}

Group = $group

} | New-MgTeam




$team = Get-MgTeam -TeamId $group.Id




# Create a New Team

Using Namespace Microsoft.Graph.PowerShell.Models

[MicrosoftGraphTeam1]@{

Template = [MicrosoftGraphTeamsTemplate]@{

Id = 'com.microsoft.teams.template.OrganizeHelpDesk'

}

DisplayName = "New Team"

Description = "New Team Description"

} | New-MgTeam




$group = Get-MgGroup -Filter "DisplayName eq 'New Team'"

$team = Get-MgTeam -TeamId $group.Id




# Add a Team Owner

$group = Get-MgGroup -Filter "DisplayName eq 'New Team'"

$team = Get-MgTeam -TeamId $group.Id




$user = Get-MgUser -UserId "[email protected]"

$properties = @{

"@odata.type" = "#microsoft.graph.aadUserConversationMember";

"[email protected]" = "https://graph.microsoft.com/beta/users/" + $user.Id

}

$role = "owner"




New-MgTeamMember `

-TeamId $team.Id `

-Roles $role `

-AdditionalProperties $properties



# Add a Private Teams Channel Then Add a Member

$channel = New-MgTeamChannel `

-TeamId $team.Id `

-DisplayName "New Team Channel 2" `

-Description "New Team Channel Description 2" `

-MembershipType "Private"




$user = Get-MgUser -UserId "[email protected]"

$properties = @{

"@odata.type" = "#microsoft.graph.aadUserConversationMember";

"[email protected]" = "https://graph.microsoft.com/beta/users/" + $user.Id

}




New-MgTeamChannelMember `

-ChannelId $channel.Id `

-Team $team.Id `

-Id $user.Id `

-Roles "Member" `

-AdditionalProperties $properties

Just remember that changing actions may require further permissions than the original connection. When necessary, you can do this by reissuing the connection command with the appended permissions. For writing messages and sending them, you will need the “ChannelMessage.Send“, “Chat.ReadWrite“, and “ChatMessage.Send” commands:

# Post a Message to a Channel
$message = "New Sample Message"
New-MgTeamChannelMessage `
-ChannelID $channel.Id `
-TeamId $team.Id `
-Body @{ Content = $message }
Microsoft Teams sample message
# Post a New Message and Then a Reply

$message = New-MgTeamChannelMessage `

-ChannelID $channel.Id `

-TeamId $team.Id `

-Body @{ Content = "My New Message" }




$reply = New-MgTeamChannelMessageReply `

-ChannelID $channel.Id `

-TeamId $team.Id `

-ChatMessageId $message.Id `

-Body @{ Content = "Great Comment" }
Microsoft Teams reply

As you can see, using the Microsoft Graph PowerShell SDK provides excellent capabilities from the highest level of creating and managing teams to posting messages. To enhance this even further, a command called “Invoke-MgGraphRequest” allows you to pass an actual Microsoft Graph request instead of using a specific command. For example, you could use the following URL and particular properties to add a new message:

https://graph.microsoft.com/v1.0/teams/$($team.Id)/channels/$($channel.Id)/messages

The command is powerful and allows you to use a more developer-centric approach to executing PowerShell. To learn more about the Microsoft PowerShell Graph SDK in general and teams, you can use the following support pages from Microsoft: Microsoft Graph PowerShell overview and Microsoft Graph PowerShell Cmdlets.