Skip to main content

Microsoft Teams Direct Routing

MonoPbx can be the Session Border Controller (SBC) a Microsoft 365 tenant pairs with Teams Direct Routing. Teams users then call the PSTN through the company's carriers on MonoPbx, and numbers routed to the Teams trunk ring Teams users. It is a trunk of kind teams_direct_routing (POST /api/v1/trunks with "kind": "teams_direct_routing", or Admin > Numbers and trunks > Trunks, type Microsoft Teams Direct Routing). Code: pbx/crates/trunks/src/teams.rs; the trunk model and API are the ones of SIP trunks.

Part 1 (this guide) covers the SBC signalling: TLS, the SBC FQDN, OPTIONS keepalive, X-MS-SBC, SRTP, media through the MonoPbx media relay. Media bypass, ICE-lite, presence sync and click-to-call from Teams are follow-ups ((planned)).

What you need​

RequirementWhyWhere
A public FQDN for the SBC, in a domain the Microsoft 365 tenant has verified (for example sbc.contoso.com; not *.onmicrosoft.com)Microsoft pairs the SBC by its FQDN and finds it in the Contact headerThe trunk's From domain (from_domain)
A DNS A/AAAA record for that FQDN pointing at the MonoPbx SIP edge's public addressThe Microsoft proxies connect to the SBC by nameYour DNS
A TLS certificate for the FQDN from a CA Microsoft trusts (public CA, SHA-256, the FQDN in the SAN; a wildcard of the domain is accepted)Microsoft refuses self-signed or private-CA certificatesThe SIP edge's TLS listener, see certificates
Port 5061/TCP open inbound from Microsoft's signalling ranges and the SBC able to reach the Microsoft proxies on 5061SIP over TLS onlyFirewall
Media ports of the media relay open to Microsoft's media ranges (52.112.0.0/14, 52.122.0.0/15, UDP 3478-3481 and 49152-53247)Media bypass is off: media flows between the Microsoft media processors and the MonoPbx relayFirewall, NAT and TURN
A Microsoft 365 tenant with Teams Phone licences and the Teams admin (PowerShell) rightsPairing the SBC and the voice routingMicrosoft 365

The trunk​

The type sets Microsoft's requirements; validation (MPBX-TRUNK-INVALID, the field named) refuses anything else:

FieldValue on a Teams trunk
hostA Microsoft SIP proxy: sip.pstnhub.microsoft.com (also sip2., sip3.; sip.pstnhub.gov.teams.microsoft.us and sip.pstnhub.dod.teams.microsoft.us for GCC High and DoD). Create one trunk per proxy for failover, or one trunk and let DNS fail over.
transport, porttls, 5061 (empty)
from_domainThe SBC FQDN (a DNS name with at least three labels, never an IP address or a Microsoft domain). It is the host of the From and of the Contact (<sip:…@FQDN:5061;transport=tls>) on every INVITE and OPTIONS.
srtprequired (SDES; Teams media is always encrypted)
inbound_auth, inbound_cidrsip, Microsoft's signalling ranges as /16 prefixes: 52.112.0.0/16 … 52.115.0.0/16, 52.122.0.0/16, 52.123.0.0/16 (filled in when the type is chosen). Microsoft does not answer digest challenges; no username or password on the trunk.
options_interval_secs5 to 180 (default 60). Microsoft marks an SBC inactive when its OPTIONS stop, so the health check cannot be off.
codecsAmong PCMU, PCMA, G722, G729, opus (default PCMU, PCMA, G722)
outbound_proxy, registrarEmpty

Every OPTIONS and INVITE to Microsoft carries X-MS-SBC: MonoPbx/SBC/<version>. The X-MS-* headers Microsoft puts on calls from Teams are read by the SBC only and never forwarded to another leg. The database keeps the rules too (trunks_teams_direct_routing_check: TLS, SRTP required, an SBC FQDN, IP inbound authentication).

Calls in from Teams are admitted like any trunk call (source address on the allow-list, the DID read from the Request-URI) and routed by the company's dial plan; calls to Teams numbers are an outbound route of the dial plan to the Teams trunk. A Teams trunk belongs to one company, like every trunk.

Pairing in Microsoft 365 (Teams PowerShell)​

Connect-MicrosoftTeams
New-CsOnlinePSTNGateway -Fqdn sbc.contoso.com -SipSignalingPort 5061 -MaxConcurrentSessions 50 -Enabled $true -MediaBypass $false
Set-CsPhoneNumberAssignment -Identity user@contoso.com -PhoneNumber +525550000101 -PhoneNumberType DirectRouting
New-CsOnlinePstnUsage -Identity Global -Usage @{Add="MonoPbx"}
New-CsOnlineVoiceRoute -Identity "MonoPbx" -NumberPattern ".*" -OnlinePstnGatewayList sbc.contoso.com -OnlinePstnUsages "MonoPbx"
New-CsOnlineVoiceRoutingPolicy "MonoPbx" -OnlinePstnUsages "MonoPbx"
Grant-CsOnlineVoiceRoutingPolicy -Identity user@contoso.com -PolicyName "MonoPbx"

After pairing, the Teams admin center shows the SBC with TLS connectivity status: Active and SIP OPTIONS status: Active within a few minutes once MonoPbx's OPTIONS reach Microsoft; in MonoPbx the trunk status turns healthy when Microsoft answers them.

Troubleshooting​

SymptomCheck
SIP OPTIONS status "Warning" or "Inactive" in TeamsThe trunk is enabled, its health check is on, and the From domain is the paired FQDN; port 5061 outbound is open
TLS connectivity "Inactive"The certificate covers the FQDN, is from a public CA and its chain is complete; the DNS record points at the edge
Calls from Teams are refused 403 or never arriveThe source address is in inbound_cidrs; port 5061 inbound is open
One-way or no audioSRTP is required; media ranges open; see audio quality

Testing​

  • Unit and validation tests: cargo nextest run -p mpbx-trunks -p mpbx-b2bua -E 'test(teams)' (kind presets and validation, OPTIONS keepalive with FQDN Contact and X-MS-SBC, SRTP offer check; a B2BUA call over a Teams trunk with the FQDN Contact and X-MS-SBC).
  • SIPp plays the Microsoft proxy over TLS in Docker: make teams-sipp (pbx/crates/trunks/sipp/run-teams.sh: OPTIONS keepalive, an INVITE with X-MS-* headers and SRTP answered with SRTP, ACK, BYE, and a plain-RTP INVITE refused 488). SIPp 3.7.3's own TLS client fails its handshake, so SIPp speaks TCP to tls_bridge.py, which opens a TLS connection per SIPp connection to the SBC and verifies its certificate against the test CA for the SBC FQDN, as Microsoft does.
  • A run against a real Microsoft 365 developer tenant is an owner task.