Trusted Domains and SIP Gateways

Microsoft Unified Communications Managed API (UCMA) 3.0 is able to interoperate with third-party SIP peers such as IP-PBXs and SIP PSTN gateways. This topic describes the APIs on the CollaborationPlatform and related classes that developers must understand when they create applications that interoperate with SIP gateways.

Configuring Trusted Domains for the CollaborationPlatform

UCMA 3.0 can be used to create a CollaborationPlatform instance using the TCP, TLS or MTLS transport types. For security reasons, it is highly recommended that you use TLS or MTLS.

UCMA 3.0 supports two modes of trusted domains as specified in the TrustedDomainMode enumeration: CommunicationsServer and Other. The CommunicationsServer value indicates that the trusted domain is a Microsoft Lync Server 2010 server or a Microsoft Edge Server. The Other value indicates that the trusted domain is a remote SIP peer, such as a SIP PSTN gateway or IP-PBX.

Most of the SIP messages and call flows in both TrustedDomainMode modes are of the same type. The principal differences involve header parsing and the filtering of headers in outgoing messages. These differences between these modes are described later in this topic.

If a CollaborationPlatform instance is created with the TLS or MTLS transport type, the default behavior of the platform is to consider the first-hop proxy (specified in the ProxyHost property on an ApplicationEndpointSettings instance) to be a Lync Server 2010 or Microsoft Office Communications Server 2007 R2/Microsoft Office Communications Server 2007 server (TrustedDomainMode.CommunicationsServer). Unless specified by application writer (the application writer can use the ConnectionContext property on a CallEstablishOptions instance. to override this behavior), all outgoing messages and INVITE messages are routed to this first-hop proxy.

UCMA 3.0 allows application writers to prepopulate all known trusted domains. This can be done by adding the known domains on the property TrustedDomains property on a ServerPlatformSettings instance when the CollaborationPlatform is constructed. The TrustedDomains property is similar to the obsolete AllowedDomains property on the ServerPlatformSettings class, except that developers can use the TrustedDomains property to choose the type of trusted domain for each entry. For incoming connections this property represents a list of computers that are allowed to make incoming connections, when mutual TLS is used. The subject or subject alternate names (SANs) in the certificate are matched against each DomainName property (on the TrustedDomain class) in the TrustedDomains collection. For outgoing connections domain names are matched with the fully qualified domain names specified in the connection context.

The following code example demonstrates how to add two trusted domains in platform settings when a CollaborationPlatform instance is constructed.

private CollaborationPlatform CreateServerPlatform()
{
  ServerPlatformSettings mySettings = new ServerPlatformSettings();
  // Add a known Microsoft Lync Server 2010 server to trusted domains.
  mySettings.TrustedDomains.Add(new TrustedDomain(“finance.contoso.com”)); 
  // Add a known PSTN gateway to trusted domains.
  mySettings.TrustedDomains.Add(new TrustedDomain(“mygateway.contoso.com”), TrustedDomainMode.Other); 
  CollaborationPlatform platform = new CollaborationPlatform(mySettings);
  return platform;
}

Maintaining a Dynamic List of Trusted Domains

In some applications an application might not be aware of all trusted domains at start-up time. In these cases the application can authorize outgoing or incoming connections by registering a handler for the ConnectionAuthorizationRequested() event.

The following example demonstrates an implementation of a handler for the ConnectionAuthorizationRequested event. In this event handler, an application selectively allows connections that match a specific domain name.

private void myConnectionAuthorizationRequested(object sender, 
ConnectionAuthorizationRequestedEventArgs e)
{
  // Accept the incoming connection if it is from the known domain ″finance.contoso.com″, otherwise deny it.
  if (e.Connection.MatchingDomainName == ″finance.contoso.com″)
  {
    e.Allow();
  }
  else
  {
    e.Deny();
  }
}

UCMA 3.0 also enables application writers to add trusted domains to or remove them from the CollaborationPlatform instance after platform is started. For these purposes, he CollaborationPlatform class exposes the GetTrustedDomains, AddTrustedDomain(TrustedDomain), and RemoveTrustedDomain(TrustedDomain) methods to maintain a list of trusted domains in the CollaborationPlatform instance. When a trusted domain entry is added after the platform is started, the semantics for newly added or removed domains are applied only to new connections and have no any impact on connections created prior to the new entry.

TrustedDomainMode Differences

There are few differences in behavior between the CommunicationsServer and Other enumeration values of the TrustedDomainMode enumeration for most call flows and other SIP transactions. The following table describes the differences in header parsing and outgoing header filtering.

Setting ConnectionContext on an Outgoing Call

The default behavior of a CollaborationPlatform instance is to always route messages to the first-hop proxy that is specified in the ProxyHost property in the ApplicationEndpointSettings instance. An application writer who intends to route outgoing message to any destination host other than the first-hop proxy should set the ConnectionContext property on the CallEstablishOptions instance for the outgoing call.

The following code sample demonstrates setting connection context on an outgoing call, so that outgoing INVITE messages are routed to the gateway server specified in options.ConnectionContext.

Conversation conversation = new Conversation(myAppEndpoint);
AudioVideoCall outgoingCall = new AudioVideoCall(conversation);
CallEstablishOptions options = new CallEstablishOptions();
options.ConnectionContext = new ConnectionContext(myGatewayFQDN, gatewayPort);
outgoingCall.BeginEstablish(gatewayUri, options, userCallback, outgoingCall);