ADFS Email OTP Provider
TOTP Email authentication for Microsoft ADFS. It is a module for Microsoft ADFS 2019 and ADFS 2016 servers. It enables ADFS servers to provide multi-factor authentication (MFA) using a Time-Based One-Time Password (TOTP) Algorithm which is based on RFC6238. Using this MFA provider user is required to enter a confirmation code, which is generated and send to an email address associated with user’s Active Directory account.
- Multi-language UI: English, Spanish, French, German, Chinese, Portuguese, Russian, Italian, Arabic, Turkish, Dutch, Finnish, Swedish, Norwegian, Polish, Danish and Lithuanian.
- Unlimited user accounts for personal or trial use scenarios.
- Authorization codes are 18 digits long.
- Authorization codes are valid up to 60 min.
- Supports ADFS CSS themes.
- Authorization code is delivered via e-mail set in user’s AD account attribute.
- Logs are stored in Windows application log.
- Runs on ADFS 2016 and ADFS 2019 servers.
- Supports unlimited users.
Licensed version (additional features)
- Provider allows to issue OTP codes for user authentications.
- Authorization codes are 6 digits long.
- Unlimited user accounts of licensed organization.
- Authorization code validity can be customised.
- Unique secret keys and authentication codes for the users.
- Secret key encryption with AES 256-bit encryption in AD.
- Customizable AD attributes for secret key storage.
- Allows secure SMTP configuration (SSL) and user authentication options.
- User interface customizations for provider’s interface.
- Configure allowed Domain list to receive OTP codes
- Free version notes are removed.
Deploy SecureMFA Email Time Based OTP Provider into ADFS Farm
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: If your ADFS server 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_EMAIL_OTP" -Repository "PSGallery" | Save-Module -Path "C:\"
Copy C:\SecureMFA_EMAIL_OTP folder from client’s computer into ADFS server “C:\Program Files\WindowsPowerShell\Modules\SecureMFA_EMAIL_OTP”
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 update “SecureMFAEmailOtpProvider.json” file. If you are using a free license you only need to modify "smtp_server" server settings. If you will buy a license to enable all the features, you will need to update "company" and "serialkey" information to unlock the app.
3) 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
Below is a sample of a SecureMFAEmailOtpProvider.json file
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.
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 “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.
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 hour.
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.
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.
All successful second factor authentication sessions will issue a new Actual Authentication method value: http://schemas.microsoft.com/ws/2008/06/identity/claims/authenticationmethod
Authorization code customization
By default authorization pass-code is valid up to 1h. Licensed clients can modify up to time interval by updating “SecureMfaOtpProvider.json” configuration file. Bellow sample sets authorization code validity up to 5 min. Validity time is set in seconds.
Configuring Secret Key in AD (OTP Configuration)
By default, authorization pass-code value is generated from user’s e-mail address using specific algorithm. This allows to setup duplicated environment with the same email addresses for the users and generate duplicated authentication codes. Licensed clients can change that pass-code value is generated from user’s AD attribute which is unique and randomly generated value for each user. Value is encrypted with AES 256-bit encryption. To allow pass-code value to be generated from user’s AD attribute, update “SecureMfaOtpProvider.json” configuration file with
Default user’s AD attribute which is used by provider to store secret key is “primaryTelexNumber”. You can change it to be any other custom string attribute in AD by modifying “auth_code_secret_AD_user_atribute” value. Please note that ADFS service account needs to have modify access to user’s AD attribute value. Generated value will look like bellow. If you suspect that value is compromised, you can delete it and provider will generate a new one for the user with a next authorization code request.
This setting enables “SecureMFA Email OTP Provider” to send OTP codes because on each successful login user’s “primaryTelexNumber” value is removed and a new value will be generated when user will request a new OTP code.
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.
Licensed providers can enable Secure SMTP connection via SSL and use service account credentials for authentication, by updating bellow settings:
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.
All provider related logs are stored in Windows Application Event logs
Source: Secure MFA Email OTP
Event ID 6660: Configuration Logs
Event ID 6662: Successful Events
Event ID 6663: Failed 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_EMAIL_OTP -Repository PSGallery -Scope AllUsers -Froce
You’ll need to repeat all deployment steps as it was done for original installation.