Teams PowerShell Automation

In this article:

Automating with the Teams PowerShell Module

If you haven’t already, check out our Tikit Virtual Agent Setup Guide for info on creating Teams App Setup and App Permission policies for Tikit Virtual Agent using Microsoft Teams admin center. Once those policies have been created, deploying them to users and groups can be a repetitive task that is ready for automation. 

The Microsoft Teams admin center currently has limited support for assigning App Setup and App Permission policies, primarily focusing on individual user assignment. This manual process is great for deployments to small groups of users, but quickly becomes a lot of work to manage larger numbers of users. As a solution, Microsoft is actively developing the Teams PowerShell module to provide admins the ability to assign or remove policies. It currently support App Setup Policy assignment for both users and groups. App Permission Policies are still on a per-user basis using the PowerShell module, but can still be automated to simplify the process. 

Install and Connect to the Microsoft Teams PowerShell module

Run the following to install the Teams PowerShell module, if it’s not already installed. For more details, see Install Microsoft Teams PowerShell.

# Install the Microsoft Teams PowerShell module
Install-Module -Name MicrosoftTeams

Copy

Run the following to connect to Teams and start a session.

# Connect to Teams and start a session
Connect-MicrosoftTeams

Add/Remove App Setup Policy for a Microsoft 365/Security Group

Group assignment for policies takes a lot of work out assigning larger sets of users. At this point in time the Teams Admin center does not support group assignment for App Setup Policies, but we can use the Teams PowerShell module to manage those. We’ll be using the function New-CsGroupPolicyAssignment for both assigning and unassigning an App Setup Policy to a group. To learn more, see Assign policies to large sets of users. 

Assign App Setup Policy to group

The following PowerShell will assign the App Setup Policy named Tikit Virtual Agent to the TVAUsers group. You can specify a group by its object Id, Session Initiation Protocol (SIP) address, or email address. In this example, we use an email address ([email protected]). For more details, see Assign a policy to a group.

# Assign Teams App Setup Policy to Group
New-CsGroupPolicyAssignment -GroupId '[email protected]' -PolicyType TeamsAppSetupPolicy -PolicyName 'Tikit Virtual Agent'

Unassign App Setup Policy from group

Unassigning an App Setup Policy needs a small update to the PolicyName argument, setting it to $null to remove the assigned policy.

The following PowerShell will unassign any App Setup Policies from the TVAUsers group. You can specify a group by its object Id, Session Initiation Protocol (SIP) address, or email address. In this example, we use an email address ([email protected]). For more details, see Unassign a policy that was directly assigned to users.

# Unassign Teams App Setup Policy from Group
New-CsGroupPolicyAssignment -GroupId '[email protected]' -PolicyType TeamsAppSetupPolicy -PolicyName $null

Add/Remove App Permissions Policy for Users

The Teams admin center and the Teams PowerShell module do not currently support group assignments for App Permissions Policies, so we need to manage assignments on a per-user basis. We can address individuals for small sets of users with the function Grant-CsTeamsAppPermissionPolicy. For larger groups of users we’ll be using the batch assignment function New-CsBatchPolicyAssignmentOperation. For more details, see Unassign a policy that was directly assigned to users.

Assign App Permission Policy

The following PowerShell will assign the App Permission Policy named Tikit Virtual Agent to a user. You can specify a user by their object Id, Session Initiation Protocol (SIP) address, or email address. In this example, we use an email address ([email protected]).

# Grant Teams App Permission Policy to user.
Grant-CsTeamsAppPermissionPolicy -Identity '[email protected]' -PolicyName 'Tikit Virtual Agent'

Unassign App Permission Policy

The following PowerShell will unassign any App Permission Policies from a user. You can specify a user by their object Id, Session Initiation Protocol (SIP) address, or email address. In this example, we use an email address ([email protected]).

# Remove assigned policy by granting $null as Teams App Permission Policy.
Grant-CsTeamsAppPermissionPolicy -Identity '[email protected]' -PolicyName $null

