Grant-CsTeamsMeetingPolicy: assign a Teams policy to a user, a group, many users or the whole tenant

Teams policies (meeting, messaging, calling, app setup, ...) are assigned with Grant-Cs<PolicyType> cmdlets. For a meeting policy, after Connect-MicrosoftTeams:

# One user
Grant-CsTeamsMeetingPolicy -Identity anna@contoso.com -PolicyName "Restricted Meetings"

# A group (for example a security group or distribution list), with a rank
Grant-CsTeamsMeetingPolicy -Group sales@contoso.com -PolicyName "Restricted Meetings" -Rank 1

# Org-wide default
Grant-CsTeamsMeetingPolicy -Global -PolicyName "Restricted Meetings"

# Back to the default: remove the direct assignment
Grant-CsTeamsMeetingPolicy -Identity anna@contoso.com -PolicyName $null

Grant-CsTeamsMeetingPolicy (like the other common Grant-Cs* cmdlets) has three parameter sets: user, group and global. The syntax in MicrosoftTeams 8.0.0, read offline:

Import-Module MicrosoftTeams
(Get-Command Grant-CsTeamsMeetingPolicy).ParameterSets |
  ForEach-Object { '{0}: {1}' -f $_.Name, (($_.Parameters | Where-Object { $_.Name -in 'Identity','Group','Global','PolicyName','Rank' }).Name -join ', ') }

GrantToTenant: Global, PolicyName
GrantToGroup: PolicyName, Group, Rank
Identity: PolicyName, Identity

Which policy wins

A user has at most one effective policy per policy type. A policy assigned directly to the user wins over one inherited from a group; among groups, the assignment with the highest ranking wins (rank 1 is the highest); if neither exists the Global (org-wide default) policy applies. Check what a user ends up with:

Get-CsUserPolicyAssignment -Identity anna@contoso.com -PolicyType TeamsMeetingPolicy

Many users at once

New-CsBatchPolicyAssignmentOperation assigns one policy to up to 5,000 users per batch (object IDs or SIP addresses) and runs in the background:

$users = Get-Content .\users.txt        # one SIP address or object ID per line
New-CsBatchPolicyAssignmentOperation -PolicyType TeamsMeetingPolicy -PolicyName "Restricted Meetings" `
  -Identity $users -OperationName "Restricted meetings for contractors"

Get-CsBatchPolicyAssignmentOperation    # status of the batches

Pass -PolicyName $null to remove the policy from the batch of users.

Group assignment with New-CsGroupPolicyAssignment

New-CsGroupPolicyAssignment -GroupId sales@contoso.com -PolicyType TeamsMeetingPolicy -PolicyName "Restricted Meetings" -Rank 1
Get-CsGroupPolicyAssignment -PolicyType TeamsMeetingPolicy

This is equivalent to Grant-CsTeamsMeetingPolicy -Group. Group assignments apply to members added later as well.

When to use which method

The same pattern for other policy types

Each Teams policy type has its own Grant-Cs cmdlet with the same user, group and global parameter sets. A few common ones, checked in MicrosoftTeams 8.0.0:

Import-Module MicrosoftTeams
'Grant-CsTeamsMessagingPolicy', 'Grant-CsTeamsCallingPolicy', 'Grant-CsTeamsAppSetupPolicy',
'Grant-CsTeamsAppPermissionPolicy', 'Grant-CsTeamsChannelsPolicy', 'Grant-CsTeamsUpgradePolicy' |
  ForEach-Object { '{0}: {1}' -f $_, [bool](Get-Command $_ -ErrorAction SilentlyContinue) }

Grant-CsTeamsMessagingPolicy: True
Grant-CsTeamsCallingPolicy: True
Grant-CsTeamsAppSetupPolicy: True
Grant-CsTeamsAppPermissionPolicy: True
Grant-CsTeamsChannelsPolicy: True
Grant-CsTeamsUpgradePolicy: True

The -PolicyType values of New-CsBatchPolicyAssignmentOperation and Get-CsUserPolicyAssignment use the type name without the Grant-Cs prefix, for example TeamsMessagingPolicy. Messaging policies are covered on Set-CsTeamsMessagingPolicy.

Pitfalls

• No connection. Without Connect-MicrosoftTeams every Grant-Cs cmdlet fails with Session is not established.
• Direct assignment hides the group policy. If a user keeps the wrong settings after a group assignment, look for a direct assignment and remove it with -PolicyName $null.
• Changing the Global policy. -Global affects every user without a direct or group assignment, so try the policy on a pilot group first.

FAQ