So, you want to be able to enroll your users onto XenMobile by sending an SMS with all necessary links?

Well, basically, you have two choices off-the-shelf:

  1. XenMobile supports SMS provider Nexmo out of the box. Nexmo is an SMS gateway that you can subscribe to from most countries in this world, and their prices are competitive. So for the easiest integration, just create an account at http://www.nexmo.com, go into your XenMobile settings, and under “Notification Server,” add an SMS provider with the details from your Nexmo account.
  2. Most SMS gateway providers actually also provide an SMTP interface to their services. So your second choice , which is almost as easy as using Nexmo, is to simply create an SMTP provider, pointing to your internal mail server, and create or modify notification templates. In this case, you would remove the “SMS” option from your notification templates, and set the SMTP recipient to something like:”${user.mobile}@smsgateway.myprovider.com”. In this particular sample, I use the field “Mobile” from the user’s Active Directory object. Using this method, you can easily send SMS’es for enrollment. However, to make this method work, you need to make sure your phone numbers are formatted without spaces and dashes in AD.

If these methods don’t get you where you want, how would you go about configuring a custom SMS provider in XenMobile?

Well, you cannot really do that as of today. But hey, I can provide you with a method that will achieve just that, although Citrix cannot directly support this solution.

The basic idea here, is that “if you have XenMobile installed, you will most probably also have a NetScaler.” And NetScaler is, after all, the Swiss army knife of any data center, right? So, basically, we can let XenMobile believe it sends an SMS request to Nexmo, but have NetScaler intercept it, and transform it to fit the SMS gateway of your choice, before it is then sent to the correct SMS provider. Sounds interesting?

To make it easier to follow, I will provide instructions only for using NetScaler GUI to set this up. The procedure has been tested with NetScaler 11 towards a limited set of SMS providers, but as long as you have some documentation on what format your provider expects, this should work for most providers. It is, however, only tested with the Latin alphabet, so I have no idea how it would react to other alphabets. Please provide comments below if you test it with a different alphabet, to tell me how it went!

Let’s go!

NetScaler Configuration

When this blog post was first written, it was possible to use regular HTTP (port 80) from XenMobile towards rest.nexmo.com. Unfortunately, due to changes at Nexmo, this is no longer possible, so now you need to have an SSL certificate on your SMS gateway vServer. My recommended approach for this is the following:

-Create a new Root Certificate and Key on NetScaler called something like “LocalNexmo CA”

-Create a new certificate on NetScaler for the common name (CN) of “rest.nexmo.com”, and sign it with the “LocalNexmo CA” root certificate.

-Import the “LocaNexmo CA” certificate as a trusted root on XenMobile.

By doing it this way, you have a separate root specifically for this purpose, so that you are in control of which hosts trust the certificate. The only servers that should trust it, are your XenMobile servers. This is in reality an “impersonation”, which is a bit dirty, so in order to keep it as clean as possible, we should use this “only trusted by XenMobile servers” approach.

Create a URL Transform

Go into AppExpert –> Rewrite –> URL Transformation –> Profile and create a new profile.TransformAction

Then go into the new profile you created, and press “Insert” to create a new profile. Make sure you set a valid priority and check the “Enabled” check box. Insert the following text into the “Request URL From” box:

/sms/xml?username=(.*)(?:&password)(?:=)(.*)(?:&from).*(?:to=)(.*)(?:&type).*(?:text=)(.*)(?:&).*

This extracts the interesting fields from the Request URL, and assigns them to the following variable:

Username = $1

Password = $2

SMS to = $3

Message = $4

In the “Request URL Into” box, insert the text that is needed for your SMS gateway provider. As an example, this is the URL required by one provider:

http://sms.example.com/send?username=myuser&password=secretpass&to=%2B46701234567&from=%2B46701234567&text=Hello+world

For this particular sample, we would insert the following in the “Request URL Into” box (provided the “From” parameter may be alphanumeric, if no, use a number):