Batch App Permission Policy Assignment

Performing batch operations can save time, especially for larger user groups, but even small lists of users can benefit.

The following PowerShell will define a list of users and batch assign an App Permission Policy with the name “Tikit Virtual Agent” to those users. You can specify a user by their object Id, Session Initiation Protocol (SIP) address, or email address. In this example, we used an array of users’ email addresses for our batch assignment.

# Specify a list of users.
$userIds = @('[email protected]', '[email protected]', '[email protected]')

# Batch assign Teams App Permission Policy Tikit Virtual Agent for users.
New-CsBatchPolicyAssignmentOperation -PolicyType TeamsAppPermissionPolicy -PolicyName 'Tikit Virtual Agent' -Identity $userIds -OperationName 'Assign TVA App Permission Policy'

The following PowerShell will define a list of users and batch unassign any App Permission Policies from those users. You can specify a user by their object Id, Session Initiation Protocol (SIP) address, or email address. In this example, we used the same array of users’ email addresses for our batch assignment.

# Specify a list of users.
$userIds = @('[email protected]', '[email protected]', '[email protected]')

# Batch unassign Teams App Permission Policy for users.
New-CsBatchPolicyAssignmentOperation -PolicyType TeamsAppPermissionPolicy -PolicyName $null -Identity $userIds -OperationName 'Unassign TVA App Permission Policy'

Find users assigned a policy

Using the Teams admin center to determine which users are directly assigned a policy can be time-consuming for more extensive user bases as it requires checking each individual user (see Assign a policy to individual users). We can display a user’s assigned policies with Get-CsUserPolicyAssignment and search for any users assigned a particular policy with Get-CsOnlineUser.

View User's Policies

The following PowerShell will display a user’s directly assigned policies and those inherited from a group using Get-CsUserPolicyAssignment. Note that if a policy is not directly assigned or inherited, it will not appear in the results returned. In that case, the user will typically use the global default policy. You can specify a user by their object Id, Session Initiation Protocol (SIP) address, or email address. In this example, we use an email address ([email protected]).

# Get user policy assignments.
Get-CsUserPolicyAssignment -Identity '[email protected]'

Find Users with Assigned Policy

Get-CsUserPolicyAssignment does not support multiple users at this time, but we can look at all directly assigned policies for users by using a filter. The following PowerShell will find all users that have been directly assigned an App Permission Policy with the name Tikit Virtual Agent and then display the results in table. In this example, we used TeamsAppPermissionPolicy in our filter, but you can also filter for other policies like TeamsAppSetupPolicy. 

# Teams App Permission Policy Name
$permissionPolicyName = 'Tikit Virtual Agent'

# Find all users with the specified App Permission Policy.
$currentPolicyUsers = Get-CsOnlineUser -Filter "TeamsAppPermissionPolicy -eq '$permissionPolicyName'"

# Display users found.
$currentPolicyUsers | Select UserPrincipalName, TeamsAppPermissionPolicy | ft

Add/Remove User From Team

Once we have our App Setup and Permission Policies assigned we can move on to adding and removing users from a Team. We can add a user to a Team with Add-TeamUser or remove a user with Remove-TeamUser.

Add User to Team

The following PowerShell will find a Team’s object id using its email address and then add a user to that Team with the Member role. Add-TeamUser requires the group’s object id and the user’s UPN (user principal name – e.g., [email protected]). In this example, we’re finding the Azure AD Group object for the specified email address ([email protected]) and passing its object id; and for the user, we use their UPN ([email protected]).

# Azure AD Group Email Address
$groupId = '[email protected]'

# Adding user to Team. The Add-TeamUser method requires an object id,
# so we’re finding the Azure AD Group object for the specified email.
$azureADGroup = Get-AzureADGroup -Filter "Mail eq '$groupId'"
Add-TeamUser -GroupId $azureADGroup.ObjectId -User '[email protected]' -Role Member

Remove User from Team

