How to Configure Teams Media Connectivity Policies in PowerShell Using CsTeamsMediaConnectivityPolicy

In enterprise network environments, audio and video quality in Microsoft Teams depends directly on real-time media routing paths. When two employees in the same corporate office establish a 1:1 voice or video call, Microsoft Teams attempts to establish direct Peer-to-Peer (P2P) media connectivity across the local area network using the Interactive Connectivity Establishment (ICE) protocol. Bypassing cloud media relays reduces round-trip audio latency and saves WAN internet bandwidth.

However, in high-security environments, financial institutions, and multi-tenant hosting environments, direct P2P connections pose security and compliance concerns. Direct P2P media connections expose user IP addresses, bypass corporate Session Border Controllers (SBCs), and evade network-level deep packet inspection (DPI) firewalls. To govern whether endpoints are permitted to establish direct P2P media connections or must route all audio/video streams through cloud TURN relays and enterprise Session Border Controllers, Microsoft Teams administrators configure Teams Media Connectivity Policies via the CsTeamsMediaConnectivityPolicy cmdlet family. This guide explains how Teams media routing and candidate filtering operate and details how to manage media connectivity policies using PowerShell.

Architecture of Teams Media Connectivity and Candidate Filtering

During call setup, Microsoft Teams endpoints negotiate media routing using Session Description Protocol (SDP) and Interactive Connectivity Establishment (ICE) techniques (RFC 5245):

• Host Candidates (Local P2P): Endpoints advertise their local private network IP addresses. If both clients reside on the same LAN subnet or routed corporate intranet, media packets stream directly between endpoints over UDP ports 50000–50019, bypassing cloud relays entirely.
• Server Reflexive Candidates (STUN): Endpoints discover their public IP address via Session Traversal Utilities for NAT (STUN) servers, attempting direct peer-to-peer connections across external firewalls.
• Relay Candidates (TURN): When corporate firewalls block direct UDP connectivity, or when administrative policy forbids direct P2P streaming, endpoints route audio and video through Microsoft 365 cloud media relays (TURN servers) over port 3478 UDP or 443 TCP.
• CsTeamsMediaConnectivityPolicy Control: Dictates whether direct P2P candidate gathering is permitted (Direct) or strictly suppressed (RelayOnly). Forcing relay routing hides user IP addresses and forces media across inspected corporate boundary routers.

Configuring media connectivity policies via PowerShell guarantees that remote branch offices and executive user cohorts adhere to enterprise perimeter security baselines.

Prerequisites and PowerShell Module Connection

Configuring Teams media connectivity policies requires Microsoft Teams PowerShell module version 4.9.0 or later and an account assigned the Teams Administrator or Global Administrator role in Microsoft Entra ID.

Open an elevated PowerShell prompt and check your module version:

Get-Module -ListAvailable -Name MicrosoftTeams

If required, install or update the module from the PowerShell Gallery:

Install-Module -Name MicrosoftTeams -Force -AllowClobber -Scope CurrentUser

Connect to your Microsoft Teams tenant:

Connect-MicrosoftTeams

Confirm your active administrative connection:

Get-CsTenant | Select-Object DisplayName, TenantId

Inspecting Current Media Connectivity Policies

To inspect your tenant’s active media connectivity policies, run Get-CsTeamsMediaConnectivityPolicy:

Get-CsTeamsMediaConnectivityPolicy

PowerShell outputs configured policy definitions:

Identity             : Global
Description          : Default tenant-wide media connectivity configuration
DirectMediaAllowed   : True
IceCandidateFiltering: Standard

Identity             : Tag:HighSecurity-RelayOnly
Description          : Forces all media streams through cloud TURN relays to prevent IP exposure
DirectMediaAllowed   : False
IceCandidateFiltering: RelayOnly

To inspect a single policy in detailed list format, pass the -Identity parameter:

Get-CsTeamsMediaConnectivityPolicy -Identity "Global" | Format-List

Creating Custom Scoped Media Connectivity Policies

Best practice in zero-trust enterprise security dictates leaving the default Global policy optimized for standard corporate offices (permitting direct media on internal networks) while creating dedicated restricted policies for remote contractors, VIP executives, or sensitive branch offices.

To create a high-security policy that forces all voice and video calls through cloud media relays, execute New-CsTeamsMediaConnectivityPolicy:

New-CsTeamsMediaConnectivityPolicy `
    -Identity "Strict-RelayOnly-Policy" `
    -Description "Prevents direct peer-to-peer IP exposure by routing all media through cloud TURN relays" `
    -DirectMediaAllowed $false

To create a high-performance policy optimized for corporate campus branches with high-speed 10 Gbps LAN infrastructure:

New-CsTeamsMediaConnectivityPolicy `
    -Identity "Campus-DirectMedia-Policy" `
    -Description "Enables direct peer-to-peer media streaming for low-latency campus calls" `
    -DirectMediaAllowed $true

Modifying Existing Policy Settings

If security requirements or network infrastructure change—such as when re-architecting corporate VPN tunnels or deploying regional cloud relays—update policy instances using Set-CsTeamsMediaConnectivityPolicy:

# Force cloud relay routing on the Global tenant policy
Set-CsTeamsMediaConnectivityPolicy -Identity "Global" -DirectMediaAllowed $false

Conversely, to permit direct P2P media across campus environments:

Set-CsTeamsMediaConnectivityPolicy -Identity "Campus-DirectMedia-Policy" -DirectMediaAllowed $true

Assigning Media Connectivity Policies to Users and Security Groups

Once defined, assign media connectivity policies to licensed users using Grant-CsTeamsMediaConnectivityPolicy.

Assigning Policy to an Individual User

To assign the high-security relay policy to a specific user via their User Principal Name (UPN):

Grant-CsTeamsMediaConnectivityPolicy `
    -Identity "[email protected]" `
    -PolicyName "Strict-RelayOnly-Policy"

To remove a direct user-level assignment and return the account to the tenant-wide Global policy default, pass $null:

Grant-CsTeamsMediaConnectivityPolicy `
    -Identity "[email protected]" `
    -PolicyName $null

Automating Assignments via Entra ID Security Groups

In large multinational organizations, assign policies dynamically based on department or location security groups using New-CsGroupPolicyAssignment:

# Retrieve the Object ID of the target Entra ID security group
$groupId = (Get-MgGroup -Filter "DisplayName eq 'Finance and Executive Tier'").Id

# Assign the media policy to the security group
New-CsGroupPolicyAssignment `
    -GroupId $groupId `
    -PolicyType TeamsMediaConnectivityPolicy `
    -PolicyName "Strict-RelayOnly-Policy" `
    -Rank 1

Group-based policy assignments automatically apply the media policy to newly onboarded executives, ensuring consistent network isolation without manual administrative intervention.

Verifying User Policy Assignments and Call Quality Telemetry

After granting a media connectivity policy, confirm that the assignment is successfully reflected on the user’s online directory record:

Get-CsOnlineUser -Identity "[email protected]" | Select-Object DisplayName, UserPrincipalName, TeamsMediaConnectivityPolicy | Format-List

Expected output confirms the policy association:

DisplayName                  : Alex Turner
UserPrincipalName            : [email protected]
TeamsMediaConnectivityPolicy : Strict-RelayOnly-Policy

To verify that active calls adhere to the policy, administrators can inspect call records in the Microsoft Teams Call Analytics / Call Quality Dashboard (CQD). Look under Connectivity Type: calls made by users under the Strict-RelayOnly-Policy will report Relay (TURN) for both endpoints with zero direct peer-to-peer IP exposure, confirming complete network perimeter enforcement.