Kamailio as SBC for MS Teams

Kamailio as session border controller for Microsoft Teams

Update September 2020

At this year Kamailio World Online conference I gave a more general talk about using Kamailio as SBC for Microsoft teams. You can find the blog post with the presentation and video recording here.

About Microsoft Teams

Microsoft Teams is a unified communication and collaboration platform that combines persistent workplace chat [and] video meetings [..]. The service integrates with the company's Office 365 [..] suite and features extensions that can integrate with non-Microsoft products. Microsoft Teams is a competitor to services such as Slack and is the evolution and upgrade path from Microsoft Skype for Business. From wikipedia.

Using Kamailio to connect your existing infrastruture

Many companies have already existing PBX infrastructure and/or existing telephone trunks. The Open Source SIP server Kamailio allows you to connect easily and efficiently your telephone infrastructure with the Microsoft Cloud telephony infrastructure.

This way you can provide interoperability between your existing phone infrastructure and continue to use your existing PSTN connection for outside calls. You can configure call-forwardings, use existing PBXs for routing or announcements and many more..

Necessary requirements

Microsoft provides an extensive documentation about how to plan, setup and troubleshoot direct routing link. So this article describes only the Kamailio parts of the implementation in detail.

Necessary knowledge

The setup of this infrastructure requires a good knowledge of Kamailio and also the relevant SIP standards. If you are looking for an easier approach, you'll find a link to our product offerings at the bottom of this page.

SBC domain, DNS and certificate

You need to use a proper domain for your tenant, the default "onmicrosoft.com" domain is not supported. Choose a dedicated DNS name for the new SBC, e.g. sbc.domain.com. Don't use sip or other reserved domain names.

In my tests I will setup a new SBC for my network dc-sbc.skalatan.de. It will be called SBC-DNS-DOMAIN in this article to allow easy adaption. The public IP address of this SBC is called SBC-IP-ADDR.

Your SBC obviously needs a public IP, configure your DNS that the new domain points to this IP with forward- and reverse-lookup.

The Microsoft Teams infrastructure encrypts all the SIP traffic with TLS. Therefore you need a TLS certificate for the Kamailio SBC. Officially only commercial TLS certificates are supported, but LetsEncrypt certificates also worked in my tests.

Ensure that you configure the TLS inside Kamailio correctly to also provide the necessary certificate authority information. Otherwise the TLS connection will not work in one or both ways and Microsoft can't use the SBC.

Add the SBC to MS Teams

Before you add the new SBC with PowerShell to MS Teams make sure that the DNS names can be lookup from the outside internet.

Get the proper credentials in PowerShell:

PS> $userCredential = Get-Credential
PS> $sfbSession = New-CsOnlineSession -Credential $userCredential
PS> Import-PSSession $sfbSession

Then add the SBC to the Direct Routing:

New-CsOnlinePSTNGateway -Fqdn SBC-DNS-DOMAIN -SipSignallingPort 5061 -MaxConcurrentSessions 10 -ForwardCallHistory $true -Enabled $true

Identity                           : SBC-DNS-DOMAIN
InboundTeamsNumberTranslationRules : {}
InboundPstnNumberTranslationRules  : {}
OutbundTeamsNumberTranslationRules : {}
OutboundPstnNumberTranslationRules : {}
Fqdn                               : SBC-DNS-DOMAIN
SipSignallingPort                  : 5061
FailoverTimeSeconds                : 10
ForwardCallHistory                 : True
ForwardPai                         : False
SendSipOptions                     : True
MaxConcurrentSessions              : 10
Enabled                            : True
MediaBypass                        : False
GatewaySiteId                      :
GatewaySiteLbrEnabled              : False
FailoverResponseCodes              : 408,503,504
GenerateRingingWhileLocatingUser   : True
PidfLoSupported                    : False
MediaRelayRoutingLocationOverride  :
ProxySbc                           :
BypassMode                         : None

You should now be able to see the Kamailio SBC in the MS Teams overview page. Of course it shows still a failed status as we did not configured it yet.

TLS configuration

As already mentioned, we need to setup TLS in Kamailio to properly interact with the MS infrastructure. Enable TLS in the Kamailio default configuration can be easily done with the existing #!define. Example tls.cfg:

[server:default]
method = TLSv1.2+
verify_certificate = yes
require_certificate = yes
private_key = /etc/kamailio/kamailio.key
certificate = /etc/kamailio/kamailio.pem
ca_list = /etc/kamailio/ca_list.pem