The following PowerShell will find a Team’s object id using its email address and then remove a user from that Team. Remove-TeamUser requires the group’s object id and the user’s UPN (user principal name – e.g., [email protected]). In this example, we’re finding the Azure AD Group object for the specified email address ([email protected]) and passing its object id; and for the user, we use their UPN ([email protected]).

# Azure AD Group Email Address
$groupId = '[email protected]'

# Removing user from Team. The Remove-TeamUser method requires an object id,
# so we’re finding the Azure AD Group object for the specified email.
$azureADGroup = Get-AzureADGroup -Filter "Mail eq '$groupId'"
Remove-TeamUser -GroupId $azureADGroup.ObjectId -User '[email protected]'

Putting It All Together

Now that we’ve explored assigning App Setup Policies, App Permission Policies, and adding/removing users from a Team, we can streamline onboarding the Tikit Virtual Agent app for users: 

Onboarding User

The following PowerShell will assign an App Setup Policy named Tikit Virtual Agent to the Team ([email protected]), assign an App Permission Policy named Tikit Virtual Agent to the user ([email protected]), and then add that user to the specified Team.

# Azure AD Group Email Address
$groupId = '[email protected]'
# Teams User Id
$userId = '[email protected]'

# Assign Teams App Setup Policy to Group
New-CsGroupPolicyAssignment -GroupId $groupId -PolicyType TeamsAppSetupPolicy -PolicyName 'Tikit Virtual Agent'

# Assign App Permission Policy to user.
Grant-CsTeamsAppPermissionPolicy -Identity $userId -PolicyName 'Tikit Virtual Agent'

# Finally, adding user to Team. The Add-TeamUser method requires an object id,
# so we’re finding the Azure AD Group object for the specified email.
$azureADGroup = Get-AzureADGroup -Filter "Mail eq '$groupId'"
Add-TeamUser -GroupId $azureADGroup.ObjectId -User $userId -Role Member

Offboarding user

The following PowerShell will unassign the App Permission Policy from the user ([email protected]) and then remove that user from the Team ([email protected]).

# Azure AD Group Email Address
$groupId = '[email protected]'
# Teams User Id
$userId = '[email protected]'

# Unassign App Permission Policy for user.
Grant-CsTeamsAppPermissionPolicy -Identity $userId -PolicyName $null

# Finally, removing user from Team. The Remove-TeamUser method requires an object id,
# so we’re finding the Azure AD Group object for the specified email.
$azureADGroup = Get-AzureADGroup -Filter "Mail eq '$groupId'"
Remove-TeamUser -GroupId $azureADGroup.ObjectId -User $userId

Onboarding Users

We can also use batch assignment to onboard multiple users at the same time. The recommended path for importing large numbers of users into a Team is to add those users to a distribution list and then import through the Teams app, but in our case we’ll be adding those users to the Team directly. The following PowerShell will assign an App Setup Policy named Tikit Virtual Agent to the Team ([email protected]), batch assign an App Permission Policy named Tikit Virtual Agent to the list of users, and then add those users to the specified Team.

# Azure AD Group Email Address
$groupId = '[email protected]'
# Specify a list of users.
$userIds = @('[email protected]', '[email protected]', '[email protected]')

# Assign Teams App Setup Policy to Group
New-CsGroupPolicyAssignment -GroupId $groupId -PolicyType TeamsAppSetupPolicy -PolicyName 'Tikit Virtual Agent'

# Batch assign Teams App Permission Policy TVA for users.
New-CsBatchPolicyAssignmentOperation -PolicyType TeamsAppPermissionPolicy -PolicyName 'Tikit Virtual Agent' -Identity $userIds -OperationName 'Assign TVA App Permission Policy'

# Finally, adding users to Team. The Add-TeamUser method requires an object id,
# so we’re finding the Azure AD Group object for the specified email.
$azureADGroup = Get-AzureADGroup -Filter "Mail eq '$groupId'"
foreach ($userId in $userIds) {
    Add-TeamUser -GroupId $azureADGroup.ObjectId -User $userId -Role Member
}