MS Windows OTP Provider

SecureMFA WIN Authentication Provider is a wrapping of TOTP authentication onto a native windows authentication provider. This allows requesting users to enter a one-time passcode, which is generated on their phones via authenticator application like Microsoft Authenticator, Google Authenticator, Symantec VIP etc. as second-factor authentication in addition to their password. Windows MFA provider works with a standalone and domain-joined workstations or servers. It 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 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)

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

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.

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.

  1. Update registry to remove MFA requirement for console logins: Set-ItemProperty -Path "HKLM:\Software\SecureMFA" -Name "win_rdponly" -Value 1

  2. Restart computer

  3. Log in with local administrator account using the console

  4. Uninstall old provider: Uninstall-SecureMFA_WIN_OTP_AuthenticationProvider

  5. Delete old provider installtion source files: Remove-Item –path “c:\Program Files\WindowsPowerShell\Modules\SecureMFA_WIN_OTP” –recurse -force

  6. Pull latest SecureMFA_WIN_OTP installtion source files: Install-Module -Name SecureMFA_WIN_OTP -Repository PSGallery -Scope AllUsers -Froce

  7. 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.