ADFS Email OTP Provider

OTP authentication for Microsoft Active Directory Federation Service (ADFS). It enables ADFS servers to provide multi-factor authentication (MFA) using a Time-Based One-Time Password (TOTP) Algorithm based on RFC6238. Using this MFA provider, users must enter a one-time passcode to complete a second-factor authentication login process. OTP code is delivered using SMTP service.

Features

Unlicensed version

  • Multi-language UI: English, Spanish, French, German, Chinese, Portuguese, Russian, Italian, Arabic, Turkish, Dutch, Finnish, Swedish, Norwegian, Polish, Danish and Lithuanian.

  • OTP pass-codes for 24 user accounts

  • OTP codes delivery using SMTP service

  • OTP user accounts deactivation

  • OTP data storage in MS SQL service

  • OTP validity length can be customized

  • Logs in Windows Applications Log

  • ADFS 2016 / ADFS 2019 / ADFS 2022 support

  • Support of ADFS CSS themes

Licensed version (additional features)

  • OTP pass-codes for unlimited user accounts

  • OTP data storage in MS Active Directory attributes or MS SQL Service

  • OTP account lockout

  • SSL and user authentication support for SMTP service

  • Secrets encryption with AES 256-bit encryption

  • Domain restrictions to receive OTP codes

  • User interface customizations

  • Free version notes are removed

Release information

  • Latest version has major configuration changes which are aligned against all other SecureMFA Providers

  • Some features which were used in old provider's versions have been depreciated. Please see documentation which features remain available.

  • If system has old version (version before 1.0.2.x) of this provider it must be uninstalled first before deploying the latest one.

Content

Deploy SecureMFA Email Time Based OTP Provider into ADFS Farm

Preparation steps

Before you can start registering “SecureMfaEmailOtpProvider” into your ADFS farm you must complete bellow steps. All commands must be executed in elevated PowerShell (PS) command prompt.

1) Deploy latest “SecureMfaEmailOtpProvider” PowerShell module from Microsoft PSGallery using bellow PS command.

Install-Module -Name SecureMFA_EMAIL_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 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_EMAIL_OTP ” folder from client’s computer into ADFS server (same location).

As alternative you can download “SecureMFA_EMAIL_OTP ” nupkg file manually from https://www.powershellgallery.com/ website. Rename nupkg file’s extension into ZIP. Unzip content into a folder “SecureMFA_EMAIL_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_EMAIL_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 “SecureMfaEmailOtpProvider”

3) Within “C:\Program Files\WindowsPowerShell\Modules\SecureMFA_EMAIL_OTP ” directory update “SecureMfaEmailOtpProvider.json” file.

If you are using a free version you only need to modify "sqlserver" server settings. If you will buy a license for unlimited users you will need to update "company" , "serialkey" and "subscriptionid" information to unlock licensed provider features.

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

5) Using SQL manager provision dbo access to “SecureMfaOTP” database for ADFS service account or SQL user.

Below is a sample of a SecureMfaEmailOtpProvider.json file

{

"company": "MyCompany",

"serialkey": "m00000000",

"subscriptionid": "1000000000000000000000001",

"sqlserver": "asqlaol1.adatum.labnet,1433",

"sqldbname": "SecureMfaOTP",

"sqlintegratedsecurity": "true",

"sqluseraccount": "",

"sqluserpassword": "",

"smtp_server": "smtp.adatum.labnet",

"smtp_mailfrom_title": "sMFA Email Time Based OTP Provider",

"smtp_mailfrom": "mfa.no.reply@adatum.labnet",

"smtp_port": "25",

"smtp_enablessl": "false",

"smtp_username": "",

"smtp_password": "",

"smtp_remove_user_prefix": "false",

"data_encryption": "false",

"data_encryption_passphrase": "d9GhT=7=Ox8-+LaZ",

"ui_customization": "false",

"ui_login_text": "",

"ui_login_failures": "0",

"ui_lockout_minutes": "5",

"ui_allowed_domains_for_otpcode": "",

"totp_customization": "false",

"totp_validity_seconds": "30",

"auth_mode": "SQL",

"verboselog": "false"

}

NOTE: Any configuration changes in json configuration file requires Install-SecureMfaEmailOtpProvider to be executed again.

SecureMFA Email OTP Provider Installation

Before a SecureMfaEmailOtpprovider 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.

Install-SecureMfaEmailOtpProvider

Other ADFS node(s)

Bellow command will install OTP authentication provider on OTHER ADFS node(s).

Install-SecureMfaEmailOtpProvider -NotMainNode

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

Verification

To verify if “SecureMFA Email OTP Provider” has been installed successfully.

