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
| Requirement | Why | Where |
|---|---|---|
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 header | The trunk's From domain (from_domain) |
| A DNS A/AAAA record for that FQDN pointing at the MonoPbx SIP edge's public address | The Microsoft proxies connect to the SBC by name | Your 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 certificates | The 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 5061 | SIP over TLS only | Firewall |
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 relay | Firewall, NAT and TURN |
| A Microsoft 365 tenant with Teams Phone licences and the Teams admin (PowerShell) rights | Pairing the SBC and the voice routing | Microsoft 365 |
The trunk
The type sets Microsoft's requirements; validation (MPBX-TRUNK-INVALID, the field named)
refuses anything else:
| Field | Value on a Teams trunk |
|---|---|
host | A 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, port | tls, 5061 (empty) |
from_domain | The 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. |
srtp | required (SDES; Teams media is always encrypted) |
inbound_auth, inbound_cidrs | ip, 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_secs | 5 to 180 (default 60). Microsoft marks an SBC inactive when its OPTIONS stop, so the health check cannot be off. |
codecs | Among PCMU, PCMA, G722, G729, opus (default PCMU, PCMA, G722) |
outbound_proxy, registrar | Empty |
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
| Symptom | Check |
|---|---|
| SIP OPTIONS status "Warning" or "Inactive" in Teams | The 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 arrive | The source address is in inbound_cidrs; port 5061 inbound is open |
| One-way or no audio | SRTP 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 andX-MS-SBC, SRTP offer check; a B2BUA call over a Teams trunk with the FQDN Contact andX-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 withX-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 totls_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.