MS Windows OTP Provider

The SecureMFA WIN authentication provider is wrapping 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. The server OS minimal version must be Windows 2016, and the Client OS minimal version must be Windows 10.

Unlicensed version

Licensed version (additional features)

Deploy SecureMfa WIN OTP Provider on Windows OS


Prerequisites

NOTE: For security reasons, end-user devices with “WIN OTP Provider” installed don’t allow users to be enrolled for a TOTP account. Please check the "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 a Windows device. All commands must be executed in an elevated PowerShell (PS) command prompt.

1) Deploy the latest “SecureMfa_WIN_OTP” PowerShell module from Microsoft PSGallery using below PS command:

Install-Module -Name SecureMFA_WIN_OTP -Repository PSGallery -Scope AllUsers

NOTE: As of April 2020, the PowerShell Gallery no longer supports a TLS protocol lower than 1.2. Hence, if your servers don’t have GPO changes to reflect this requirement, you may need manually to enforce TLS 1.2 for PowerShell sessions by using below command 

[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12

If your server/workstation doesn’t have access to the Internet, you can pull the PowerShell module from the Windows client which has Internet access using the PS command:

Find-Module -Name "SecureMFA_WIN_OTP" -Repository "PSGallery" | Save-Module -Path "C:\"

Copy C:\SecureMFA_WIN_OTP folder from the client’s computer into “C:\Program Files\WindowsPowerShell\Modules\SecureMFA_WIN_OTP”

As an alternative, you can download the “SecureMFA_WIN_OTP” nupkg file manually from the https://www.powershellgallery.com/  website. Rename the nupkg file’s extension to ZIP. Unzip the content into a folder named “SecureMFA_WIN_OTP” and place it in the PS Modules default location on the server. That will work the same way as pulling the package with native Windows PS Tools.

2) Before Windows invokes the authentication provider, it must be registered in the system with a PowerShell command, which performs the necessary installation actions, including installation into the GAC and registration with DCOM interfaces, which are required for authentication.

The bellow command installs SecureMFA WIN OTP Provider on Windows for RDP sessions only (Console access is not affected) and points the provider to the API endpoint URL, which is used for OTP code validations. To lock down Windows OS with MFA for all sessions, you must use the -RDPonly $false parameter. The anchor parameter specifies the OTP user’s suffix, which is used in the “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" — The self-service password portal (SSPR) URL for corporate users, which the provider will use for the “Change Password” link. If the parameter is not set during the provider’s installation, it will use a host part from the 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” — The number of days offline secret synchronization is valid for TOTP authentication before the user synchronises data from the SecureMFA SSPR Portal API endpoint. 0 disables the offline authentication feature.

“totp_offline_ui_login_failures” — When the offline authentication feature is enabled, this counts the number of failed OTP logon attempts before the TOTP user is locked for the number of minutes set under “totp_offline_ui_lockout_minutes.” 0 disables the disabled TOTP user lockout feature.

“data_encryption_passphrase” - is a passphrase used to decrypt API responses and local data used for offline authentication. This setting only works for licensed adapters, and all unlicensed providers will use the 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 the setting of proxy names for API calls if required.

“api_proxy_server” - If proxy, enable FQDN for the proxy name.

“api_proxy_port” - If the proxy is enabled, provide the port number for the proxy.

“verboselog” - (True/False) Enables verbose logging for the provider on the installed system.

Verification

This is to verify if “SecureMfa WIN OTP Provider” has been installed successfully.

RDP into your workstation and confirm that you must enter the TOTP code with your standard credentials.

OTP Account Creation for Users

Windows OTP Provider enforces second-factor authentication in addition to the user's password to ensure strong authentication. The user must enrol their mobile device by scanning the QR code with a mobile application like Google's Authenticator, Microsoft Authenticator, Symantec VIP, and potentially many other time-based authenticators that support RFC6238 ( a Time-Based One-Time Password (TOTP) Algorithm).

Windows OTP Provider can’t generate QR codes for enrolment, but you can enrol users by using one of the following options:

Option 1:

Install ADFS with OTP Provider and Web Portal for users' self-service OTP enrollment. For more details, click HERE.

Option 2:

Create OTP accounts in the SQL database manually using the “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. When TOTP validation is performed against the SecureMFA SSPR Portal API endpoint for online lockouts, the setting will not have any impact as SecureMFA SSPR Portal configuration settings will dictate lockout behaviour. If you set “totp_offline_ui_login_failures” to more than a zero and the user reaches this number of attempts during offline TOTP authentication, the user’s account will be locked out for a period of time set in " totp_offline_ui_lockout_minutes" . 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 for offline authentication.  AES 256-bit encryption is configured with the .NET wrapper side using the publicly 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 the API endpoint may not be accessible when the device travels to remote locations, you can enable OTP offline logins by setting the “totp_offline_secret_valid_days” value above zero. Users can synchronise secret data, which is required to validate TOTP codes when the device is used offline.

The user must have a valid TOTP code to receive the account’s secret data, and the “SecureMFA SSPR Portal API endpoint” must be accessible. Data received in HTTP messages and later stored locally for offline use is always encrypted and validated against tampering or packet replay attempts.  

 The value set in “totp_offline_secret_valid_days” indicates how long offline secret synchronization is valid for TOTP authentication before the user resynchronises data from the SecureMFA SSPR Portal API endpoint. 0 – disables offline authentication feature.

Values must be set as parameters for Install-SecureMFA_WIN_OTP_AuthenticationProvider PS command.

To synchronize an offline OTP account, you must enter only the username value for the OTP user you want to synchronise on the computer for offline logins and the valid user’s OTP code. The username value is joined with the anchordnsname value issued to your licence. If the OTP code is valid for the user, a secret key for offline use is replicated and encrypted on the user’s computer from the “SecureMfaAOTP” database. You can replicate multiple user’s OTP data onto a computer using the below interface as long as you have a valid OTP code for each user.

Change Password - LINK 

If the password has expired or has been set to be changed on the next logon, the user must use the Self-service password portal (SSPR) to update expired password details before continuing to log in. To access a corporate SSPR portal, the user must click on the “Change Password” link, which will bring the user to an SSPR portal set during the provider’s installation. 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, your device must have the latest Google Chrome browser installed. To validate that your system has the Google Chrome browser installed, please check if “C:\Program Files\Google\Chrome\Application\chrome.exe” exists on the host.

The “Change Password” link will start the Microsoft Chrome Browser in KIOSK mode, which will point to the URL set by the $sspr_url parameter during installation or the default location. KIOSK mode starts the browser in full screen, and when the user completes the password change operation, they will need to press CTRL+F4 on a keyboard to close the browser and continue with the Windows login process.

NOTE: On older provider versions before 2.0.1.2, Microsoft Edge was a supported browser.

For the “Change Password” link to work correctly, you must ensure that your device has installed the latest Microsoft EDGE browser. For Windows 10, it is recommended to use the 20H2 update and upwards, as this release has a new EDGE browser by default. If you are using an older version of Windows, you must 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” exists on the host.

Browser Updates

Microsoft Edge Browser updates must be under your organization's control with GPO to avoid issues with the "Change Password" link. The latest version may change the browser's behaviour, affecting the "Change Password" link. 

The stable Google Chrome release of 124.x.x.x major version works fine with Windows 10 or Windows 11 OS. You must return to the previously working version if your OS has an auto-updated Google Chrome browser. 

For older providers before the 2.0.1.2 release

The stable MS EDGE release of 94.x.x.x major version works fine with Windows 10 or Windows 11 OS. If your OS has an auto-updated MS Edge browser, you can roll it back to the previous version by following the EDGE Rollback documentation.

Uninstall

To uninstall “SecureMFA WIN OTP Provider”, use the below PS command. This will unregister the custom provider and set the original Windows authentication providers as the main ones.

Uninstall-SecureMFA_WIN_OTP_AuthenticationProvider

Security

Secrets and identity data are always encrypted in TRANSIT and REST using AES 256-bit encryption.

Each API request has a unique state value that is encrypted with data. This allows it to be validated against HTTP packet tampering or packet replay attempts. 

Logs

The below system events in the 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 stay current with the 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 the latest version from PowerShell Gallery by using below command:

Install-Module -Name SecureMFA_WIN_OTP -Repository PSGallery -Scope AllUsers -Froce

You’ll need to repeat all deployment steps as they were done for the original installation. 


The following steps are recommended when upgrading an old provider version to the latest one on a computer:

Bellow PowerShell commands must be executed in an elevated command prompt.

Deployment Architecture

Deployment Video

Bellow video shows how quickly you can setup required components to enable MFA authentication on a Windows device.