/send?username=$1&password=$2&to=$3&from=XenMobile&text=$4

Press OK and OK to leave the Profile.

Now go into AppExpert –> Rewrite –> URL Transformation –> Policy and create a policy. The policy expression may be as simple as “true”, but I chose to use “HTTP.REQ.URL.CONTAINS(“status-report-req”)”, since I know SMS URLs generated by XenMobile contain that string. For “Profile”, choose the profile you created above.

TransformPolicy

Create a vServer and bind the URL transform to it

Go to Traffic Management –> Load Balancing –> Servers, and add a server object that points to your supplier’s web server, for instance:

LBServerObject

Now, go to Traffic Management –> Load Balancing –> Service OR Traffic Management –> Load Balancing –> Service Groups, and create either a Service or a service group that points to your SMS supplier’s SMS gateway. Make sure you use the correct protocol (HTTP or SSL) and port, which may be non-standard. Example:

LBService

Monitor binding is optional, some providers may not like if you send unsolicited tcp requests. In that case, you can disable “Health Monitoring” on the service / service group. Otherwise, I would recommend using the default tcp monitor, since running an HTTP monitor against an SMS gateway is unlikely to give the required HTTP status code. (The HTTP monitor expects an HTTP 200 (OK) as reply when requesting the default URL of the site, but SMS gateways are unlikely to respond to a “default site”.)

Next, create a vServer to use this service. This is done by going into Traffic Management –> Load Balancing –> Virtual Servers, and chosing “Add”.

First, choose a name for your vServer, use SSL as protocol, and set an IP address that XenMobile will use to “talk to” this virtual server.

For Load Balancing Service or Service Group binding, choose the object you created in the step above.

Now, click on “Policies”, and then the “+” sign in the Policies box:

LBPolicy

Set the “Choose Policy” to “Transform, and let the “Choose Type” box stay “Request”.

SetPolicy

Select the URL Transform policy that you created in step 1 of this guide, and press OK.

InsertTransform

Select “Server Certificate” under “Certificates”, and add the server certificate that you have created for “rest.nexmo.com”.

Press “Done” to save and exit from this new vServer. This concludes the job on the NetScaler.

 Configure hosts file on XenMobile Server(s)

(This step needs to be repeated for the all XenMobile servers that will use the SMS gateway)

Use hypervisor-based console or SSH (if you have enabled it) to log on to the console of your XenMobile server. Choose 2 (System), and then 4 (Update Hosts file). You will now be able to make XenMobile contact your NetScaler vServer instead of contacting Nexmo upon sending SMS. Add the following entry:

rest.nexmo.com:<IP of your NetScaler vServer>

For my example above, I gave the NetScaler vServer the address 10.0.0.20, so my entry would be:

rest.nexmo.com:10.0.0.20

After this change, you can check by typing “4” again:

XenMobileConsole

To exit this menu, type a period (.) and enter. You may now exit the shell, and test the solution from XenMobile.

Troubleshooting

In order to troubleshoot, log onto your NetScaler through your favorite ssh client (putty), and type “shell<enter>” to go into a shell.

Now, type the following command into the window:

nstcpdump.sh -A -s 0 ‘(tcp port <port-of-provider’s SMS gateway> and host <SMS gateway host IP>) or (tcp port <your vserver’s port> and host <your vserver’s IP>) and (((ip[2:2] – ((ip[0]&0xf)<<2)) – ((tcp[12]&0xf0)>>2)) != 0)’

This enables you to see, in real time, the traffic going to your NetScaler vServer, and the traffic going from the NetScaler to your provider’s SMS gateway. For the environment I have used as an example above, the finished command to use would be:

nstcpdump.sh -A -s 0 ‘(tcp port 8080 and host 193.54.2.21) or (tcp port 80 and host 10.0.0.20) and (((ip[2:2] – ((ip[0]&0xf)<<2)) – ((tcp[12]&0xf0)>>2)) != 0)’