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
Great job! We will also use the tool instead of the /manageotp.
Would it simply be possible to send the "Secret" in text form with the e-mail?
We would like to leave it up to the user whether he takes a picture of the QR code or captures the secret manually.
Thank you! I can put that in. A URL should also be sent along. Just wait for the next version (next Week?). I'm curious if there are still bugs to be reported.
Hi Andreas,
Great work!
We also configured out netscaler with push, is this coming in the next release? Now, when we add a device via OTP-Explorer it only generates it for the passcode, push isn't working.
Do you mean sending by e-mail? Sending the QRCode should work. The PoSh script in the directory is used for this.Is SMTP configured correctly? You can also test it with Send-Mail on the command line or add something of your own to the script. For sending to groups I might build something later.
No, i mean the push service within the netscaler. We are offering our users the ability to logon via push notification or to type in the passcode manually. Your tool can only generate a QR for a passcode a guess, there's nothing written for the push service.
No, the tool does not interact with the gateway. All operations run in AD. I didn't plan anything there, either. But if there is a "simple" way to implement something then I am open for cool new functions
Nice work. We've had a basic batch load of OTP for a while, however while the OTP generation and management is fairly trivial, the integration of the QRcode generator is very convenient and make it a tool that Service Desks can use. I'm guessing the QRCode is the a substantial part of the code or are you leveraging a library?
I hope you change your mind on the source. Given it's a security app, a native script / uncompiled version will avoid the common malware concerns with PS compiled apps.
At least the QRCode generator is from the PowerShell gallery. The module uses encoded code. At least I would have to replace that with something else. Otherwise we'll wait and see what the community has to say and fix the problem. I can revise the code again and then at least reveal parts (or the all) of it.
Hi Andreas,
Thank you for your response. We have to need to publish this tool via Citrix for the Service Desk team, but the tool has the necessity to use an elevate permission user for work correctly. We have the need to RunAs the tool and customize the GUI to limit the Service Desk permissions.
Silvio
The tool does not have to run as administrator. But the user must have the right to change AD attributes. The Netscaler does this when an account gets a token.Do you use an administrator there? If it is absolutely necessary, you could also start the tool via a script. Otherwise we have the possibility to set a rake, so that the tool requests an administrator via the UAC.
Hi Andreas,
We have the interest to use this tool to bypass the manageotp native usage, but we have the interest to customize the GUI with some changes.
You have the possibility to share the source code or it's is not a possibility?
Thank you
Silvio Balduzzi
There's a reason I haven't published it "yet". I have developed some techniques here that simplify the use of reactive GUI elements and that I want to use for other tools. Also the code is currently quite confusing. The source code is a file with 200KB PowerShell code. During the development I separated and packed everything into modules but in the end it should be an exe. What do you need? Maybe I can help?