So you want to secure the XML traffic going from StoreFront to your Controllers (Brokers)… I think that's a good decision!
In many enterprise level deployments I encounter the following are true:
- They want to Secure XML – the transaction between StoreFront and the Controllers that contains user information. It's obscured over plaintext but SSL is always better!
- They DO NOT have IIS installed on the Controllers (as in, no Director or StoreFront roles installed) to keep services isolated and lower the attack surface.
Instructions here are good: https://support.citrix.com/article/CTX200415 and that link also includes methods for using IIS and also not. I've used that article for some time now.
I wanted to highlight some tips and tricks about this process- just to make sure the procedure is clear!
Choose a Secure XML Service Port
Make a design decision on the port you want to use. Default for SSL of course is 443 but you can use anything you like, for example 6443 or 8443- as long as it's not in use elsewhere on the controller you are fine. Note- because the Broker service can use the same ports for different functions, it can share for this function if you like. In our examples, we'll use 8443
So first, you'll open an elevated command prompt and navigate to the service directory, typically
cd c:\Program Files\Citrix\Broker\Service
run the command
BrokerService -storefronttlsport 8443
(remember to change the port to whatever you designed)
Note- this command to specify the secure XML port was previously -wisslport. This changed after 7.11 but in my testing the old command does still work.
Bind the Certificate
I'm not going to go into the process of requesting a certificate here. Make friends with Google 😉 Install the Cert- I will typically use MMC and the Certificate management. Remember to use the Local Machine account, and put the cert in the Personal store. It sounds counterintuitive but that is how it is done.
Once installed, Note the Expiration date of the cert. Make yourself a scheduled task for about a month before that date to revisit this process. You will need to rebind the certs or your users will not be able to log on using that broker service.
Pro Tip: Use different SSL Certificate dates for each Broker. That way, if you forget to update the certs before the expiration date you'll have a few days before users can't logon at all.
We'll use a netsh command for this. I find it best to use Notepad or another text editor like Notepad++ to build the commands first, then paste into a command line. For this, you can use PowerShell but I'm not sure what the point is- this is not a PowerShell command. First, add in the following:
netsh http add sslcert
Determine the IP address to bind. If you want to bind a specific IP address, make sure you have IPv6 disabled. Most people will want to specify a specific IP to bind to their service, but it is possible to bind to all incoming addresses. In our example, we'll say the address is 10.0.0.50, but you can use 0.0.0.0 for all. We'll use the entry ipport=<IP>:<port>
Our command should now read something like:
netsh http add sslcert ipport=10.0.0.50:8443
Next, you'll want to grab the Certificate Hash number of the cert. Double click the certificate to open it, and click the Details tab. Select the Thumbprint. Copy the text in the box.
(note- if you hate your life you can do this same thing within the Registry Editor)
Return to Notepad, add certhash= and paste the text into it. Remove the spaces between the hexidecimal sets of two that you copied. You should have 40 characters total. I'll create some gibberish here for the certhash, but our command should look like this:
netsh http add sslcert ipport=10.0.0.50:8443 certhash=39AB8CB5432AA54601D50D49B6875191D85AB3CA
Now- we'll need the GUID for the Citrix Broker Service.
Open Registry Editor and navigate to HKEY_CLASSES_ROOT\Installer\Products\. Ctrl+F to Search and search for Citrix Broker Service. Once you have the result that has that a ProductName in it's key, that key indicates your GUID. Right click on the key and select “Copy Key Name”
Back in Notepad, type in appid={ and paste in the key. Remove the HKEY_CLASSES_ROOT\Installer\Products that precedes it so that only a set of numbers remain.
You will need to add dashes to this in the following pattern of characters: {8-4-4-4-12}
So you would end up with something like appid={12345678-1234-1234-1234-1234567890AB}
Your command should now look like this:
netsh http add sslcert ipport=10.0.0.50:8443 certhash=39AB8CB5432AA54601D50D49B6875191D85AB3CA appid={12345678-1234-1234-1234-1234567890AB}
STOP
This next part will save you a lot of trouble!
Save your text file as an ANSI formatted document.
Close it and Re-Open it.
Pasting the Command
Were you to just paste the command in as text without re-opening the text file you may get the failure “The parameter is incorrect”
This happens because at times when you paste from Registry or the Cert into notepad and then re-copy, certain hidden UNICODE text will still copy. Saving the file as ANSI forces the characters into compliance first.
With your newly re-opened text file, copy the full text into an elevated command window. (note- if you don't see “Administrator” at the top of your command window you aren't elevated.
Dealing with other issues
- Don't forget to reboot your controllers once you've applied this configuration.
- Some people have found that putting the appid before the certhash works more consistently
- If for some reason the Certificate doesn't have enough numbers, first check that you have the correct type of cert issued and you aren't attempting to use the internal certificate. If it is correct, you may need to add zeros before the hex values for the cert hash.
- If you use PowerShell, be sure to first run netsh, then paste in the remainder of the command (without netsh in front of it).
- In some cases, using powershell will require you to add apostrophes surrounding the curly brackets when appid precedes the certhash. So it would look like
netsh
http add sslcert ipport=10.0.0.50:8443 appid='{12345678-1234-1234-1234-1234567890AB}' certhash=39AB8CB5432AA54601D50D49B6875191D85AB3CA
Repeat for All Controllers
Note- this is a binding for XML on each server, so you must be consistent and note that the appid and certhash will likely be different between servers. So you have to repeat this process.
Setting Up StoreFront and/or NetScaler Load Balancing
I'm not going to go too much into this, just a few quick tips:
- Make sure you select Transport Type as HTTPS and note the correct port for the Delivery Controller connection in StoreFront. It doesn't say “XML” on the dialogue box but when it refers to “Port” this means the XML Port to the Controllers.
- Make sure the StoreFront and/or NetScaler can trust the Certificates you used! This is a commonly missed item and why you should NOT use self-signed certificates. The best way to accomplish this is to make sure that StoreFront and/or NetScaler can trust the Root and Intermediate CAs that are used for the cert on the Controllers!
- Avoid using shared name certs; but a wildcard with SANs should be okay for this. Because the interaction will be with individual servers for XML it ends up being important in most cases. The NetScaler may ignore it but that's really not leading practice, is it?
I hope this is helpful for you! Feel free to leave any questions in the comments for folks to help you out with!