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.
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 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 (TVAUsers@ktomer.com). For more details, see Assign a policy to a group.
# Assign Teams App Setup Policy to Group
New-CsGroupPolicyAssignment -GroupId 'TVAUsers@ktomer.com' -PolicyType TeamsAppSetupPolicy -PolicyName 'Tikit Virtual Agent'
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 (TVAUsers@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 'TVAUsers@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 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 (AlexW@ktomer.com).
# Grant Teams App Permission Policy to user.
Grant-CsTeamsAppPermissionPolicy -Identity 'AlexW@ktomer.com' -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 (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 “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 = @('adelev@ktomer.com', 'diegos@ktomer.com', 'alexw@ktomer.com')
# 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 = @('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 TVA 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 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
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 (TVAUsers@ktomer.com) and passing its object id; and for the user, we use their UPN (AlexW@ktomer.com).
# Azure AD Group Email Address
$groupId = 'TVAUsers@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 (TVAUsers@ktomer.com) and passing its object id; and for the user, we use their UPN (AlexW@ktomer.com).
# Azure AD Group Email Address
$groupId = 'TVAUsers@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 Tikit Virtual Agent app for users:
The following PowerShell will assign an App Setup Policy named Tikit Virtual Agent to the Team (TVAUsers@ktomer.com), assign an App Permission Policy named Tikit Virtual Agent to the user (AlexW@ktomer.com), and then add that user to the specified Team.
# Azure AD Group Email Address
$groupId = 'TVAUsers@ktomer.com'
# Teams User Id
$userId = 'AlexW@ktomer.com'
# 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
The following PowerShell will unassign the App Permission Policy from the user (AlexW@ktomer.com) and then remove that user from the Team (TVAUsers@ktomer.com).
# Azure AD Group Email Address
$groupId = 'TVAUsers@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 Tikit Virtual Agent to the Team (TVAUsers@ktomer.com), 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 = 'TVAUsers@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 '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
}
