Upgrade of Teams Policy Cmdlets Enables Use in Azure Automation

Now Possible to Make Teams Policy Assignments in Azure Automation Runbook

Microsoft released a new version (4.9) of the MicrosoftTeams PowerShell module on November 1. One of the changes made in this module is the upgrade of four policy management and assignment cmdlet sets so that they no longer have a dependency on the WinRM component. The policies include the Teams meeting and messaging policies, two of those most important and heavily used. The other two are the Teams feedback policy and the Teams voicemail policy.

Although many of the Teams PowerShell cmdlets are Graph-based, the Teams developers have been modernizing the older policy management cmdlets inherited from the Skype for Business Online connector. When modernized, cmdlets can run in environments like Azure Automation (this article explains the concept of using Teams PowerShell in Azure Automation). If you want to use Azure Automation with Teams, make sure that the service principals used for authentication have the necessary permissions.

Checking Teams Policy Assignments

Obviously, it’s a good thing for the Teams PowerShell cmdlets to support Azure Automation, but would you use these cmdlets in Azure Automation runbooks? I don’t think that you’d use Azure Automation for something like a bulk assignment of a Teams policy to user accounts. Teams already has its own bulk assignment mechanism.

The new capability is more likely to be used in periodic checks run against accounts to make sure that they have the right policy assignments. Given the number of Teams policies, it can be easy to miss out an inappropriate or erroneous assignment, so having a regularly-scheduled job to make sure that the right assignments are in place is a good idea. With the advent of the Teams Premium license, it might also be a way to make sure that these expensive add-ons ($10/user/month) are granted to the right accounts.

Example – Making Teams Policy Assignments for IT Department Members

To take a simple example, let’s assume that we want to assign specific meeting and messaging policies to members of the IT Department. The concept for the runbook is simple:

  • Find the users to process.
  • Grant the policies.

The Get-CsOnlineUser cmdlet from the Teams module hasn’t yet been modernized so it cannot be used with Azure Automation. Instead, we can use cmdlets from the Microsoft Graph PowerShell SDK or Exchange Online management modules to find target accounts. As I want to filter users based on department, I chose to use the Get-Recipient cmdlet.

The Grant-CsTeamsMeetingPolicy and Grant-CsTeamsMessagingPolicy are the two cmdlets needed to assign policies to the target accounts. Unhappily, I discovered that although the cmdlets work in an Azure Automation runbook, they don’t work when using a managed identity for authentication. Plan B duly ensued, and I reverted to fetching credentials for an account used for background processing from Azure Key Vault and used those credentials to connect to Teams instead. I guess you can’t expect perfection overnight.

Here’s the complete code:

# Connect to AzAccount to access Key Vault to fetch variables used by the script
$AzConnection = Connect-AzAccount -Identity | Out-Null
# Get username and password from Key Vault
$UserName = Get-AzKeyVaultSecret -VaultName "xxxxxx" -Name "AccountName" -AsPlainText
$UserPassword = Get-AzKeyVaultSecret -VaultName "xxxxxx" -name "AccountPassword" -AsPlainText
# Create credentials object from the username and password
[securestring]$SecurePassword = ConvertTo-SecureString $UserPassword -AsPlainText -Force
[pscredential]$UserCredentials = New-Object System.Management.Automation.PSCredential ($UserName, $SecurePassword)
Connect-MicrosoftTeams -Credential $UserCredentials
Connect-ExchangeOnline -ManagedIdentity -Organization office365itpros.onmicrosoft.com
[Array]$Users = Get-Recipient -RecipientTypeDetails UserMailbox -Filter {Department -eq 'IT'}
$Users | Format-Table DisplayName, WindowsLiveId -AutoSize
ForEach ($User in $Users) {
   Write-Output ("Processing {0} with UPN {1} to assign IT messaging and meeting policies to account" -f $User.DisplayName, $User.WindowsLiveId)
   Grant-CsTeamsMessagingPolicy -Identity $User.WindowsLiveId -Policy 'Advanced' -ErrorAction SilentlyContinue
   Grant-CsTeamsMeetingPolicy -Identity $User.WindowsLiveId -Policy 'IT Department Meeting Policy' -ErrorAction SilentlyContinue
}

Figure 1 shows the output of a test run. This doesn’t really prove anything except that the Write-Output cmdlet worked!

Updating Teams policy assignments in Azure Automation
Figure 1: Updating Teams policy assignments in Azure Automation

To make this runbook operational, we need to publish it and then link the runbook to an Azure automation schedule so that it’s run based on whatever period is deemed appropriate. Monthly seems like a good idea.

Making sure that these kind of boring, repetitive, but valuable checks are done is a good example of where Azure Automation is very useful. Sure, you could run the script interactively once a month, but you’d have to remember to do it and it’s a task likely to be interrupted by more essential (and interesting) work, so it might not get done.

Inching Forward

Microsoft is gradually modernizing the Teams PowerShell module. As each update appears, new possibilities for operational automation emerge. In this instance, we’re making sure that user accounts have the right Teams messaging and meeting policies. I’m sure you can come up with other examples.


Learn how to exploit the data available to Microsoft 365 tenant administrators through the Office 365 for IT Pros eBook. We love figuring out how things work.

6 Replies to “Upgrade of Teams Policy Cmdlets Enables Use in Azure Automation”

  1. Have updatet to Teams module to 4.9 but my job does not have enough permissions?
    Connecting to teams with service principal in a Run Book:
    Connect-MicrosoftTeams -ApplicationId $appIdTeams -CertificateThumbprint $TeamsCertThumbPrint -TenantId $tenantId

    Service Principial has delegated full Teams admin permission.
    When running runbook it fails with permissions denied.
    If I connect to teams with stored credentials, it works.
    Connect-MicrosoftTeams -Credential $Cred

    Error on following commands:
    Grant-CsTeamsComplianceRecordingPolicy -Identity $User.UserPrincipalName -PolicyName $null
    Grant-CsTeamsComplianceRecordingPolicy -Identity $User.UserPrincipalName -PolicyName $PolicyName

    Do you know if there are any other rights I need? It works with global admin rights, but not if I give global admin rights to the app I have.

    1. I reported in the article that I had to revert to using stored credentials to make the cmdlets work. I’m sure that Microsoft will improve this area (eventually), but for now it looks like this is what’s needed to make the policy management cmdlets work.

Leave a Reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.