MFA One Time Pass-code Provider
- OTP passcodes can be used with 25 users for free.
- Support of ADFS CSS themes
- Enable self-registration with QR code (using free Microsoft Authentication, Google Authentication, Symantec VIP etc. mobile apps)
- Logs are stored in Windows application log
- Runs on ADFS 2016 and ADFS 2019 servers
Licensed version (additional features)
- OTP passcodes for unlimited user accounts of licensed organization.
- QR code encryption with AES 256-bit encryption.
- Configuration of network locations from which user can scan QR code.
- Can run without MS SQL service.
- Offline QR code generator (Integrated into adapter)
- Text customization for adapter interface.
- OTP account lockout feature.
- QR code customizations. (Advanced configuration)
- Free version notes are removed.
Deploy SecureMfaOtp adapter into AD FS farm
Before you can start registering “SecureMfaOtpProvider” into your ADFS farm you must complete bellow steps. All commands must be executed in elevated PowerShell (PS) command prompt.
1) Deploy latest “SecureMfaOtpprovider” PowerShell module from Microsoft PSGallery using bellow PS command.
Install-Module -Name SecureMFA_OTP -Repository PSGallery -Scope AllUsers
NOTE: If your ADFS server doesn’t have access to the Internet you can pull PowerShell module from Windows client which will have Internet access and copy “C:\Program Files\WindowsPowerShell\Modules\SecureMFA_OTP” folder from client’s computer into ADFS server (same location).
As alternative you can download “SecureMFA_OTP” nupkg file manually from https://www.powershellgallery.com/ website. Rename nupkg file’s extension into ZIP. Unzip content into a folder “SecureMFA_OTP” and place it into PS Modules default location on the server. That will work the same way as pulling package with native windows PS Tools.
2) Within “C:\Program Files\WindowsPowerShell\Modules\SecureMFA_OTP” directory you will find “sql_Create_Database_SecureMfaOTP.txt”
Modify FILENAME location to reflect your sql server storage configuration. Open the script in SQL manager and execute it. This will create a new SQL database for “SecureMfaOtpprovider”
3) Within “C:\Program Files\WindowsPowerShell\Modules\SecureMFA_OTP” directory update “SecureMfaOtpProvider.json” file.
If you are using a free license you only need to modify "sqlserver" server settings. If you will buy a license for unlimited users you will need to update "company" and "serialkey" information to unlock the app.
If you are not running your ADFS servers using service account and you cannot use SQL integrated security to access database, you need to change:
"sqlintegratedsecurity": "false“ and update "sqluseraccount" and "sqluserpassword" with relevant information.
4) If you need to generate verbose logs in windows events for troubleshooting reasons change verboselog value from “false” to “true”. Please note that verbose logging can affect your servers’ performance, use it only for troubleshooting reasons. Don’t enable “verboselog” in production environments as it may reveal configuration secrets
Using SQL manager provision dbo access to “SecureMfaOTP” database for ADFS service account or SQL user.
Below is a sample of a SecureMfaOtpProvider.json file
"lockout_minutes" : "5",
SecureMfaOtp adapter installation
Before a SecureMfaOtpprovider will be invoked by AD FS, it must be registered in the system. with PowerShell command which performs the necessary installation actions including installation in the GAC, and registration in AD FS farm.
Primary ADFS node
Bellow command will install OTP authentication provider on the MAIN ADFS node.
Other ADFS node(s)
Bellow command will install OTP authentication provider on OTHER ADFS node(s).
NOTE: If you are using federation server farm that uses Windows Internal Database, you must start installation using the primary federation server of the farm as a MAIN node. Installation needs to be executed on ADFS farm server (not web application proxy servers).
To verify if “SecureMfaOtpProvider” has been installed successfully.
1) Open the AD FS Management Snapin (from Server Manager Tools menu)
2) Click Authentication Policies at left
3) In the center pane, under Multi-Factor Authentication, click the blue Edit link to the right of Global Settings.
4) Under Select additional authentication methods at the bottom of the page, check if “Time Based OTP Authentication Provider” is selected.
When you will login into your ADFS application which requires multifactor authentication first time user will see QR coder which can be scanned with any authenticator which is based on RFC6238 ( a Time-Based One-Time Password (TOTP) Algorithm). This algorithm is used in Google's Authenticator, Microsoft Authenticator, Symantec VIP and potentially in many other time-based authenticators.
Below is print screen of SecureMFA OTP provider.
After user’s successful logon using OTP code, QR code will never be displayed unless user’s account is deleted from “Secrets” table in SQL or “logon” value is updated to 0
This feature only works for licensed adapters. If you set “login_failures” more than a zero in SecureMFA database you will see failed user authentication attempts. When user reaches “failedlogoncount” number of attempts set in “login_failures” value user’s account will be locked out for a period of time set in "lockout_minutes" . If you want to disable this feature you must set “login_failures” to zero. All values are configured in SecureMfaOtpProvider.json file.
SecureMfaOtpProvider.json config settings to enable 5 min lockouts for 15 failed OTP passcode attemps :
"lockout_minutes" : "5"
Encryption only works for licensed adapters. AES 256-bit encryption is created with AesManaged class in the System.Security.Cryptography module: This class uses Windows CryptoAPI (CAPI) which uses FIPS-compliant .NET Assemblies. The cipher mode is Cipher Block Chaining (CBC). The passphrase can be configured in configuration file and it is recommended to be between 16-18 random characters. It is salted with 16 bytes string, zero padding and 4 key iterations. Full documentation on “AesManaged .NET class” can be found in Microsoft documentation for “System.Security.Cryptography.AesManaged“ constructors)
SecureMfaOtpProvider.json config settings to enable encryption:
When it is enabled your secret code is encrypted in Database and it looks like bellow.
Licensed clients can customize adapter text which is presented to the users during logon. You can use some simple html code like links to provide users with self-service portal links etc. Text customizations are configured in “SecureMfaOtpProvider.json” file.
NOTE: "ui_customization" must be set to "true" for bellow changes to take effect.
"ui_first_login_text": "Please configure your Authenticator Application (Microsoft Authenticator, Google Authenticator, Symantec VIP etc.) using the QR code below."
"ui_login_text": "Enter the passcode generated by your authenticator application."
Configuration of network locations for QR code
Licensed clients can customize from which network locations users can scan their QR code for mobile device configuration.
Allowed network locations are configured in “SecureMfaOtpProvider.json” file.
NOTE: "ui_customization" must be set to "true" for bellow changes to take effect. List of locations must be specified as indicated in bellow format (SubnetID/MASK) and each location is separated by semicolon.
All successful second factor authentication sessions will issue a new Actual Authentication method value: http://schemas.microsoft.com/ws/2008/06/identity/claims/authenticationmethod
QR code customizations
Licensed clients can customize QR code generated text and set advanced features for Authenticator software. QR image is presented to the user during first logon and allows to enrol user’s Authenticator device to generate OTP codes for the user. With customization settings enabled you can change QR code generator endpoint from Google API (which is default QR code generator for SecureMFA OTP adapter) to any other vendor or internal QR service. Any advance settings specified in QR customizations must be supported by OTP Authenticator software. Some OTP Authenticator software do not support QR codes with advance settings, some of them will ignore settings like SHA256 passphrase encryption on the client etc. Most popular OTP Authenticator clients defaults to SHA1 encryption and use 30 seconds period to display OTP code. .
To enable customization set:
Enable Offline QR Generator
To enable offline QR generator which comes as integrated feature with adapter you need to set:
"totp_offline_qr_enable": "true" (note it must be used together with above setting)
This is most secure option as user’s secret doesn’t travel over internet to service provider to request QR code image for user’s secret key.
Additional customization settings can be done if your QR coder reader supports advanced QR customization.
To configure higher encryption of secret on QR client you can change “totp_offline_qr_algorithm” value to be SHA256 or SHA512.
"totp_offline_qr_algorithm": "SHA1" (default and has best support across major OTP client vendors)
Bellow setting must always be set to be 30 seconds unless you have specific requirements to configure your QR client with different time period.
Bellow settings specifies HTML image size which will be displaying QR code, it must not be smaller than a size setting used in QR endpoint URL. It is recommended to match values.
If you need to hide user’s account prefix information as additional security feature on client’s device. Set “totp_remove_user_prefix” in json config file to be “true”
Bellow pictures shows how it looks with enabled and disabled user’s prefix on Authenticator’s screen.
Enable OTP codes with Active Directory
This feature is only available for licensed OTP providers. It allows to store User OTP attributes in Active Directory domain. This removes dependency and cost of having MS SQL service configuration to store OTP database. To enable this feature, you have to update SecureMfaOtpProvider.json file to enable AD mode and update encryption passphrase with your custom string which will be used to encrypt secret data in AD attribute. AD mode doesn’t support unencrypted secrets.
You will have to execute following script “Create_SecureMFA_OTP_AD_attributes.ps1” which comes with OTP provider on Read-Write domain controller. You need to execute this script on Read-Write domain controller with AD account which is member of Schema Admins group. SecureMFA OTP provider when operates in AD mode it requires custom Active Directory (AD) attributes to be created to store OTP data for the user. This action cannot be undone and needs to be tested in your TEST domain first before moving into PRODUCTION. New AD Schema Attributes will be added into custom SecureMFA Auxiliary Class and that Class will be added into Existing User Class as AD Schema best practices suggest. OID numbers for custom attributes are from SecureMFA Private Enterprise range assigned by iana.org . Which do not overlap with other vendors OIDs numbers used to create custom AD attributes.
Note: THIS ONLY REQUIRES IF YOU PLAN TO RUN SecureMFA OTP Provider in AD MODE.
Bellow print screen shows how AD user’s custom attributes will look like.
Enable API endpoint for QR Generator
Endpoint for QR generator API is specified under "totp_api_endpoint" value. (NOTE, it is only accessed by client computers, most likely user’s browser will need to access this endpoint to retrieve QR image, and this configuration only works when "totp_offline_qr_enable" is set to "false". Otherwise offline QR generator configuration takes precedence). It must be specified with all mandatory parameter values in URL which are required by a vendor. Only vendors who specifies TOTP settings under “otpauth://totp/” configuration will work. It must support following format: otpauth://[TYPE]/[KEY NAME]?secret=[KEY SECRET, BASE 32]&issuer=[ISSUER] . All those settings will be generated by SecureMFA OTP adapter and amended into API endpoint URL. Issuer and Label information will come from licensed company name. Not licensed adapters will show www.securemfa.com as issuer information.
Any advance settings which are supported by QR generator and client authenticator software must be specified under bellow setting. Set all required parameters separated by & symbol.
More details on advanced QR configuration can be found HERE
Below is a sample of json configuration file which will work with qrserver.com API. It is another free QR image generator service available on the internet.
Final URL for API endpoint to the user is unique. Below is a sample how properly formatted URL for QR image will look like:
All provider related logs are stored in Windows Application Event logs and som in SQL table.
Windows Application Event:
Source: Secure MFA OTP
Event ID 5550: Configuration Logs
Event ID 5552: Successful Events
Event ID 5553: Failed Events
[lastlogon] – Time stapm of last successful logon;
[logoncount] – Total number of successful user logons;
[failedlogoncount] – Number of failed logons in a row;
[failedlastlogon] - Time stamp of last failed logon;
[failedcode] – Last failed user’s input;
[logonip] – IP address of remote user;
[useragent] – Details of user’s agent details from last logon;
Deployment of a new version can be done by pulling latest version from PowerShell Gallery by using bellow command:
Install-Module -Name SecureMFA_OTP -Repository PSGallery -Scope AllUsers -Froce
You’ll need to repeating all deployment steps as it was done for original installation. If it is highlited in deployment notes that attribute store needs to be extended for OTP data, you’ll need extra step to complete your upgrade.
· If you are using to store your user OTP data in MS SQL you may need to execute “sql_Upgrade_From_Previous_Version.txt” on your SQL database.
· If you are using to store your user OTP data in AD you may need to execute “Create_SecureMFA_OTP_AD_attributes.ps1” on your Domain controller. (this usually is highlighted in a new release documentation)
Files can be found in a directory with other installation files. This will add any extra missing columns/attributes in the Database or AD.