add teams-direct-routing.rst (#138)

* Create teams-direct-routing.rst

en/best-practices/teams-direct-routing.rst

@@ -0,0 +1,129 @@
+
+.. :maxdepth: 2
+
+=======================
+MS Teams direct routing
+=======================
+
+.. _ms_teams:
+
+Yeti-Switch able to act as SBC for MS Teams direct routing. This document explains how to configure MS teams interconnection for domain **subdomain.teams.example.com**
+
+
+Prerequisites
+=============
+
+This part out of scope of this document. You have to complete next steps yourself:
+
+#. Read MS Teams documentation https://learn.microsoft.com/en-us/microsoftteams/direct-routing-plan
+
+#. Yeti Load balancer should be installed and properly configured:
+
+    * Domain name for SBC address required. Domain name **A record** should point to Yeti load balancer IP address. **SRV** records not supported by MS Teams.
+
+    * Valid TLS certificate should be installed on Yeti load balancer. If you planning to using multitenacy on MS Teams side(multiple MS Teams accounts connected to same Yeti-Switch system) you have to use wildcard certificate. See https://learn.microsoft.com/en-us/microsoftteams/direct-routing-plan#public-trusted-certificate-for-the-sbc for details.
+
+
+#. Validate SBC domain name on Teams side using DNS TXT record according to MS Teams documentation.
+#. Create SBC on MS Teams side according to MS Teams documentation.
+#. Assign proper licenses and users according to MS Teams documentation.
+
+
+SIP OPTIONS requests
+====================
+
+MS Teams require SBC to send SIP OPTIONS requests. MS Teams using these SIP OPTIONS requests to validate trunk status and without proper configuration there your trunk will not became active on MS Teams side.
+
+To configure Yeti to send OPTIONS requests you have to create :ref:`SIP Options Prober <sip_options_probers>`. Important configuration parameters:
+
+Transport Protocol
+    Should be **TLS**
+
+Ruri Domain
+    Should be **sip.pstnhub.microsoft.com**. See https://learn.microsoft.com/en-us/microsoftteams/direct-routing-plan#infrastructure-requirements for details
+
+Proxy
+    Should be **sip:subdomain.teams.example.com**
+
+Proxy Transport Protocol
+    Should be **TLS**
+
+Contact Uri
+    Should be **sip:subdomain.teams.example.com**
+
+.. warning::
+    After completion of this step you have to check MS Teams response in Realtime Data -> SIP Option Probers. **last_reply_code** and **last_reply_reason** should be **200 OK**. On Teams side trunk also should became active with good status. Sometimes you have to wait few hours until SBC will be provisioned on MS Teams side.
+
+    Once trunk status is OK on both sides you can proceed with Gateway configuration.
+
+
+Gateway configuration
+=====================
+
+For each Teams trunk you should create dedicated :ref:`Gateway <gateways>` on Yeti side. Import configuration parameters:
+
+
+Transport Protocol
+    Should be **TLS**
+
+Host
+    Should be **sip.pstnhub.microsoft.com** See https://learn.microsoft.com/en-us/microsoftteams/direct-routing-plan#infrastructure-requirements for details/alternative options.
+
+Orig Append Headers Reply
+    Should contain **Allow: INVITE, ACK, CANCEL, BYE, INFO, NOTIFY, PRACK, UPDATE, OPTIONS**. Redefining **Allow** header there affects transfer logic on MS Teams side when call originated by MS Teams. Without this settings MS Teams will send **REFER** requests to Yeti-Switch to handle call transfer and it will fail because Yeti-Switch is not processing such requests in this scenario.
+
+Term Append Headers Req
+    Should contain **Allow: INVITE, ACK, CANCEL, BYE, INFO, NOTIFY, PRACK, UPDATE, OPTIONS**. Redefining **Allow** header there affects transfer logic on teams side when call originated by Yeti to MS Teams. In case of multitenant configuration **term append headers req** should also contain **X-RR-Domain: subdomain.teams.example.com**.
+
+Term Use Outbound Proxy
+    Should be **YES**
+
+Term Proxy Transport Protocol
+    Should be **TLS**
+
+Term Outbound Proxy
+    Shoyld be **subdomain.teams.example.com**
+
+Media Encryption Mode
+    Should be **SRTP SDES**
+
+RTP ACL
+    Should be **52.112.0.0/14, 52.120.0.0/14** See https://learn.microsoft.com/en-us/microsoftteams/direct-routing-plan#microsoft-365-office-365-and-office-365-gcc-environments-1
+
+
+Customer Auth configuration
+===========================
+
+MS Teams originates calls from same IP address range for all accounts. Since username/password SIP auth is not supported by MS Teams we have to authenticate incoming calls on Yeti side by IP addresses and domain names.
+
+:ref:`Customer Auth <customer_auth>` object important parameters:
+
+Require Incoming Auth
+    Should be **NO** because MS Teams doesn't support username/password authentication mechanism.
+
+
+Transport Protocol
+    Should be **TLS**
+
+IP
+    Should be **52.112.0.0/14, 52.122.0.0/15** See https://learn.microsoft.com/en-us/microsoft-365/enterprise/urls-and-ip-address-ranges?view=o365-worldwide#microsoft-teams
+
+From Domain
+    Should be **sip.pstnhub.microsoft.com**
+
+To Domain
+    Should be **subdomain.teams.example.com**
+
+Gateway
+    Previously created gateway
+
+
+Call routing
+=====================
+
+* Incoming call routing works as usual - call will be authenticated by customer auth matching logic, then routing will be done according to routing plan.
+* Outgount call routing works as usual - just create Dialpeer with MS Teams gateway and Yeti will send call to proper trunk.
+
+
+
+

en/index.rst

@@ -33,6 +33,7 @@ Welcome to Yeti's documentation!
    disconnect-codes
    headers-filtering
    best-practices/best-practices.rst
+   best-practices/teams-direct-routing.rst
 
 .. toctree::
    :maxdepth: 2