Goal (short description)

This recipe describes tying Microsoft Office Communications Server 2007 (OCS) to Asterisk. This enables users that have a hard phone connected to an Asterisk PABX, to

• make calls from their Microsoft Office Communicator to the PSTN
• be dialled from the PSTN and answer the call on either the hard phone or Office Communicator (for instance when working from home)
• let them control forwarding and simultaneous ringing options from the Communicator
• have an archive of call records and missed calls notifications in Microsoft Outlook
• click to dial on telephone numbers within Outlook

Applicability

OCS is meant as a value adding service platform that offers Unified communications by integrating IPTelephony, presence, instant messaging and e-mail. The power lies in the connections. A powerfull connection, and also a difficult, is to connect it to a PABX. In this case, the PABX is based on Asterisk. Asterisk takes care of the connectivity with the PSTN and the number plan.

OpenSER acts as a proxy between Asterisk and OCS, since OCS only supports SIP over TCP and Asterisk only SIP over UDP.

When a call is made, the message flow is as follows:

SIP:
Communicator 2007 <-TLS--> OCS <-TLS--> OCS med serv <- TCP -> OpenSER <- UDP -> Asterisk <-> PSTN

Media:
Communicator 2007 <-SRTP-> OCS <-SRTP-> OCS med serv <------------RTP----------> Asterisk <-> PSTN

This recipe needs one bug to be resolved concerning RTP flowing from Asterisk to the Mediation server. Solution coming soon.

Prerequisites

• Linux machine with Asterisk, a number plan and PSTN connectivity
• Linux machine with OpenSER 1.2.1 or higher http://www.openser.org/mos/view/Download/
• Microsoft Office Communications Server 2007 core installation
• Windows 2003 machine to install OCS Mediation Server 

OCS can be either Enterprise Edition or Standard Edition. For the basic installation guides of OCS, see http://technet.microsoft.com/en-us/library/bb676082.aspx.

You need a second windows machine to install an OCS Mediation Server, which is the designated node for external SIP connectivity.
For specifics on installing OCS Mediation Server, see http://www.microsoft.com/downloads/details.aspx?FamilyId=24E72DAC-2B26-4F43-BBA2-60488F2ACA8D&displaylang=en

Configuration of Asterisk

Assuming you have a working Asterisk setup, only few things have to be taken care of.

Create a SIP trunk, see http://blog.lithiumblue.com/2007/12/interim-information-on-integration-ocs.html for an example if you use Trixbox as your Asterisk server. Use the following settings in your SIP.conf:

         host=<your OpenSER IP address>
         port=5060
         qualify=no
         type=peer
         context=from-internal

Forward all incoming calls from the PSTN destined for known extensions to the SIP trunk that connects to OpenSER.

Asterisk should always send a full E.164 number to OCS, starting with a plus sign !

Configuration of Microsoft Office Communications Server 2007

Your basic Enterprise Edition or Standard Edition server should be running and you have enabled users to log on to OCS. PC-to-PC calls should run smoothly. If they are outside the firewall, you should use an Edge Server (which supports STUN and rate limiting).

In the OCS MMC snap-in, right click on the OCS forest and select 'properties -> voice properties'.

Add a Localization Profile

The dialog opens in the 'Localization Profiles' tab.
Edit the default location profile or add a new one and edit the profile, so you can add a localization rule.

Add a normalization rule

Within the localization rule, add a normalization rule. The rule translates numbers dialed by users to a standard format. Here we always translate to E.164 format, namely

+<countrycode><area code><subscriber number>

Fortunately, the Microsoft Communicator translates numbers automatically to this format, leaving out the +, (), spaces and dashes, even when starting a call from Microsoft Outlook. However, we have to add at least one rule. The normalization rule is written in .net regular expression format. See http://www.regular-expressions.info/tutorial.html for more explanation of regular expressions. In our case, we translate any number starting with a zero to a Dutch number:

^0(\d*)$       ->       +31$1

It basically means that for any new translation (^) of a number that starts with a 0 and then containing any number of digits \d* it should take the part of the number between brackets () and use it as variable in the translation. The translation adds +31 to it.
THE '+' SIGN IS ABSOLUTELY CRUCIAL!!!!! Don't forget to put it there! Please double check whether it's in the config! Don't say we didn't warn!

Add phone usages and policies

