Teams PowerShell Automation

Table of Contents
    Add a header to begin generating the table of contents

    If you haven’t already, check out our HelpBot Recommended Setup Guide for info on creating Teams App Setup and App Permission policies for HelpBot 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. 

    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
    				
    			

    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

    The following PowerShell will assign the App Setup Policy named HelpBot to the HelpBot Users 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 (HelpBotUsers@ktomer.com). For more details, see Assign a policy to a group.

    				
    					# Assign Teams App Setup Policy to Group 
    New-CsGroupPolicyAssignment -GroupId 'HelpBotUsers@ktomer.com' -PolicyType TeamsAppSetupPolicy -PolicyName 'HelpBot' 
    				
    			

    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 HelpBot Users 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 (HelpBotUsers@ktomer.com). For more details, see Unassign a policy that was directly assigned to users.

    				
    					# Unassign Teams App Setup Policy from Group 
    New-CsGroupPolicyAssignment -GroupId 'HelpBotUsers@ktomer.com' -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 HelpBot 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 (AlexW@ktomer.com).

    				
    					# Grant Teams App Permission Policy to user. 
    Grant-CsTeamsAppPermissionPolicy -Identity 'AlexW@ktomer.com' -PolicyName 'HelpBot' 
    				
    			

    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 (AlexW@ktomer.com).

    				
    					# Remove assigned policy by granting $null as Teams App Permission Policy. 
    Grant-CsTeamsAppPermissionPolicy -Identity 'AlexW@ktomer.com' -PolicyName $null 
    				
    			

    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 HelpBot 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 = @('adelev@ktomer.com', 'diegos@ktomer.com', 'alexw@ktomer.com') 
    
    # Batch assign Teams App Permission Policy HelpBot for users. 
    New-CsBatchPolicyAssignmentOperation -PolicyType TeamsAppPermissionPolicy -PolicyName 'HelpBot' -Identity $userIds -OperationName 'Assign HelpBot 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 = @('adelev@ktomer.com', 'diegos@ktomer.com', 'alexw@ktomer.com') 
    
    # Batch unassign Teams App Permission Policy for users. 
    New-CsBatchPolicyAssignmentOperation -PolicyType TeamsAppPermissionPolicy -PolicyName $null -Identity $userIds -OperationName 'Unassign HelpBot App Permission 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.

    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 (AdeleV@ktomer.com).

    				
    					# Get user policy assignments. 
    Get-CsUserPolicyAssignment -Identity 'AdeleV@ktomer.com' 
    				
    			

    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 HelpBot 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 = 'HelpBot' 
    
    # Find all users with the specified App Permission Policy. 
    $currentPolicyUsers = Get-CsOnlineUser -Filter "TeamsAppPermissionPolicy -eq '$permissionPolicyName'" 
    
    # Display users found. 
    $currentPolicyUsers | Select UserPrincipalName, TeamsAppPermissionPolicy | ft 
    				
    			

    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.

    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., AlexW@ktomer.com). In this example, we’re finding the Azure AD Group object for the specified email address (HelpBotUsers@ktomer.com) and passing its object id; and for the user, we use their UPN (AlexW@ktomer.com).

    				
    					# Azure AD Group Email Address 
    $groupId = 'HelpBotUsers@ktomer.com' 
    
    # 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 'AlexW@ktomer.com' -Role Member  
    				
    			

    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., AlexW@ktomer.com). In this example, we’re finding the Azure AD Group object for the specified email address (HelpBotUsers@ktomer.com) and passing its object id; and for the user, we use their UPN (AlexW@ktomer.com).

    				
    					# Azure AD Group Email Address 
    $groupId = 'HelpBotUsers@ktomer.com' 
    
    # 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 'AlexW@ktomer.com'
    				
    			

    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 HelpBot app for users: 

    The following PowerShell will assign an App Setup Policy named HelpBot to the Team (HelpBotUsers@ktomer.com), assign an App Permission Policy named HelpBot to the user (AlexW@ktomer.com), and then add that user to the specified Team.

    				
    					# Azure AD Group Email Address 
    $groupId = 'HelpBotUsers@ktomer.com' 
    # Teams User Id 
    $userId = 'AlexW@ktomer.com'
    
    # Assign Teams App Setup Policy to Group 
    New-CsGroupPolicyAssignment -GroupId $groupId -PolicyType TeamsAppSetupPolicy -PolicyName 'HelpBot' 
    
    # Assign App Permission Policy to user. 
    Grant-CsTeamsAppPermissionPolicy -Identity $userId -PolicyName 'HelpBot' 
    
    # 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  
    				
    			

    The following PowerShell will unassign the App Permission Policy from the user (AlexW@ktomer.com) and then remove that user from the Team (HelpBotUsers@ktomer.com).

    				
    					# Azure AD Group Email Address 
    $groupId = 'HelpBotUsers@ktomer.com' 
    # Teams User Id 
    $userId = 'AlexW@ktomer.com'
    
    # 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
    				
    			

    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 HelpBot to the Team (HelpBotUsers@ktomer.com), batch assign an App Permission Policy named HelpBot to the list of users, and then add those users to the specified Team.

    				
    					# Azure AD Group Email Address 
    $groupId = 'HelpBotUsers@ktomer.com' 
    # Specify a list of users.
    $userIds = @('adelev@ktomer.com', 'diegos@ktomer.com', 'alexw@ktomer.com') 
    
    # Assign Teams App Setup Policy to Group 
    New-CsGroupPolicyAssignment -GroupId $groupId -PolicyType TeamsAppSetupPolicy -PolicyName 'HelpBot' 
    
    # Batch assign Teams App Permission Policy HelpBot for users. 
    New-CsBatchPolicyAssignmentOperation -PolicyType TeamsAppPermissionPolicy -PolicyName 'HelpBot' -Identity $userIds -OperationName 'Assign HelpBot 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
    }
    				
    			
    June 30, 2021
    Was this article helpful?