[client:default]
method = TLSv1.2+
verify_certificate = yes
require_certificate = yes
private_key = /etc/kamailio/kamailio.key
certificate = /etc/kamailio/kamailio.pem
ca_list = /etc/kamailio/ca_list.pem

Verify e.g. with openssl or with a soft phone that the TLS is working correctly.

SBC detection and keep-alive

MS detect if the SBC is working in two ways:

1. MS probes periodically the SBC with SIP OPTIONS requests, and
2. the SBC probes periodically the MS infrastructure with SIP OPTIONS request

So we need to setup Kamailio to support this. If you use the default kamailio.cfg then Kamailio should already be replying to SIP OPTIONS with a status 200 - "Keepalive" reply. So the first part is already solved.

For the second part we will use the dispatcher module, which provides everything what we need. First enable it in the Kamailio configuration:

loadmodule "dispatcher.so"
modparam("dispatcher", "list_file", "/etc/kamailio/dispatcher.list")
modparam("dispatcher", "ds_probing_mode", 1)
modparam("dispatcher", "ds_ping_interval", 60)

And then provide a dispatcher.list file:

# setid(integer) destination(sip uri) flags (integer, optional), priority(int,opt), attrs (str,optional)
1 sip:sip.pstnhub.microsoft.com;transport=tls 0 3 socket=tls:SBC-IP-ADDR:5061;ping_from=sip:SBC-DNS-DOMAIN
1 sip:sip2.pstnhub.microsoft.com;transport=tls 0 2 socket=tls:SBC-IP-ADDR:5061;ping_from=sip:SBC-DNS-DOMAIN
1 sip:sip3.pstnhub.microsoft.com;transport=tls 0 1 socket=tls:SBC-IP-ADDR:5061;ping_from=sip:SBC-DNS-DOMAIN

Teams expect an optional Contact header in the SIP request, otherwise it will not accept it. This can be easily done with a special route in kamailio.cfg:

event_route[tm:local-request] {

        if(is_method("OPTIONS") && $ru =~ "pstnhub.microsoft.com") {
               append_hf("Contact: <sip:dc-sbc.skalatan.de:5061;transport=tls>\r\n");
        }
        xlog("L_INFO", "Sent out tm request: $mb\n");
}

You need to adapt the cfg if this event route already exists in your Kamailio installation.

Verify e.g. with kamcmd dispatcher.list that the ping works correctly.

# kamcmd dispatcher.list | egrep "URI|FLAGS"
                                        URI: sip:sip.pstnhub.microsoft.com;transport=tls
                                        FLAGS: AP
                                        URI: sip:sip2.pstnhub.microsoft.com;transport=tls
                                        FLAGS: AP
                                        URI: sip:sip3.pstnhub.microsoft.com;transport=tls
                                        FLAGS: AP

If the probing works correctly in both ways then the SBC should be listed as enabled in the MS Teams Admin overview (TLS active, OPTIONS active):

Outgoing and incoming calls

In order to properly route outgoing and incoming calls over the MS infrastructure you need to complete two last steps.

First it necessary set the correct Record-Route header in Kamailio. This is used from Teams as authenticiation mechanism. Change in your configuration the existing record_route() function call to this one:

record_route_preset("SBC-DNS-DOMAIN:5061;transport=tls", "SBC-IP-ADDR:5060");

It might be necessary to change the Record-Route functionality depending on your network setup, e.g. only activate this logic for certain routing path.

Then you need to configure a voice routing policy in MS Teams and assign it to your user(s). More information about this can be found in the extensive Microsoft documentation.

Now incoming and outgoing calls should be working, e.g. with a soft phone:

And you should see some statistics in the MS Teams Admin overwiew:

Depending on your soft phone you can also see the traffic from your Kamailio to it:

Remarks

Now you can use all the existing possibilities that Kamailio provide to interact with MS Teams as well!

Extend the MS Teams systems with the features that Kamailio provides, especially for SIP trunking, interconnecting with VoIP providers or connecting external SIP endpoints.

If you need redundancy in your setup, you can add two Kamailio SBCs to MS Teams. You can e.g. balance your calls between both by adapting the MS voice routing policy. The same way different regions or PSTN routing destinations could be supported.

It is also possible to support multiple tenants or different customers on one Kamailio server, with different subdomains.

We offer now a MS Teams Direct Connect compatible SBC - more information here