When you're done with the 'Localization Profiles' tab you can add 'phone usages' in the 'voice properties' dialog, which are useful for assigning to users and logging these types of use. Be sure to also create at least one Policy in the Policy tab. A collection of phone usages form a 'policy', and a user will later on be assigned a policy. This way, you can discern which users are allowed what type of calls (for instance disallow service numbers).

Add a Route

Finally add a 'route' under the 'routes' tab.
Here is defined that for numbers matching a certain regular expression, the call should be routed to our mediation server. The regular expression states in this case that any number should be forwarded:

^(\d*)$

Part of the route definition are the phone usages that are allowed for this route.

See the Microsoft 'OCS_VoIp_Guide' document for further reference.

Enabling users

Even though they cannot really make external calls yet, you can enable users for Enterprise Voice. This can be done in various places. Let's go to the 'Active Directory Users' MMC snap-in, go to the entry of a test user and select its properties.

In the 'Communications Tab' choose 'additional options' -> Configure,
and in the new dialog select 'Enable Enterprise Voice':
Fill in the line URI. which can be of the form

tel:+<nr>                  (yes, the '+' again!)

Install and configure OCS Mediation Server

Now install an OCS Mediation Server on a machine running Microsoft Windows 2003 server. The Mediation Server software can be found in the OCS installer under 'additional server roles'.

Configure the Medation Server as follows:

Next Hop:
Gateway Listening IP address: the external IP address of the Mediation Server

Location Profile:
choose the location profile as chosen before (i.e. 'Utrecht')

Gateway IP addres:
<your OpenSER IP address>

Configuration of OpenSER

Edit your openser.cfg as follows or download openser.cfg for your convenience:

# lower debug level for debugging purposes: 
debug=5
log_stderror = no
fork=yes
children=4
alias=<your OpenSER proxy FQDN>
listen=udp:<your OpenSER proxy IP address>:5060
listen=tcp:<your OpenSER proxy IP address>:5060
check_via=no
dns=no
rev_dns=nompath="/usr/local/lib/openser/modules/"
loadmodule "sl.so"
loadmodule "tm.so"
loadmodule "maxfwd.so"
loadmodule "uri.so"
loadmodule "uac.so"
modparam("uac","from_restore_mode","auto")
loadmodule "textops.so"
loadmodule "rr.so"
modparam("rr", "enable_full_lr", 1)
modparam("rr", "enable_double_rr",0)
loadmodule "mi_fifo.so"
modparam("mi_fifo", "fifo_name", "/tmp/openser_fifo")
loadmodule "xlog.so"
modparam("xlog", "buf_size", 4096)
modparam("xlog", "force_color", 1)

route {
if (mf_process_maxfwd_header("10")) {
	sl_send_reply("483","Too Many Hops");
	exit;
};
if (msg:len >= 2048 )  {
	sl_send_reply("513", "Message too big");
	exit;
};
 
if (loose_route()) {
	append_hf("P-hint: rr-enforced\r\n");
	route(1);
};
 
if (!uri==myself) {
	append_hf("P-hint: outbound\r\n");
	route(1);
};

route(1);
}
 
route[1] {
	# If coming from OCS
	if (src_ip==<your OCS Mediation Server IP address>)
		{ if (method=="INVITE|BYE") {
			xlog("L_INFO", "*** invite from OCS M=$rm RURI=$ru F=$fu T=$tu IP=$si ID=$ci\n");
		}
		t_relay("udp:<your Asterisk Server IP Address>:5060");
	}
	# else coming from Asterisk
	else {
		t_relay("tcp:<your Asterisk Server IP Address>:5060");
	};
	exit;
}

OS specific help

Validation, confirmation tests

Configure MS Office Communicator 2007 to log on to OCS and provide the login account with a 'line URI' as mentioned above. Start typing a telephone number or (Outlook) contact in the search bar or right-click on one of the contacts to dial the number. The communicator should ring, as well as the chosen number.

A useful tool to debug SIP message flows can be downloaded from the MS site:
http://www.microsoft.com/downloads/details.aspx?familyid=7b6ab4f3-2949-4e97-856e-9c4ae323c75a
You can use it by right-clicking on your OCS pool or server and choose 'Logging tool->Start debugging session' . Choose 'SIPstack' in the options and click 'start' before setting up a testcall. After pressing 'stop' and 'analyse' you can see a SIP messageflow between your OCS nodes and find problems.

For debugging on the OpenSER machine, you can use ngrep or wireshark

> tshark -i any -n -V -R sip

Acknowledgements

Thanks to the NLnet Foundation for sponsoring, 2AT and Rob Kruit.