Deploy a UCMA SDK Application
This content is no longer actively maintained. It is provided as is, for anyone who may still be using these technologies, with no warranties or claims of accuracy with regard to the most recent product version or service release.
To deploy a Microsoft Unified Communications Managed API (UCMA) application, configure the Microsoft Office Communications Server environment, establish trust between the application and Office Communications Server, and then create contact records in Active Directory directory service.
Types of Application Deployment
There are two types of routing for Office Communications Server applications:
User-routing, used by Microsoft Office Communicator.
Application routing, used by UCMA applications.
Within the category of application routing, there are two choices:
A non-redundant deployment model where there is only one instance of the application.
.jpg "Dd130183.874fb685-2242-477d-88da-bbaffc33dfea(en-us,office.13).jpg")
A redundant deployment model features hardware load balancers and multiple instances of the application. Each instance of the application is represented by a trusted service object (TSO). Each identical TSO for the application contains a set of properties, including application name, trusted GRUU, and port number to listen on. Office Communications Server passes calls to the application to a hardware load balancer, which uses Round Robin Domain Name System (RRDNS) to distribute calls to individual TSOs.
.jpg "Dd130183.ea8a3ad7-3b79-4272-9c1e-c0a57bd8adb7(en-us,office.13).jpg")
Load Balancing
When running applications on Office Communications Server, authors may choose to use either Enterprise Edition or Standard Edition. With Enterprise Edition there may be more than one Front End Server. If more than one Front End Server is used, the application's outbound connections should be load balanced across the Front End Servers using a hardware load balancer. Standard Edition uses a single Front End Server, so load balancing is not required.
Activating the Application
To activate an application, establish trust between the application and Office Communications Server, and then add an Application Contact Object for the application.
To communicate over a Mutual Transport Layer Security (MTLS) connection, Office Communications Server and the application server must have a valid certificate signed by a mutually-trusted certification authority. As an additional security measure, Office Communications Server also refers to a Trusted Service Entry (TSE) for the application. A TSE is a record stored in Active Directory that indicates which servers are trusted by the domain. To be trusted by Office Communications Server, a server must have a certificate and a TSE.
Create an Application Pool
Create an application pool to establish communications at the connections level.
To create an application pool
In Active Directory, for each application type, activate one trusted service object for each instance of the application.
In Active Directory, activate one trusted service object for the hardware load balancer used as the entry point to the application pool.
Manually provision the hardware load balancer to map the application instance’s RCT to the hardware load-balancer connection tuple corresponding to this application pool.
Create Application Endpoints
Create application endpoints to establish communications at the SIP routing level. Each contact object represents a routable entity for the application, and is present once for each application instance.
To create application endpoints
- Activate one or more contact objects associated with a given application pool.
Adding Trusted Service Entries
To create TSEs, use the WMI class cimv2\MSFT_SIPTrustedAddInServiceSetting. Required properties are listed in the following table.
Property name |
Comment |
|---|---|
Type |
Identifier for the application. |
FQDN |
Fully qualified domain name (FQDN) of the system receiving SIP traffic for the application. If the system is part of an array behind a load balancer, the FQDN is the address of the load balancer. |
TlsTarget |
The FQDN of the certificate on the computer. If TlsTarget is NULL, then the value in the FQDN field in the previous row is used. Different values in FQDN and TlsTarget indicates a load balancer is being used. Available pools can be retrieved from MSFT_SIPPoolSetting.PoolFQDN.PoolFQDN. |
Port |
The TCP port the application listens on. The valid range for port numbers is 1 to 65535. |
Routeable |
Set to TRUE. |
TrustedServiceCategory |
Set to “Custom”. |
The following properties of the TSE are automatically created: InstanceID, GRUU, and TrustedServiceDSN.
The GruuID property of the TSE is set to NULL.
For more information, see the ApplicationProvisioner sample application in the UCMA v2.0 Core SDK\Sample Applications\Collaboration\ApplicationProvisioner directory.
Adding Certificates
Use certificates to authenticate the connection between the Office Communications Server computer and the application computer. A Unified Communications Managed API application may use either Transmission Control Protocol (TCP) or Mutual Transport Layer Security (MTLS). Use of MTLS requires a certificate to authenticate inbound and outbound connections with Office Communications Server. For more information about certificate management see Advanced Certificate Enrollment and Management.
In Office Communications Server, use Certificate Wizard to create certificates on the Standard Edition server or Front End Server of an Enterprise pool. For more information, in the Microsoft Office Communications Server 2007 Administration Guide see "Configuring Certificates for Servers" and "Configuring Internal and External Interfaces and Certificates for Edge Servers."
Certificates are also required on the application computer.
Create a certificate for the application computer that will be trusted by Office Communications Server, and then import that certificate to the application host computer. This certificate must be installed in the Console Root\Certificates(Local Computer)\Personal\Certificates folder.
Create a root certificate and install this certificate in the Console Root\Certificates(Local Computer)\Trusted Root Certification Authorities\Certificates folder.
Ensure the account used for the application has read access to the certificate store and the private key.
Application contact objects in Active Directory represent an application that the server running Office Communications Server can route calls to. An Application Contact object contains the Display Name, SIP URI, Tel URI and a reference to the TSE representing the application.
Adding Contact Objects
After a TSE is created, create a contact object to provide routing to the application. To create a contact object, use the WMI class cimv2\MSFT_SIPApplicationContactSetting. Required properties are listed in the following table.
Property name |
Comment |
|---|---|
ApplicationDescriptionDN |
The value of the associated Trusted Service Entry (TSE). Set this TSE to the value of the MSFT_SIPTrustedServiceSetting.TrustedServiceDN property. |
PrimaryURI |
The default domain for the pool that created the contact object. To set this value, find the instance of MSFT_SIPDomainData where MSFT_SIPDomainData.DefaultDomain = TRUE, and read the value MSFT_SipDomainDate.Address of that instance of MSFT_SIPDomainData. |
DisplayName |
The name under which the contact will appear in the address book. |
DisplayNumber |
The telephone number that will appear in the address book. |
Enabled |
A Boolean value that indicates whether the object is enabled. Set this to TRUE. |
EnabledForEnhancedPresence |
A Boolean value that indicates whether the object is enabled for enhanced presence. Set this to TRUE. |
EnabledForFederation |
A Boolean value that indicates whether the object is enabled for federation. Set this to TRUE or FALSE, depending on the application and function performed. |
HomeServerDN |
The Distinguished name of the Active Directory object representing the pool that created the contact object. The value is available in MSFT_SIPPoolSetting.PoolDN. An instance of MSFT_SIPPoolSetting is available for each pool configured in the enterprise. Pick the pool that is most applicable. |
LineURI |
The phone number of the contact object. Set this to tel:< phonenumber >. This value can be set to NULL. |
UCEnabled |
A Boolean value that indicates whether the object is enabled for Unified Communications Managed API applications. |
The following properties of the contact object are automatically created: ContactDN and InstanceID.
The following properties of the contact object are not used, and are set to NULL: LocationProfile and MeetingPolicy.
Provisioning the Application
To provision the application in Office Communications Server, first configure authorization, set permissions, and then configure authentication.
To configure authorization, activating the TSE will populate and update the appropriate authorization in Office Communications Server.
UCMA SDK applications require the following permissions: registry read access, permission to execute unmanaged code, and file write access if tracing is enabled. Also, application user accounts must be members of the RTCService domain security group.
To configure authentication, create certificates on Office Communications Server Standard Edition or the Front End Server of an Enterprise pool, and on the application computer.
See Also
Other Resources
Unified Communications Managed API 2.0 Workflow SDK Documentation