MS Windows OTP Provider
SecureMFA WIN Authentication Provider is a wrapping of TOTP authentication onto a native windows authentication provider. It allows requesting users to enter a one-time passcode generated on their phones via authenticator applications like Microsoft Authenticator, Google Authenticator, Symantec VIP, etc., as second-factor authentication in addition to their windows password. Windows MFA provider works with standalone and domain-joined workstations or servers. The provider is developed by using Windows authentication plug-in architecture. More details about this architecture and how the new credential provider model works can be found HERE.
Features
SecureMFA WIN Authentication Provider supports Windows x64 platforms only. Servers OS minimal version must be Windows 2016 and Client OS minimal version must be Windows 10.
Unlicensed version
TOTP code validation for 24 user accounts.
TOTP API message decryption with AES 256-bit encryption key.
Header authentication against API endpoint.
API response message protection against replay or tampering.
“Change Password” link to Self-service password portal (SSPR) URL.
Licensed version (additional features)
TOTP code validation for unlimited user accounts
TOTP Offline authentication.
TOTP account lockout feature.
Deploy SecureMfa WIN OTP Provider on Windows OS
Prerequisites
A Self-service password reset portal (SSPR) installed on a windows server with API Interface enabled. Portal deployment information can be found under MFA-SSPR Section.
Windows server 2016 / 2019 or Windows 10 x64 for MFA provider installation
NOTE: For security reasons end user devices with “WIN OTP Provider” installed doesn’t allow to enrol user for TOTP account. Please check "OTP Account Creation for Users" section for more details.
Installation steps
Before you can start using MFA authentication on Windows OS you must deploy “SecureMfa WIN OTP Provider” on Windows device. All commands must be executed in elevated PowerShell (PS) command prompt.
1) Deploy latest “SecureMfa_WIN_OTP” PowerShell module from Microsoft PSGallery using bellow PS command:
Install-Module -Name SecureMFA_WIN_OTP -Repository PSGallery -Scope AllUsers
NOTE: As of April 2020, the PowerShell Gallery no longer supports lower than 1.2 TLS protocol. Hence if your servers don’t have GPO changes to reflect this requirement you may need manually to enforce TLS 1.2 for PowerShell session by using bellow command
[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
If your server/workstation doesn’t have access to the Internet you can pull PowerShell module from Windows client which has Internet access using bellow PS command:
Find-Module -Name "SecureMFA_WIN_OTP" -Repository "PSGallery" | Save-Module -Path "C:\"
Copy C:\SecureMFA_WIN_OTP folder from client’s computer into “C:\Program Files\WindowsPowerShell\Modules\SecureMFA_WIN_OTP”
As alternative you can download “SecureMFA_WIN_OTP” nupkg file manually from https://www.powershellgallery.com/ website. Rename nupkg file’s extension into ZIP. Unzip content into a folder “SecureMFA_WIN_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) Before authentication provider will be invoked by Windows, it must be registered in the system. with PowerShell command which performs the necessary installation actions including installation into the GAC, and registration with DCOM interfaces which are required for authentication.
Bellow command installs SecureMFA WIN OTP Provider on Windows for RDP sessions only (Console access is not affected) and points provider to API endpoint URL which is used for OTP codes validations. To lock down Windows OS with MFA for all sessions you must use -RDPonly $false parameter. Anchor parameter specifies OTP user’s suffix which is used in “SecureMfaOTP” database.
Install-SecureMFA_WIN_OTP_AuthenticationProvider -anchordnsname "adatum.labnet" -RDPonly $true -api_endpoint “https://awebapi.adatum.labnet/api/securemfaotp”
Available parameters:
“anchordnsname” - Anchor parameter specifies TOTP user’s suffix which is used in “SecureMfaOTP” database.
“serialkey” and “subscriptionid” - details to license adapter, it unlocks licensed provider features.
“api_endpoint” - SecureMFA WEB API Portal API endpoint.
“api_timeout” - Timeout value in milliseconds for API response.
"sspr_url" - Self-service password portal (SSPR) URL for corporate users which will be used by provider for “Change Password” link. IF parameter has not been set during the provider’s install it will use a host part from API endpoint URL for the default SSPR Portal address URL.
“RDPonly” - (True/False) Enable only RDP session for MFA on the device.
“totp_offline_secret_valid_days” - How long offline secret synchronization is valid for TOTP authentication before user must resynchronise data from SecureMFA WEB API Portal API endpoint. 0 – disables offline authentication feature.
“totp_offline_ui_login_failures” - When offline authentication feature is enable, this counts number of failed OTP logon attempts before TOTP user is locked for number of minutes which are set under “totp_offline_ui_lockout_minutes” . 0 – disables disabled TOTP user lockout feature.
“data_encryption_passphrase” - A passphrase which is used to decrypt API responses and local data which is used for offline authentication. This setting only works for licensed adapters and all unlicensed providers will use following passphrase for encryption and decryption operations: "d9GhT=7=Ox8-+LaZ",
“api_headers_value” - random string value which is used for header authentication against SecureMFA WEB API Portal API endpoint.
“api_proxy_enable” - (True/False) Allows to set proxy name for API calls if required.
“api_proxy_server” - If proxy enable FQDN for proxy name.
“api_proxy_port” - If proxy enable port number for proxy.
“verboselog” - (True/False) Enables verbose logging for provider on installed system.
Verification
To verify if “SecureMfa WIN OTP Provider” has been installed successfully.
RDP into your workstation and confirm that you require to enter TOTP code together with your standard credentials.
OTP Account Creation for Users
Windows OTP Provider enforces second factor authentication in addition to user's password to enforce strong authentication. User must enroll mobile device by scanning QR code with mobile application like Google's Authenticator Microsoft Authenticator, Symantec VIP and potentially in many other time-based authenticators which supports RFC6238 ( a Time-Based One-Time Password (TOTP) Algorithm).
Windows OTP Provider doesn’t have ability to generate QR codes for enrolment , but you can enroll users by using one of the following options:
Option 1:
Install ADFS with OTP Provider and Web Portal for Users self-service OTP Enrolment. For more details click HERE.
Option 2:
Create OTP accounts in SQL database manually using “SecureMFA Tools” PS command - New-xOTP_User For more details click HERE
User Lockouts
This feature only works for licensed providers when performing offline TOTP authentication. For online lockouts when TOTP validation is performed against SecureMFA WEB API Portal API endpoint the setting will not have any impact as lockout behaviour will be dictated by SecureMFA WEB API Portal configuration settings. If you set “totp_offline_ui_login_failures” more than a zero and user reaches this number of attempts during offline TOTP authentication user’s account will be locked out for a period of time set in " totp_offline_ui_lockout_minutes" . If you want to disable this feature you must set “totp_offline_ui_login_failures” to zero.
Values must be set as parameters for Install-SecureMFA_WIN_OTP_AuthenticationProvider PS command.
Encryption
It is used to decrypt API responses and local data which is used for offline authentication. AES 256-bit encryption is configured with the .NET wrapper side by using public sealed class AesCng: System.Security.Cryptography.Aes. It provides a Cryptography Next Generation (CNG) implementation of the Advanced Encryption Standard (AES) algorithm and allows to run provider when FIPS compliant algorithms for encryption are enforced on the Windows platform. The cipher mode is Cipher Block Chaining (CBC). The passphrase can be configured in the 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 “AesCng .NET class” can be found in Microsoft documentation (https://docs.microsoft.com/en-us/dotnet/api/system.security.cryptography.aescng)
Values must be set as parameters for Install-SecureMFA_WIN_OTP_AuthenticationProvider PS command.
To enforce Windows Operating System cryptography to use FIPS compliant algorithms for encryption, hashing, and signing run bellow command in elevated PowerShell (PS) o a server. More details on the policy can be found by following link: System cryptography: Use FIPS compliant algorithms for encryption.
New-ItemProperty -path 'HKLM:\System\CurrentControlSet\Control\Lsa\FIPSAlgorithmPolicy' -name 'Enabled' -value 1 -PropertyType 'DWord' -Force; Restart-Computer -Force;
Enable Offline TOTP validations
This feature only works for licensed providers. To allow offline TOTP validation when API endpoint may not be accessible when device travels to remote locations. You can enable OTP offline logins by settings “totp_offline_secret_valid_days” value above zero. Users can synchronise secret data which is required to validate TOTP codes when device is used offline.
User must have a valid TOTP code to receive account’s secret data and “SecureMFA WEB API Portal API endpoint” must be accessible. Data which received in HTTP message and later stored locally for offline use is always encrypted and validated against tampering or packet replay attempts.
Value set in “totp_offline_secret_valid_days” indicates how long offline secret synchronization is valid for TOTP authentication before user must resynchronise data from SecureMFA WEB API Portal API endpoint. 0 – disables offline authentication feature.
Values must be set as parameters for Install-SecureMFA_WIN_OTP_AuthenticationProvider PS command.
To synchronize OTP account offline, you must enter only the username value for OTP user which you want to synchronise on the computer for offline logins and the valid user’s OTP code. Username value is joined with anchordnsname value issued to your licence and if OTP code is valid for the user secret key for offline use is replicated and encrypted on the user’s computer from “SecureMfaAOTP” database. You can replicate multiple user’s OTP data onto a computer using the bellow interface as long as you have a valid OTP code for each user.
Change Password - LINK
If the password has been expired or has been set to be changed on the next logon user must use the Self-service password portal (SSPR) to update expired password details before continuing to login. To access a corporate SSPR portal user needs to click on “Change Password” link which will bring the user to an SSPR portal set during the provider’s install. If $sspr_url parameter has not been set during the provider’s install it will use a host part from API endpoint URL for the default SSPR Portal address URL.
IMPORTANT: For the “Change Password” link to work correctly you must ensure that your device has the latest Microsoft EDGE browser installed. For Windows 10 it is recommended to use 20H2 update and upwards as this release has a new EDGE browser by default. If you are using an older release of Windows you will need to download and install the latest Microsoft Edge Browser from Microsoft. To validate that your system has EDGE browser installed please check if “C:\Program Files (x86)\Microsoft\Edge\Application\msedge.exe” exist on the host.
“Change Password” link with start Microsoft Edge Browser in KIOSK mode which will point to URL set by $sspr_url parameter during install or default location. KIOSK mode starts browser in full screen and when user completes password change operation they will need to press CTRL+F4 on a keyboard to close a browser and continue with login process into windows.
Microsoft Edge Browser updates must be under control in your organization with GPO to avoid issues with the "Change Password" link. The latest version may change the browser's behaviour, affecting the "Change Password" link. Currently, we confirmed that a stable MS EDGE release of 94.x.x.x major version works fine with Windows 10 or Windows 11 OS. If your OS has auto-updated MS Edge browser, you can roll back it to the previous version by following EDGE Rollback documentation.
Uninstall
To uninstall “SecureMFA WIN OTP Provider” use bellow PS command. This will unregister custom provider and set original windows authentication providers as the main one.
Uninstall-SecureMFA_WIN_OTP_AuthenticationProvider
Security
Secrets and identity data is always encrypted in TRANSIT and REST using AES 256-bit encryption.
Each API request has unique state value which is encrypted with data. It allows to validated against HTTP packet tampering or packet replay attempts.
Logs
The below system events in Windows Event log may be used to verify and troubleshoot SecureMfa WIN OTP Provider:
Windows Application Event:
Source: SecureMFA WIN OTP
Event ID 5550: Successful Configuration Events
Event ID 5551: Failed Configuration Events
Event ID 5552: Successful Provider Events
Event ID 5553: Failed Provider Events
Event ID 5556: Successful OTP Events
Event ID 5557: Failed OTP Events
Patching and Upgrades
Provider is highly integrated with MS Framework classes and uses Windows OS components to deliver functionality.
To keep up to date with latest security updates you must constantly update your Operating System and MS Framework components using Microsoft Security updates.
For any feature updates please upgrade a provider by pulling latest version from PowerShell Gallery by using bellow command:
Install-Module -Name SecureMFA_WIN_OTP -Repository PSGallery -Scope AllUsers -Froce
You’ll need to repeating all deployment steps as it was done for original installation.
Following steps are recommended when upgrading an old provider version into a latest one on a computer:
Bellow PowerShell commands must be executed in an elevated command prompt.
Update registry to remove MFA requirement for console logins: Set-ItemProperty -Path "HKLM:\Software\SecureMFA" -Name "win_rdponly" -Value 1
Restart computer
Log in with local administrator account using the console
Uninstall old provider: Uninstall-SecureMFA_WIN_OTP_AuthenticationProvider
Delete old provider installtion source files: Remove-Item –path “c:\Program Files\WindowsPowerShell\Modules\SecureMFA_WIN_OTP” –recurse -force
Pull latest SecureMFA_WIN_OTP installtion source files: Install-Module -Name SecureMFA_WIN_OTP -Repository PSGallery -Scope AllUsers -Froce
Install new provider with your environment parameters: Install-SecureMFA_WIN_OTP_AuthenticationProvider
Deployment Architecture
Deployment Video
Bellow video shows how quickly you can setup required components to enable MFA authentication on a Windows device.