Routes: MS Teams

AG Projects RTC Platforms (Routing Guides)

MS TEAMS integration

This guide describes SIP Thor plaform integration with MS Teams.

MS Teams integration provides routing, numbering, provisioning and accounting for multiple MS Teams tenants using SIP Thor platform as an outgoing and incoming PSTN carrier.

Both postpaid and prepaid accounting can be used for users of MS Teams domains.

Scalability is horizontal, depending on the numbers of servers available.

The integration makes use of Microsoft Direct routing method.

Operator requirements

• Schedule a platform upgrade with AG Projects
• Obtain a wildcard TLS certificate for domain *.msteams.sipthor.domain together with the alternative name msteams.sipthor.domain
• Enable sRTP encryption in PSTN gateways used by the operator
• Provide at least two new servers (can be virtual machines)

Features

Setup

Interconnection with Microsoft requires an Internet domain allocated for the SIP servers, which are further referred as Session Border Controller (SBC) for the operator and each tenant.

For this domain, a TLS wildcard certificate issued by a Certificate Authority recognized by Microsoft is needed.

This domain is further referred as MSTEAMS_SERVER_FQDN.

On SIP Thor platform MSTEAMS_SERVER_FQDN is automatically managed in DNS as msteams.sipthor.domain

MS Teams operator

The operator needs to setup this up once.

• Purchase an Office 365 license with Enterprise voice support from Microsoft (like E5)
• Register msteams.sipthor.domain with Microsoft
• Add msteams.sipthor.domain as an operator SBC
• Validate operator SBC using DNS, see DNS validation section bellow
• Add at least one user with Enterprise voice support

MS Teams tenant

The operator and tenant must set this up for each tenant.

Each tenant requires a hostname for the SBC under the domain msteams.sipthor.domain.

Example: sbc1.msteams.sipthor.domain.

Replace sbc1 with another DNS compatible hostname for each new tenant.

• Purchase an Office 365 license with Enterprise voice support from Microsoft
• Add sbc1.msteams.sipthor.domain as a Tenant SBC
• Validate Tenant SBC using DNS, see DNS validation section bellow
• Register a domain for use with MS Teams (e.g. customer1.com), must not be the same as the Tenant SBC address
• Add users with Enterprise voice support

PSTN gateway

• Enable sRTP media encryption

SIP Thor

• Configure the SIP Proxy nodes running msteams_gateway role with the TLS certificate for msteams.sipthor.domain
• Add DNS records for msteams_gateway role, see DNS setup section bellow
• Set msteams_gateway role in the SIP Thor node configuration
• IP addresses of MS Teams SIP gateways must be added as trusted peers
• Configure secondary MS Teams ENUM TLD in each SIP Proxy node

