OTPEdit a management tool for One Time Passwords
With Citrix an ADC (Netscaler) there is the possibility from version 12 on for a Native One-Time-Password (OTP) integration with an Authenticator App (Google, Microsoft etc.) for two-factor authentication. The authenticator delivers a number as a second factor. The respective device (mobile phone with app) must can be registered for a user beforehand. Information on the OTP is stored in the user account of the respective user. The management of users and equipment is not always easy. Actually, with a GUI this can only be Users themselves on the Citrix Gateway. Therefore we have developed a tool for a central Management.
In this blog you will find the description of the tool, the tool itself and more Backgrounds.
 |
Why a second factor?
In environments that are accessed remotely, it has always made sense to Securing access by a second factor. The first factor is the password (knowledge) the second a device (possession). Nu with a combination of both should access to a protected corporate environment. Citrix has it as of version 12.1 of the Citrix Gateway enables instead of a hardware token a Mobile phone to generate the second factor (without an additional radius server) to use. The advantages are obvious:
- saving of costs for hardware tokens
- Quickly scalable - avoids loss of time
- We as Citrix Solution Provider can offer Citrix Gateway / ADC accesses and more cost-efficiently monthly rent (also in a higher edition). That works too, if no Citrix Virtual Apps & desktops are used. So the current bottleneck can be bypassed.
What is an OTP in the gateway and how is it used?
The login page on the gateway appears after setting up Native OTP with an additional field for the passcode. Here you can for example FreeOTP https://apps.apple.com/de/app/freeotp-authenticator/id872559395 or the Use Google Authenticator to generate the second factor for a login. Note: Image recognition works much better with Google Authenticator. A user can register a device by going to the Gateway with /ManageOtp. Ideally, a set of rules prevents this from happening even from can happen to the HomeOffice. Without a special tool (our tool) it works so far not otherwise.
Setting up Native OTP on a Citrix ADC
there are enough instructions for this. Gladly we can also help you here :-) Apart from that here is the most important information about the setup:
- Carl's excellent guidance on setting up: https://www.carlstalhood.com/netscaler-gateway-12-native-one-time-passwords-otp
- Restrict access to certain AD groups: https://support.citrix.com/article/CTX111079
- Citrix Netscaler Advanced (aka Enterprise) with firmware 12.1 build 49 and newer offers "native OTP" function and the possibility to configure "nFactor".
- Citrix Workspace App 1809 is required. Older receivers or older firmware versions (between 12.0 build 51.24 and 12.1 build 49)
Constraint: The Gateway in version 13.x also has the mentioned functions. However, the attributes are encrypted in ActiveDirectory. In principle we can implement something like this for the tool (maybe later). However it is it is possible to deactivate the encryption on Citrix Gateway 13.x.
OTP-Edit a management tool for OTP devices and users
For what has disturbed the OTP so far, we have now built a management tool. This tool offers the following usecases:
- Report all users who have configured a device for OTP access
- Finding users with an OTP
- Delete Central from assigned OTP devices (mobile phones) in Active Directory
- View and save the QR Codes for the Authenticator App
- Sending e-mails with the QR Codes for the Authenticator App
- New creation of QR codes with a randomly generated number and send them by E-mail. The user no longer needs to register himself at the gateway!
Instructions / Installation
The AD Powershell module must be installed. On a server can be done with the following command:
Add-WindowsFeature RSAT-AD-Tools -IncludeManagementTools
After the start a dialog with the standard settings from the local program directory in the file OTPEditConfig.xml. Here it is important, first of all, specify an LDAP server (the domain or domain controller).
If you use another LDAP attribute as "Userparameters", this is also configure. This makes sense, because in "Userparameters" also the remote desktop settings can be saved for a user account (if used)! For the tool to work properly, the field (UserProperties) empty or filled with one or more OTP device strings. Other Data lead to errors here.
Values like SMTP are, I think, self-explanatory and for the function at first not necessary.
After saving with "OK" a new configuration file is created under %appdata%\AndreasNick\OTPEdit is generated. So if something doesn't work, just... delete this file.
After loading and if everything is configured correctly, we see on the left Page Users who have an OTP device assigned to them. Via the tab "All Users all users in the domain are listed. With the search filter "Filter" you can selection can be restricted.
The "ExportCSV" function exports an overview of all users to whom devices are assigned. With the context menu (right mouse button) a new device can be be created.
"Add Device" shows a dialog in which the device name and the e-mail address to which the QR Code is to be sent. As e-mail address the AD attribute "Mail" is used. If this should not be set, the UserPrincipalName of the user account entered.
The device name must be unique and may not be retrieved for a user. With "Save" the QU code can be saved as PNG. "Send" on the other hand does several things. First, the device is entered in the Active Directory attribute. In this version, a dialog always appears with the PowerShell command which must be executed to change the attribute.
First after a successful entry in the AD object of the user the question after the e-mail has been sent.
The data from the configuration file is used for sending. If the GUI should freeze here or it takes a little longer, then the data is not correct. Please wait two minutes. After this time you will get an error message.
An e-mail looks like this:
Other functions like "Remove Device" and "View Device" behave similarly. In any case, the user is asked before an action is performed. With ViewDevice it is possible to a QR Code e-mail can be sent again.
e-mail dispatch
Even when sending e-mails and when formatting e-mails, it is not always possible everything must be taken into account. So I've written this part right into a little PowerSehll script outsourced. You can store this script in the program directory as you like. or use another method for sending the messages.
Function Send-QRCodeEMail
{
<#
.SYNOPSIS
A simple function to send notifications with a QRCode
#>
[CmdletBinding()]
param
(
[Parameter(Mandatory=$true)] [String] $SMPTServer,
[Parameter(Mandatory=$true)] [int] $SMTPPort,
[bool] $SMTPUseSSL = $True,
[String] $SMTPMailuser,
[String] $SMTPMailPassword,
[String] $From = "",
[Parameter(Mandatory=$true)] [String] $To,
[String] $Subject = "QRCode Mail",
[String] $UserName = "Rudi",
[Parameter(Mandatory=$true)] [Byte[]] $QRCode
)
$ImageBase64 = [Convert]::ToBase64String($QRCode)
$secure_pwd = $SMTPMailPassword | ConvertTo-SecureString -AsPlainText -Force
$creds = New-Object System.Management.Automation.PSCredential -ArgumentList $SMTPMailuser, $secure_pwd
#
# Als als html Mail
#
[String] $htmlDoc = $null
#Bachground
$htmlDoc += '<style>'
$htmlDoc += 'body {background-color:#d2E0EF;}'
$htmlDoc += 'h1 {color: blue;}'
$htmlDoc += 'strong {color:blue;}'
$htmlDoc += '* {font-family: Consolas;}'
$htmlDoc += '</style>'
$htmlDoc += '</head>'
$htmlDoc += '<body>'
#Headline
$htmlDoc += '<h1>OTP QR Code for: ' + $UserName + '</h1>'
$htmlDoc += '<h2>Please scan the code with an Authenticator (Microsoft, Google etc.)</h2>'
$htmlDoc += '<img src="/images/easyblog_articles/102/3b872e0cd0cb5d13d58aecd9984a326c.png" />'
$htmlDoc += '</body>'
Send-MailMessage -From $From -To $To -Subject $Subject -SmtpServer $SMPTServer -Port $SMTPPort -Credential $creds `
-Body $htmlDoc -UseSsl:$SMTPUseSSL -Encoding UTF8 -BodyAsHtml -ErrorAction Stop
}
Download
The tool is completely programmed in PowerShell and is implemented using the ISE-Seroids (http://powertheshell.com) The application is digitally signed and integrated into an exe ...arms. Among other things, a new basis for Citrix and AD management tools has been created here.
Important: we/I do not assume any liability for damage caused by the use of the of the tool. In the current version every action is queried again, before it is executed. The same hint is given again before the Download!
Version 1.0
* Additional Informations and a Link in OTP mails
* Some smal Bugfixes
Also directly runable as PowerShell. Here are the source codes on Github.
When you subscribe to the blog, we will send you an e-mail when there are new updates on the site so you wouldn't miss them.
Comments 32
Hello Andreas, I hope you are well. I'm late to finding this but it is fantastic. I'm wondering how difficult it would be for you to add a feature, or create a separate .PS1 file that can accept a .CSV file of SAMAccount names, and auto-email them with the QR code. I looked at the code and I can't seem to pull out all the pieces needed to make this happen. I'd like to enroll a large number of users at once is my reason. Thank you!
Sorry, the notification is still inactive because there was too much spam. I am planning a new version. Send me info on what functions you need. But I can't promise anything.
Hello, is there away to make the QR code time out? and also limit this QR code to only be usable once?
Thanks
If then as a configuration on the Citrix Gateway. I would also have to ask an expert
FYI. Immunet AV detects this file as a Mdrop trojan and removes / quarantines it.
Sorry, the notification is still inactive because there was too much spam. I am planning a new version. The PowerShell script in the directory does the same as the "Exe" file. PowerShell and PowerShell with Exe wrapper are often used for Trojans. Therefore, the tools that I also use generate the same header for the exe and all of a sudden everything is detected as a Trojan. You can just use the PowerShell script directly!
how do i use an smtp relay that does not require a username
You can write your own function. Maybe in dotnet. The script for sending e-mails is in the program folder.
Hi Nick
Thanks for your tool, it works great :-) i just have an additional question, actually the devices are limited to 3 per user. We have accounts, where we need to register more than 10 different devices. How can this be established? Thanks a lot, Stephan
Is there a limit? If I have installed one, I would have to look in the source code myself. Please send me an e-mail directly if it is not up to date.
Hello Andreas. Do you have any plan to develop the tool to be used with encrypted OTP data? How do you see?
Thank you. Andoni
As far as I know, the encryption is certificate-based with the key on the Citrix ADC. So this is not so easy to realize. However, the encryption can be disabled. I have never tested with the newer versions of the Citrix Gateway myself but I don't like to invest time here for now. If someone has an idea how we can realize this, he is welcome to contact me. Then I can implement it.
Thanks Andreas. I will investigate a little bit more, because I think (I have to ask to my support team) that really we are using a certificate that we have included in ADC, so we are able to use the key too... but I don't know how, I don't know hot to program this. In theory, we can have all the parts of the certificate that use in ADC, so if we will be able to choose the certificate and use, perhaps it can be done
Hi,
I have an extensive AD with 3t users.
Is there any way, how to set up LDAP on a specific OU?
Please demonstrate how to use filter to a specific username.
Thank you.
Hello Ovesny, currently not, but I put this on my ToDo list. It will not cost much effort.
Hello Andreas,
I was testing your tool, thanks a lot for sharing this. I was just wandering what could be the reason of this error:
I have used the UPN as username and the mail attribute for the email address. A few users do exist which were registered with the manageotp site and which also use the same names.
Do you have the possibility to help me further? Thanks a lot!
Günther
I have an error when i want to send a token : "invoke-expression au caractère ligne 1 : 224 ..." But i think it's a great tools
Thanks! I've had this kind of problem with customers before. For example the provider causes problems - with Goolgle only "secure" apps are allowed to send messages. Or there are problems with the proxy. For this reason, the script part that layers the email is a PowerShell snippet in the root directory. You can easily adjust everything here.
This tool looks great, but keeps crashing when I try to use it. I'd love to hear from you for further testing!
which configuration do you use? Which operating system and which PowerShell version ($PSversionTable). Could it be an antivirus? Are there log entries? I could send you a console version that might give you more information. Do you have time for that?