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

Licensed version (additional features)

Release information

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 codes can be reused during valid time. The lengths dictate valid interval lengths rather than exact seconds from the current time, as specified in RFC6238. If you specify the OTP validity time to be 30 seconds, it

makes provider authorization codes compatible with other SecureMfaOtp providers, which allows the use of 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 the 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 is in an 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 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 the below command:

Install-Module -Name SecureMFA_EMAIL_OTP -Repository PSGallery -Scope AllUsers -Force

You’ll need to repeat all deployment steps as you did for the original installation. If the deployment notes highlight that the attribute store needs to be extended for OTP data, you’ll need to take an extra step to complete your upgrade. 

· If you are storing your user OTP data in MS SQL, you may need to execute “sql_Upgrade_From_Previous_Version.txt” on your SQL database. 

· If you store your user OTP data in AD, you may need to execute “Create_SecureMFA_OTP_AD_attributes.ps1” on your Domain controller. (this is usually highlighted in the 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 user management are packaged into a separate PowerShell module, which can be used for OTP accounts management tasks.

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