Guide to Integrating Asterisk with Microsoft Teams Using Direct Routing

Introduction

Love it or hate it, Microsoft Teams has become pretty popular. As more organizations adopt it as their primary collaboration tool, the need to integrate it with existing on-premise VoIP or PBX systems is growing fast. If you’re using Asterisk—a highly flexible, open-source PBX—you’re in luck. With the right configuration, Asterisk can integrate cleanly with Microsoft Teams using Direct Routing.

However, getting Asterisk to work with Microsoft Teams takes some careful setup. Teams has strict SIP and TLS requirements—most notably, it expects a Fully Qualified Domain Name (FQDN) in the Contact header of SIP messages. This guide walks you through building Asterisk 22.3.0 from source and applying a patch that adds the contact_fqdn option to meet those requirements.

Prefer an Easier Alternative? If you’re looking for a ready-to-use solution with built-in PBX capabilities and Microsoft Teams compatibility, check out the DMSBG-100. This all-in-one gateway simplifies deployment with features like WireGuard VPN, integrated firewall, and a user-friendly interface—no patching, no coding, and no monthly subscription fees. Every unit also includes free TLS certificates and managed DNS, so you’re ready to go right out of the box.

If you’re sticking with the DIY route, this guide will help you get things set up.

Prerequisites

Before starting the integration process, ensure you have the following in place:

A publicly accessible server. This could be a cloud-based virtual machine or an on-premise server with the necessary NAT and port forwarding rules configured.
A valid TLS certificate (e.g., from Let’s Encrypt or ZeroSSL) that includes a matching FQDN.
A working understanding of Asterisk configuration, SIP protocol, and basic networking concepts.

Building Asterisk with the Patch

This section outlines the steps to download the Asterisk source code, apply the necessary patch, and compile the software. This guide assumes you are using a Debian-based Linux distribution like Ubuntu.

Install Build Dependencies: Open your terminal and run the following command to install the required tools for building Asterisk:
```
sudo apt update && sudo apt install wget nano build-essential git
```
Clone Asterisk Source Code: Navigate to a directory where you want to download the Asterisk source and clone the repository for version 22.3.0:
```
git clone --branch 22.3.0 --depth 1 https://github.com/asterisk/asterisk.git
cd asterisk
```
Download and Apply the contact_fqdn Patch: Download the custom patch that adds the contact_fqdn option and apply it to your local Asterisk source code:
```
wget https://git.difuse.io/Difuse/telephony/raw/commit/2606056893ca1185fa4dbe8424d298adcebd5b59/net/asterisk/patches/999-contact_fqdn.patch -O contact_fqdn.patch
patch -p1 < contact_fqdn.patch
```
Successfully applying the patch should result in output similar to the following image:
Compile and Install Asterisk: Once the patch is applied, proceed with the Asterisk build process:
```
contrib/scripts/install_prereq install
./configure
make menuselect   # Optional: Use this to customize the modules you want to install
make -j$(nproc)
sudo make install
sudo ldconfig
```
The make menuselect command allows you to select or deselect specific Asterisk modules. This is optional but can be useful to reduce the installed footprint. The make -j$(nproc) command compiles Asterisk using all available processor cores, speeding up the process.
Install Basic PBX Configuration (Optional): For a basic starting configuration, you can run:
```
sudo make samples
sudo make config
```

Configuring TLS for Microsoft Teams

Microsoft Teams mandates the use of TLS 1.2 for all SIP connections. You need to configure a PJSIP TLS transport in Asterisk, ensuring it includes the crucial contact_fqdn parameter.

Edit pjsip.conf: Open the pjsip.conf file (usually located in /etc/asterisk/).
Define a Custom TLS Transport for Teams: Add the following section to define a new TLS transport specifically for Microsoft Teams:
```
[transport-tls-teams]
type = transport
protocol = tls
bind = 0.0.0.0:5061
cert_file = /etc/asterisk/keys/fullchain.pem
priv_key_file = /etc/asterisk/keys/privkey.pem
method = tlsv1_2
verify_client = no
allow_reload = yes
external_signaling_address = your.domain.com
external_media_address = your.domain.com
contact_fqdn = your.domain.com
```
Important: Replace your.domain.com with the publicly resolvable FQDN of your Asterisk server. This FQDN must match the Common Name (CN) or Subject Alternative Name (SANs) of your TLS certificate. Ensure that the certificate and private key file paths (cert_file and priv_key_file) are correct for your system.

Creating the Microsoft Teams SIP Trunk

Next, you need to define a SIP trunk within Asterisk that points to Microsoft’s Direct Routing infrastructure.

Edit pjsip.conf (continued): Add the following sections to define the AOR (Address of Record), Identify, and Endpoint for the Microsoft Teams trunk:

[Teams-aor]
type = aor
contact = sip:sip.pstnhub.microsoft.com:5061
qualify_frequency = 60


[Teams-identify]
type = identify
endpoint = Teams-endpoint
match = sip.pstnhub.microsoft.com
match = sip-all.pstnhub.microsoft.com


