Assigning Permissions to Azure AD Apps to Use the Microsoft Teams PowerShell Module

Assign the Teams Administrator Permission to Apps and Automation Accounts

Last week, I explained how to assign the Exchange.ManageAsApp permission to an Azure automation account. The permission allows an automation runbook to sign into Exchange Online using a system-assigned managed identity and run cmdlets in the Exchange Online management module. Essentially, the permission gives the automation account the right to act like an Exchange administrator who signs in interactively to run Exchange Online cmdlets. The upshot is that any script written for the Exchange Online module becomes a candidate to be run by Azure automation.

The same situation applies to the Teams PowerShell module. When someone runs the Connect-MicrosoftTeams cmdlet to connect to the Teams management endpoint in an interactive session, they can use all the rights and permissions held by their Azure AD account. If those rights and permissions include a role like Global administrator or Teams administrator, they can perform management operations for Teams at the tenant level.

Giving an App the Right to Act as an Administrator

To use the cmdlets in the Teams PowerShell module in an Azure automation runbook, the automation account must hold the permission to act as an administrator. This requirement applies to all methods of authentication used when apps use the module in background jobs, including when a runbook uses a managed identity.

A runbook connects to Teams with a managed identity like this:

Connect-MicrosoftTeams -Identity

When authenticating the connection, Azure AD evaluates the roles and permissions held by the automation account that owns the runbook. It’s equivalent to a user when they connect to Teams in an interactive PowerShell session. If the account holds a Teams administrator role, it can run cmdlets to update the Teams tenant configuration, alter policies, and update accounts.

Assigning the Teams Administrator Permission (Role)

In the previous article, we assigned the role to manage Exchange Online (which holds the Exchange.ManageAsApp permission) to the automation account. The same principle applies to Teams. Instead of assigning the role to allow the app to manage Exchange Online, we assign the role to allow it to manage Teams. As explained in the other article, the Azure AD admin center doesn’t support role assignment to automation accounts, so this must be done using PowerShell.

This code:

  • Connects to the Microsoft Graph.
  • Populates a variable with details of the service principal for the Skype and Teams Tenant Admin API app. This is an enterprise app installed into tenants to allow components like the Teams admin center to manage Teams. Its app id is always 48ac35b8-9aa8-4d74-927d-1f4a14a0b239.
  • Find the Application_access role in the set held by the Skype and Teams Tenant Admin API app.
  • Populate a variable with details of the automation account to use. In this example, the account is called TeamsAutomationAccount.
  • Populate the parameters to make the role assignment.
  • Run the New-MgServicePrincipalAppRoleAssignment cmdlet to assign the Application_access role to the service principal of the automation account.

Here’s the code:

Connect-MgGraph -Scopes AppRoleAssignment.ReadWrite.All
Select-MgProfile Beta
# Fetch details of the Teams management app
$TeamsApp = Get-MgServicePrincipal -Filter "AppId eq '48ac35b8-9aa8-4d74-927d-1f4a14a0b239'" 
$AppPermission = $TeamsApp.AppRoles | Where-Object {$_.DisplayName -eq "Application_access"} # Create the payload for the assignment
$ManagedIdentityApp = Get-MgServicePrincipal -Filter "displayName eq 'TeamsAutomationAccount'"
$AppRoleAssignment = @{
"PrincipalId" = $ManagedIdentityApp.Id
"ResourceId" = $TeamsApp.Id
"AppRoleId" = $AppPermission.Id }
# Assign the role to the service principal for the managed identity.
New-MgServicePrincipalAppRoleAssignment -ServicePrincipalId $ManagedIdentityApp.Id -BodyParameter $AppRoleAssignment

After the code runs, check the permissions for the automation account and you should find that the Teams administrative role is present (Figure 1).

The Teams administrative role assigned to the service principal for an automation account

Teams administrator permission
Figure 1: The Teams administrative role assigned to the service principal for an automation account

Remember that the access granted only allows the automation account to run administrative operations. Other operations might need consent for a Teams Graph permission.

Working with Teams Policies

The current version (4.7) of the Teams PowerShell module doesn’t support using a managed identity to run the older cmdlets from the Skype for Business Connector (like Get-CsTeamsMessagingPolicy). This is because Microsoft needs to update these cmdlets to support managed identities.

If you need to run the older cmdlets in an automation runbook, you can sign into Teams with an account that holds the Teams administrator role. For instance, you could store the credentials for an account in Azure Key Vault and use those credentials with Connect-MicrosoftTeams.

Azure Automation and Teams

Using an automation account with scheduled runbooks is an excellent way to make sure that administrative jobs get run. Being able to use common Microsoft 365 PowerShell modules like Teams expands the scope of possible work. A managed identity relieves the need to maintain credentials and keeps things more secure. All in all, it’s a nice combination.

Learn more about how the Office 365 applications really work on an ongoing basis by subscribing to the Office 365 for IT Pros eBook. Our monthly updates keep subscribers informed about what’s important across the Office 365 ecosystem.

Leave a Reply

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