1) Open the AD FS Management Snap-in (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.

Under Select additional authentication methods at the bottom of the page, check if “Email Time Based OTP Authentication” is selected.

ADFS Applications

When you will login into your ADFS application which requires multifactor authentication user will be able to request an authorization code to an e-mail address which is registered with user’s Active Directory account.

Below is print screen of “SecureMFA Email OTP Provider”.

By default, authorization pass-code which will be send to user’s e-mail address is valid up to 1 minute.


User interface customizations

Licensed clients can customize providers text which is presented to the users during logon. You can use simple html code like links to provide users with self-service portal links etc. Text is configured in configuration file “SecureMfaEmailOtpProvider.json” .

SecureMfaEmailOtpProvider.json config settings for user interface customization:

"login_text": "Enter a code received from MFA Email Authenticator.”

You will have to chnage "ui_customization" to be "true" for this change to take effect.

User Lockouts

This feature only works for licensed adapters. If you set “login_failures” to be more than a zero in SecureMFA data store 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 SecureMfaApiOtpProvider.json file.

SecureMfaApiOtpProvider.json config settings to enable 5 min lockouts for 15 failed OTP passcode attemps :

"login_failures": "15"

"lockout_minutes" : "5"


Disable User

This feature allows to disable SecureMFA OTP account and immediately restricts MFA authentication without disabling user in Active Directory.

User will be getting following message If user’s SecureMFA OTP account has been disabled by support team.

How to disable SecureMFA OTP accounts please read “SecureMFA Support Tools” documentation.

Support tools are packaged into a separate PowerShell module which is used for OTP support and maintenance tasks.

Encryption

Encryption only works for licensed adapters. 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)

SecureMfaApiOtpProvider.json config settings to enable encryption:

"data_encryption": "true"

"encryption_passphrase": " d9GhT=7=Ox8-+LaZ "


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;

When it is enabled your secret code is encrypted in Database and it looks like bellow.

Configure Allowed Domain List

When "ui_customization" is set to "true" you can add a list of custom domains or root domains which are allowed to receive OTP codes (You must use Semicolons to Separate a List values). This could be helpful if for security reasons you may need to restricts some domains to receive OTP tokens. Bellow is a sample of configuration in json file.

"ui_allowed_domains_for_otpcode": ".com;.net;mydomain.org;mydomain.eu"

Claims

All successful second factor authentication sessions will issue a new Actual Authentication method value: http://schemas.microsoft.com/ws/2008/06/identity/claims/authenticationmethod

With URI: http://schemas.microsoft.com/ws/2012/12/authmethod/otp

Enable OTP Data Store in Microsoft Active Directory Attributes

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

"auth_mode": "AD"

"encryption_passphrase": "d9GhT=7=Ox8-+LaZ"

You will have to execute following script “Create_SecureMFA_API_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 API OTP Provider in AD MODE. By default, write access to a new Active Directory attributes is allowed only for domain administrators. If you run ADFS under dedicated service account please make sure it has WRITE access to “sMFA-* user attributes”, in order for the provider to be able to update Active Directory user info.

Bellow print screen shows how AD user’s custom attributes will look like.

SMTP Configuration

By default provider works with default SMTP TCP port 25 and anonymous authentication. You can update SMTP server’s hostname / VIP address and port number (if required) by updating bellow settings in Secure MfaEmailOtpProvider.json file. Change “smtp_mailfrom" address which will appear for users as reply address.

"smtp_server": "smtp.adatum.labnet"

"smtp_port": "25"

"smtp_mailfrom_title": "sMFA Email Time Based OTP Provider"

"smtp_mailfrom": “mfa.no.reply@adatum.labnet”

Licensed providers can enable Secure SMTP connection via SSL and use service account credentials for authentication, by updating bellow settings:

"smtp_enablessl": "true"

"smtp_username": "smtpuser"

"smtp_password": "userpassword"

If you need to hide user’s account prefix information as additional security feature in authorization emails. Set “smtp_remove_user_prefix” in json config file to be “true”

Bellow pictures shows how authorization email looks like with enabled and disabled user’s prefix.

"smtp_remove_user_prefix": "true"


"smtp_remove_user_prefix": "false"

TOTP Customizations


This feature allows configuring how long OTP codes are valid in seconds and if OTP code can be reused during validly time. The lengths dictate valid interval length rather than exacts seconds from the current time as specified in RFC6238. If you specify OTP validity time to be 30 seconds it

makes provider authorization codes to be compatible with other SecureMfaOtp providers which allow using QR apps on a mobile device to generate OTP tokens etc...

SecureMfaApiOtpProvider.json config settings to enable 3600 seconds time drift and allow the user to reuse authorization code multiple times during valid interval:

"totp_validity_seconds": "3600",

"totp_allow_reuse": "true",

Logs

The below system events in Windows Event log may be used to verify and troubleshoot SecureMfa OTP Provider:

Log Name: AD FS/Admin

All provider related logs are stored in Windows Application Event logs and some data in SQL table or AD Attributes.

Windows Application Event:

Source: Secure MFA 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

SQL:

Table:secrets

[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;

AD Attributes:

[sMFA-OTP-lastlogon] – Time stapm of last successful logon;

[sMFA-OTP-logoncount] – Total number of successful user logons;

[sMFA-OTP-failedlogoncount] – Number of failed logons in a row;

[sMFA-OTP-failedlastlogon] - Time stamp of last failed logon;

[sMFA-OTP-failedcode] – Last failed user’s input;

[sMFA-OTP-logonip] – IP address of remote user;

[sMFA-OTP-useragent] – Details of user’s agent details from last logon;

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

OTP Users Management

Support tools for OTP Users management are packaged into a separate PowerShell module which can be used for OTP accounts management tasks.

For more details please read “SecureMFA Support Tools” documentation.