[Teams-endpoint]
type = endpoint
transport = transport-tls-teams
context = from-teams
disallow = all
allow = alaw,ulaw,g722
dtmf_mode = rfc4733
media_encryption = sdes
media_encryption_optimistic = no
direct_media = no
refer_blind_progress = no
aors = Teams-aor
from_domain = your.domain.com

Again, replace your.domain.com with your public domain name that resolves to your Asterisk server and is included in your TLS certificate. The context = from-teams line specifies the dialplan context where incoming calls from Microsoft Teams will be directed.

Configuring the Dialplan

You need to define how Asterisk handles both inbound calls originating from Microsoft Teams and outbound calls destined for Teams users or the PSTN via Teams Direct Routing.

Edit extensions.conf: Open your extensions.conf file (or the specific context file you are using).
Handle Inbound Calls from Teams: Add a context (as defined in the pjsip.conf endpoint configuration) to manage incoming calls. For example, in the [from-teams] context:
```
[from-teams]
exten => Teams,1,Hangup() ; Placeholder - consider removing or customizing
exten => h,1,Hangup() ; Hang up on call termination
exten => _.,1,NoOp(Incoming call from Teams to ${EXTEN})
 same => n,Answer()
 same => n,Playback(tt-monkeys) ; Replace with your desired inbound call logic
 same => n,Hangup()
```
The _.,1 pattern will match any incoming dialed number. You should replace the Playback(tt-monkeys) line with your actual call routing logic, such as directing the call to an internal extension or an IVR.
Configure Outbound Calls to Teams: Create a context for initiating outbound calls through the Teams trunk. For example:
```
[outbound-to-teams]
exten => _X.,1,NoOp(Placing outbound call to Teams: ${EXTEN})
 same => n,Dial(PJSIP/${EXTEN}@Teams-endpoint)
 same => n,Hangup()
```
The _X. pattern will match any dialed number. When a call matches this pattern, it will be dialed using the Teams-endpoint defined in pjsip.conf.

Important Considerations

Firewall Configuration: Ensure that your firewall allows traffic on the following ports:
- 5061 (TCP): For TLS-encrypted SIP signaling with Microsoft Teams.
- 10000–20000 (UDP): For RTP (Real-time Transport Protocol) media traffic. The specific RTP port range might vary depending on your Asterisk configuration.
Microsoft Direct Routing Compliance: Microsoft has specific requirements for Direct Routing configurations. It is crucial to thoroughly review and comply with their Direct Routing checklist to ensure proper functionality. You can use the SIP Tester Tool provided by Microsoft or monitor logs in the Teams admin center to diagnose any issues.
DNS Records: Verify that your DNS records (including A records for your server’s IP address and potentially SRV or NAPTR records if required by Microsoft in specific scenarios) are correctly configured and publicly resolvable. Incorrect DNS configuration can lead to connection failures with the Microsoft Teams infrastructure.

Configuring Teams

To complete the integration, you need to set things up on the Microsoft side. We’re going to assume you already added your domain to Microsoft and verified it. If you haven’t done that yet, please do so.

You can add the trunk the same way as you see above, once you do the TLS connectivity status and SIP Options status will become Active

Add a PSTN usage record with the ‘Manage PSTN usage records’ link in the top right of the ‘Direct Routing’ page. Give it a name and save. Then go to the ‘Voice Routes’ tab, add a new Voice Route with your own name and \d+ in the ‘Dialed number pattern’ field. Also add your SBC and PSTN usage record to the Voice Route and Save.

Now go to ‘Voice routing policies’ and edit the Global policy. Add your PSTN usage record there. You may also create a new policy. If you do that, you also need to assign that policy to a user.

We’re almost there, I promise. For the next step, we’re going to need a Windows machine (sorry).

Run the following commands

# Install the Teams module for PowerShell
Set-ExecutionPolicy unrestricted
Install-Module MicrosoftTeams

# Load the module into your environment
Import-Module -Name MicrosoftTeams

# Connect to Teams
Connect-MicrosoftTeams

After the last command you will get a popup, login as admin. If you get a tenant id back, you can proceed.

Set-CsUser -ID [email protected] -OnPremLineURI tel:+<phonenumber> -EnterpriseVoiceEnabled $true -HostedVoiceMail $true

That’s it! Your user will now have a dialpad. Log in to Teams and try to place a call. If something doesn’t work, check the Asterisk console.

Conclusion

Successfully integrating Asterisk with Microsoft Teams through Direct Routing gives you full control over your voice infrastructure while keeping Teams as the unified collaboration interface. While the process involves several steps—from building Asterisk with a custom patch to configuring SIP trunks and Teams policies—the flexibility and cost savings are well worth the effort.

If you encounter issues or have questions during the setup, feel free to reach out via email. We’re happy to help and would also love to tell you more about our hardware solutions if you’re considering a more streamlined alternative.

Blogs And Articles