define(`ENUM_PRIVATE_TREE2', `msteams.c164.net')

• Enable MSTEAMS in /etc/opensips/config/settings.m4 for each SIP Proxy node running msteams_gateway role:

define(`ENABLE_MSTEAMS', `1')

• Configure msteams_gateway role in /etc/sipthor/config.ini for designated SIP Thor nodes:

[ThorNode]
;roles = sip_proxy
roles = msteams_gateway

msteams_gateway and sip_proxy roles are mutually exclusive, no server can run both roles.

The default SIP port seen by Microsoft is 5161, this can be changed using MSTEAMS_TLS_PORT setting of the SIP proxy. This port must be different than other ports already in use by the SIP Proxy server.

define(`MSTEAMS_TLS_PORT', `5161')

DNS setup

Replace sipthor.domain with your own SIP Thor platform domain.

_msteams-gateway._tcp.sipthor.domain  SRV 0 5161 msteams.sipthor.domain.
              msteams.sipthor.domain. NS            dns1.sipthor.domain.
              msteams.sipthor.domain. NS            dns2.sipthor.domain.
              msteams.sipthor.domain. NS            dns3.sipthor.domain.

Replace dns1.sipthor.domain, dns2.sipthor.domain and dns3.sipthor.domain with all the hostnames of SIP Thor nodes running DNS manager role.

Once these DNS records are added, the hostnames corresponding to the Operator and Tenant SBCs will automatically appear in the DNS.

DNS validation

Each Operator and Tenant SBC must be verified by Microsoft. Microsoft provides an authorization token that must be published by the operator DNS using a TXT record in the form "MS=ms123456789" that corresponds to each SBC.

Add the authorization token in the trusted peer table. The authorization token must correspond to each SBC address. The address of the SBC is computed by concatenating the Tenant field of the trusted peer with MSTEAMS_SERVER_FQDN.

Operator SBC address is msteams.sipthor.domain

Tenant SBC address is tenant.msteams.sipthor.domain where tenant is the string specified in the trusted table for each MS Teams domain, for example sbc1.

You can verify the use of the authorization token by performing the following DNS queries.

For Operator SBC:

dig TXT msteams.sipthor.domain

For Tenant SBC:

dig TXT sbcX.msteams.sipthor.domain

The DNS response must contain the authorization token set above.

Once the answer is correct, proceed further with Microsoft validation.

Once the validation is completed, the authentication token must be removed from the the trusted peer table in order for the peer to be activated inside SIP Thor platform. Once removed, in about two minutes the SBC becomes active in the DNS.

To verify that the SBC is reachable, perform this DNS query:

dig sbcX.msteams.sipthor.domain

The DNS response will contain a random list with IP addresses of the SIP Thor nodes running msteams_gateway role at the moment of the query.

Provisioning

Create a new Customer entry for one or more MS Teams domains.

Add each MS Teams domain as a trusted peer and use the id of the Customer created above to identify its owner.

Specify the Tenant SBC. If Tenant SBC is not specified, the default operator SBC msteams.sipthor.domain will be used.

See Provisioning: Trusted Peers chapter for how to manage Trusted peers.

Add ENUM entries for mapping E.164 telephone numbers to MS Teams users in the secondary ENUM TLD.

See Provisioning: ENUM chapter for how to map telephone numbers to SIP addresses.

Optionally, Tenant SBC can also be added to the ENUM mapping fo each MS Teams user.

Example:

• ENUM number: +31237XXXX17
• SIP mapping: sip:ms1@sipthor.onmicrosoft.com;tenant=sbc1
• Trusted peer: sipthor.onmicrosoft.com

The above ENUM mapping routes incoming calls for +31237XXXX17 to trusted peer sipthor.onmicrosoft.com using sbc1.msteams.sipthor.domain Tenant SBC.

tenant=sbc1 overwrites the Tenant SBC setting of the trusted peer. Do not use this flag unless you need to perform specifics routing tests as it is not needed.

sipthor.onmicrosoft.com is a MS Teams domain that must be added as trusted peer.

sbc1.msteams.sipthor.domain is a hostname that must be registered as an SBC inside MS Teams tenant.

Outgoing calls to PSTN

Users belonging to MS Teams domains configured as trusted peers are allowed to place outgoing PSTN calls.

Least Cost Routing engine will select the outbound PSTN carrier for each tenant based on the customer id of the MS Teams domain.

Incoming calls from PSTN

If the domain part of the result of the ENUM query for a phone number contains a domain added as a MS Teams trusted peer, the call will be routed to SIP Thor nodes configured for msteams_gateway role.

Scalability

Scalability is horizontal with the amount of servers available.

Multiple SIP Proxy servers can join in real time SIP Thor network with the role msteams_gateway. All servers advertising this role are automatically detected by Microsoft as being alive and are used for both incoming and outgoing calls in load sharing mode.

Rating

To rate the traffic generated by MS Teams users, you must add a rating plan in CDRTool rating engine for MS Teams domain field in the rating customers table.

The calls to MS Teams users can be free of charge or can have costs rated based on the telephone number mapped in ENUM for each user.

Rating can be prepaid or postpaid. To enable prepaid, set the prepaid flag for the MS Teams domain in the trusted peer table and add a balance for each MS Teams user under that domain.

See Rating: Assignment

Numbering plan

To avoid adding specific rewriting rules that require the restart of the SIP Proxy, configure MS Teams tenant to send the numbers formatted in E.164 format or starting with 00. If properly configured, local numbers starting with one 0 may also work.

E.164 format: [+][country code][area code][local phone number]

Troubleshooting

The status of the operator SBC can be found inside each MS Teams tenant interface on Microsoft web sites.

While running, all SIP Proxies configured with msteams_gateway role inside SIP Thor network are sending SIP OPTIONS to Microsoft SIP servers at 60 seconds interval, which enables them for routing calls from MS Teams domains to PSTN numbers.

You should see the following logs lines:

MS Teams keep alive probe msteams.sipthor.domain:5161 -> sip:sip.pstnhub.microsoft.com
MS Teams keep alive probe msteams.sipthor.domain:5161 -> sip:sip2.pstnhub.microsoft.com
MS Teams keep alive probe msteams.sipthor.domain:5161 -> sip:sip3.pstnhub.microsoft.com
200 OK for MS Teams keep alive from 52.114.132.46:5061 (5b4f44980da92ef6-4474@81.23.228.190)
200 OK for MS Teams keep alive from 52.114.76.76:5061 (5b4f44980da92ef5-4474@81.23.228.190)
200 OK for MS Teams keep alive from 52.114.32.169:5061 (5b4f44980da92ef7-4474@81.23.228.190)

SIP Traces are available for each call in CDRTool interface.

When calls to MS Teams domains fail, Microsoft provides the reason which can be found in the SIP server logs:

Reply for INVITE (Vex8QHtvDs9m2dS5HU8UzI708Z-z.aX3): 488 Not Acceptable Here
INVITE failed with reason: Q.850;cause=79;InternalDiagCode: SrtpEncryptionRequired, InternalErrorPhrase: Remote participant did not offer required SRTP support" (Vex8QHtvDs9m2dS5HU8UzI708Z-z.aX3)

To find the log lines belonging to a given call, grep the system logs for the Call ID.

To verify that MS Teams authentication tokens and Tenant SBC addresses are published into the DNS, check the logs of thor-dns component for these lines:

thor-dns[16861]: adding MS Teams authentication token for sbc1.msteams.sipthor.domain: MS=ms12344555
thor-dns[16861]: adding MS Teams authentication token for sbc6.msteams.sipthor.domain: MS=ms12883449
thor-dns[16861]: adding MS Teams tenant sbc2.msteams.sipthor.domain
thor-dns[16861]: adding MS Teams tenant sbc4.msteams.sipthor.domain

In the example above, two tenant SBC are active (sbc2 and sbc4) and two are waiting for the authorization to be completed (sbc1 and sbc6).

Next Steps

Continue by:

• learning about Routes: End-Point; or
• learning about Routes: MSRP media; or
• learning about Routes: Presence; or
• learning about Routes: PSTN; or
• learning about Routes: Special; or
• going back to the Overview.