Why Would You Need to Run Teams PowerShell Cmdlets in an Azure Automation Runbook

The new permissions requirement for Entra ID apps that want to use cmdlets from the Teams PowerShell module creates the question of what conditions could occur to make apps need to use the Teams cmdlets. After all, access to Teams structures and data is available through Graph APIs and the Microsoft Graph PowerShell SDK. The answer lies in the history of the policy-drive management framework used by Teams.

When Microsoft launched Teams in 2017, they borrowed from many existing technologies. Teams took its approach to management from Skype for Business Online and adapted many of the policies used by Skype for Business to control how meetings, messaging, and other aspects of the system worked. This decision made a lot of sense as it became clear that Teams would replace Skype for Business Online, a decision first revealed in September 2017 and eventually completed in July, 2021.

The Teams PowerShell module appeared in late 2017. I didn’t like the module very much at the time, but have become accustomed to it over time as Microsoft removed the rough edges. One such irritation was the Skype for Business connector, the component used to allow PowerShell control over Teams management policies. In February 2021, Microsoft retired the Skype for Business connector and moved its cmdlets into the Teams module. The legacy of the Skype connector cmdlets still exists today with cmdlets like Get-CsOnlineUser and Get-CsTeamsMeetingPolicy.

In general, any cmdlet with a “Team” prefix (like Get-TeamChannel) is Graph-based and an equivalent cmdlet is in the Microsoft Graph PowerShell SDK (Get-MgTeamChannel in this instance). Any cmdlet with a “Cs” prefix (like Get-CsTeamsMessagingPolicy) uses the old Skype for Business framework and doesn’t have a Graph SDK equivalent. It’s therefore a reasonable conclusion that Entra ID apps need to use the Teams PowerShell module only when apps need to interact with Teams policies. The Graph handles Entra ID app access to teams, channels, chats, meetings, and so on.

Running Teams PowerShell in Azure Automation

Running PowerShell in Azure Automation runbooks is like running PowerShell through Entra ID apps. Both need to be authentication before cmdlets run, and both need some permissions to access data. Permissions can be granted explicitly or via membership of a management role.

Unless the need exists to do widespread and extensive policy reassignment to accounts, I’m not sure that many runbooks use Teams PowerShell. The exception might be where a tenant develops a script based on Teams PowerShell and wants to run the script on a scheduled basis, or the script takes so long to run that interactive execution becomes a pain. In these cases, Azure Automation is a good answer, especially because the Connect-MicrosoftTeams cmdlet supports managed identities for authentication.

The caveat is that some of the cmdlets in the Teams PowerShell module are unsupported when application-based authentication is used. New-Team is the most notable cmdlet in this category, but that gap is easily worked around by creating a new team through Microsoft Graph PowerShell SDK cmdlets.

Configuring Azure Automation for Teams PowerShell

Temas uses much of the setup used to run other Microsoft 365 PowerShell modules with Azure Automation. An automation account must be available that’s connected to an Azure subscription. Ideally, the automation account should support managed identities. The module must be loaded as a resource into the runtime environment. Teams PowerShell supports the PowerShell V7.4 runtime engine, so a custom runtime environment can be used.

Before attempting to authenticate, the service principal for the automation account must be assigned:

• The Teams administrator role. This is what allows the automation account to run the cmdlets in the module as a Teams administrator. The role can be assigned with PowerShell or via the Entra admin center (Figure 1).
• Any Graph API application permissions needed to access the Teams data processed by runbooks. For instance, because Teams management might be gated by administrative units, the RoleManagement.Read.Directory and GroupMember.Read.All permissions are needed to read details about administrative units and the members of those units. Other Graph permissions like Chat.Read.All might be needed to read information stored in teams.

With these preprequisites in place, you should be able to create and execute runbooks using the Teams PowerShell module. Figure 2 shows the output from a very simple runbook that connects to Teams with a managed identity before listing the teams in a tenant.

Not the Normal Option

My normal course of action is to use the Microsoft Graph PowerShell SDK or Graph API requests to interact with Teams (like reporting details about Teams online meetings or analyzing chat messages with external users to figure out an allow list for external access) and I seldom use the Teams PowerShell module with Azure Automation. However, the option is there if needed, and that’s good to know.

Need some assistance to write and manage PowerShell scripts for Microsoft 365, including Azure Automation runbooks? 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.