I’m a big believer in multi-factor authentication for NetScaler Gateway deployments. I’ve posted several guides and spoken at events in the past on the importance of having 2FA or MFA solutions in place for an enterprise. One that I had used years ago was SMS PASSCODE. They were bought by CensorNet earlier this year so I decided to try out the latest version with with my NetScaler and see what’s changed. The big thing I want to point out that as of last month, SMS PASSCODE is being re-branded as “CensorNet MFA” so you’ll see the name gradually change over the next few months.
Last year I talked about “How to deploy Microsoft Azure MFA & AD Connect with Citrix NetScaler Gateway” which is a half cloud/half on premises solution so really, a hybrid approach to multi-factor authentication. What if your company needs and on-premises solution or isn’t an Azure customer willing to pay for the Premium level Azure AD subscriptions or the Enterprise Mobility Suite (EMS)? And what if you had a need for Adaptive MFA that go beyond the basic conditional access Azure MFA can currently provide? SMS PASSCODE is a solution that is able to handle both of these use cases very well in my opinion.
To explain Adaptive Multi-factor authentication if you are not familiar with it, it is something a lot of multi-factor and identity and access management vendors are now pushing. What this allows is the ability to trust certain devices/locations/other scenarios while not others. This means the user can get pass-through authentication or be challenged by MFA depending on these environmental factors you define and the level of trust you have for that particular session. Hence, a type of multi-factor authentication that adapts to the scenario.
I’m going to show you a very basic install and configuration of SMS PASSCODE with your NetScaler Gateway.
Installing SMS PASSCODE Server
1. Stand up a new domain joined Windows server and install SMS PASSCODE. You should install the Windows Network Policy Server (NPS) role first as a pre-req because the installer doesn’t do it for you. In this example, I am not installing it because I want to show you how to fix it if you forget to install this role first. I am using version 9.0 so my zip file is a tiny 40.5 MB file called “SmsPasscode-900.zip”. Just unzip it and begin the x64 install:
4. You can leave all the default components. Notice there is a Self-service Website and Password Reset functionality that is not being installed. This can be installed later on web servers dedicated to this functionality, the Self-service website internally and the Password Reset site in your DMZ. I also want to note some of these roles can be broken out and scaled up as needed for larger environments.
9. On this screen the installer is asking for Authentication Clients. It just means things it has detected that can be used with SMS PASSCODE. I intend to use RADIUS with my NetScaler Gateway and you can see here it is greyed out. The reason is I need to install the Windows Network Policy server role on this server before SMS PASSCODE can protect it. As I mentioned in Step 1, you should have this in place already but I am showing you how to correct if if you forgot. I will install this role after the installer is done and show you how to correct this later on in the article. If you installed NPS before beginning the installer and you can check this box, do so now. Otherwise, just hit Next.
Configuring SMS PASSCODE
15. The Configuration Tool will open and ask you for the Network ports you want to use. You can use the defaults. I like the fact this comes up first because if the SMS PASSCODE server resides in a secure zone sandwiched by firewalls you will need to open ports and this makes it convenient letting the engineer know exactly which ports are going to be used and for what.
16. Below this is the box for the Shared secret. When you add more servers they need to be able to trust each other and they will use this secret. Make the password at least 15 characters long and save it away for later.
18. If you click on the Database tab you can see where the SMS PASSCODE database is being stored. If you go to that path you’ll see it’s just an XML file:
C:\Program Files\SMS PASSCODE\Database\SMSPASSCODE_DB.xml
23. Hit Modify and hit Next until you get to the Authentication Checks. Now RADIUS Protection will be available to you so check it. Would have been a whole lost easier if the installer did a pre-req check and had installed this role, right? 🙂
26. Go to the Miscellaneous tab and check “Collect end-user IP addresses from RADIUS attribute” under End-User IP. Once you hit Ok make sure to hit Save to save your config which will also restart the NPS Service.
Importing AD users into SMS PASSCODE using the web interface
27. In the the Web Administration interface go to Settings > General > Misc. Settings tab. Under “User store integration” click Enabled (multi sync mode) which enables AD integration. Also check Geo IP and IP history as well as Secondary phone numbers. These can come in handy later for logging purposes and to handle users with multiple phones. Don’t forget to hit Save in the top right.
By the way, Geo location has it’s own map within the SMS PASSCODE web console but this data can also be pushed to Splunk for additional analytics (one of my favorite search and visualization tools to use with my NetScalers – https://splunkbase.splunk.com/app/1702/).
28. Go to the Authentication Monitoring tab and enable logging. This will help with AAA logging retention requirements. You can leave it as the default CSV method if you like. I don’t recommend leaving logs on the C: drive as they can fill up the system drive. I recommend having a separate drive attached to the VM for logging purposes and these logs should be grabbed by a SIEM other log parsing utility. Right now there is no mechanism to syslog natively from within SMS PASSCODE but it would be a nice feature if they add it in the future. It writes to Windows event logs so you can always forward from there if necessary. Don’t forget to hit Save in the top right.
Click Edit and go to the Data Source tab. So you can see here the security group name it is looking for to sync users up with in AD is called “SMS PASSCODE Users”. If you don’t have an AD group yet you need to create one named this and add your users. If you are intending to use an existing security group then you must put the security group name here and hit Save.
Keep in mind every one of your users must have the mobile attribute populated with their cell phone number or they won’t be synched into SMS PASSCODE.
You can change this behavior by changing the attribute mapping under the Data Mapping tab or stopping the mobile number check under Data Filtering though I do not recommend doing this unless you have a real need to.
If you just created your security group it might take a minute or two but the Sync status will go green. If you want more info on exactly what is happening click Show sync status on the right side, don’t use the Connection test/Verify settings option at the bottom as it’s not talking abut the sync status.
Configuring the Dispatch Connector for CensorNet App and mobile devices
30. Now you might be wanting to hit that Test button next to your user but as is, nothing is going to work. This is because you haven’t created a Dispatch Connector yet. The Dispatch Connector is what actually sends the SMS (text message) out to the user’s phone. This can be done with an on-premises GSM or CDMA modem or via a web service that can send SMS messages for you. In this example I will use CensorNet App which is CensorNet’s web service that talks to their mobile app and sends a push notification rather than an SMS. Go to Transmission > Dispatch Connectors > Add new Dispatch Connector
31. In the Provider box, you can see SMS PASSCODE is compatible with a lot of different SMS services. Again, I’m using CensorNet App in this example so I will select it and the fields will automatically change to what I need to enter for that service in order for it to work. Give it a name, paste the Account ID for the service (this is like a license code that is unique to you), and select the server as a Transmitter host. Don’t forget to select hit Save in the top right.
32. Before I can test, I need to go my phone’s app store and install the CensorNet mobile app which was released very recently. This allows encrypted OTPs (one time passcodes) to be pushed to me via my mobile device. It also allows for other notifications like welcome notifications, reminder notifications, MFA lockout notifications, AD lockout notifications, and password expiration notifications:
Apple iOS devices:
33. Once I have the mobile app installed I need to provision my device. Basically prove I am who I say I am and that this is my device. In this first screen select your country and it will automatically add the prefix. Just type in your cell phone number after that and hit Next in the top right.
36. Extra bonus, go to the About section of the CensorNet App. They’re using the Azure Messaging SDK (Xamarin)! Very cool!
41. The Default Dispatch Policy is set to attempt to dispatch an SMS via a modem. Since I’m using a push message with a Dispatch Connector, I need to specify this on a new dispatch policy rule. Go to Dispatch Policies and click Edit.
43. Give it a description like “CensorNet App” and then go to the Dispatch settings tab and switch Dispatch type to Push message. It should automatically default to the CensorNet App dispatch connector if that is the only one you have setup so far. Take note of the message along the top saying we have not enabled passcode messages. We’ll take care of that in the next step. Just hit Create. Don’t forget to Save your Rule order on the next screen or it won’t take.
44. Go to General > Authentication Settings and check the Dispatch plugin modules check box. This is what allows passcodes to be sent via the CensorNet App dispatch connector. Don’t forget to hit Save in the right.
Configuring the Network Policy Server
47. Give it a friendly name like “NetScaler Gateway”. For the IP you would normally need to put in the NSIP of the NetScaler which is where authentication traffic flows through. If you load balance the NPS server or servers through the NetScaler itself however, the authentication traffic will flow through the SNIP. In this example I am going to put in my SNIP because I will later load balance this single NPS server through the NetScaler. You can create a Manual shared secret here. If you hit Generate it’s going to be too long and have special characters the NetScaler may not be able to process. Keep in mind this is not the same secret password you created for the SMS Passcode servers to communicate with each other. This RADIUS shared secret should be something completely different. Make sure to copy it out, you will need it later when configuring your NetScaler authentication policy.
Using the NetScaler to load balance RADIUS requests
Configuring your NetScaler RADIUS Authentication Policy
67. Give it a name and give it the IP address of the load balanced vserver you created earlier. Set the port to 1812 and add the secret key you added on your NPS server console earlier. Then hit Test Connection. It should light up green if everything is good. If something is wrong it will go red and tell you in plain English at what step it failed. The timeout value is by default 3 seconds but you’ll want to extend this depending on the type of MFA methods you allow so people have time to respond to the 2nd factor. In this example I’m just setting it to 120 seconds (2 minutes). Don’t hit Create yet.
68. This is where configuring a some other kinds of RADIUS servers vs. an SMS PASSCODE backed RADIUS server differs. Hit that little button that says More and click the “Send Calling Station ID” check box. The Calling Station ID is part of RFC 2058 that defines the Remote Authentication Dial In User Service (RADIUS) protocol from way back in January 1997 (think dial-up age). It allows the RADIUS request to contain the actual IP address that the RADIUS request comes from. Now you can hit Create.
Bind your RADIUS policy to the NetScaler Gateway vserver
71. Now go to your NetScaler Gateway vserver. In this example I was using an LDAP policy and I now need to migrate to our new RADIUS policy. Just leave LDAP under there for now, click on the plus button next to Basic Authentication. Notice I have disabled Max Login Attempts and Failed Login Attempts for testing purposes. These are not set by default but I always recommend you set them in a production deployment.
Testing an authentication attempt through your NetScaler Gateway
Troubleshooting SMS PASSCODE Authentication Issues
80. As always aaad.debug is the the go to answer for troubleshooting NetScaler Gateway authentication issues. If you’re new to NetScaler Gateway, just SSH into your NetScaler using Putty and enter:
and then attempt to login to your NetScaler Gateway. You will see what’s going on with the login request in detail in your Putty window.
82. If you do not see it there that means it’s getting blocked before even hitting the Dispatcher. Go to the Event Viewer on your SMS PASSCODE server and expand out the Applications and Services Logs. There is a custom event log there called “SMS PASSCODE Authentication Backend Service”. Here you will see all the requests being sent through the NPS RADIUS server and the reason why the requests are failing. You can also see RADIUS related logs in the “SMS PASSCODE RADIUS” log which will have more detailed info on each authentication attempt.
Advanced Policies, Self-service, and Password Reset Website
So now you’ve done a very basic SMS PASSCODE setup. From here you can get very granular with your adaptive MFA policies and setup location based authentication, trusted locations vs. untrusted locations, time of day, etc. You can be extremely granular on the conditioning you can do with your rules. You can even chain the OTP methods together in your rules so if the user doesn’t respond to one form of authentication, a secondary option is tried. If they don’t respond to the secondary and tertiary is tried. A great use case is when flying. You won’t get a text message on your phone but if you have Internet on your laptop, you can fallback to an email based authentication. If that doesn’t work you can fallback to OATH or a soft or hard token if the user is carrying one with them.
The other pieces you may have a need to deploy are the Self-service and Password Reset website roles we had skipped earlier during the install portion. The Self-service website will allow users to enter their cell phones into the system if AD doesn’t have them. They can also provide secondary cell phone numbers, changed their preferred authentication method, setup an emergency override code if they can’t authenticate using other means, etc. The Password Reset website will help keep calls to your help desk at a minimum. When the user’s AD account gets locked out, they’ll get a text or email to the password reset website. They get authenticated through MFA and then they can reset their AD user account password.
I hope this guide helps you get started with your SMS PASSCODE/CensorNet MFA deployment. If you have any questions please leave a comment below. If you would like to see more advanced policies or how to deploy the other roles like Self-service or Password Reset let me know in a comment below and I will be happy to do a follow-up post. 🙂