Scripts
SecureMFA Support Tools
Installation
All support tools for OTP accounts are packaged into Powershell module. Latest Module can be downloaded from Microsoft PowerShellGallery
Install-Module -Name SecureMFA
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 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" -Repository "PSGallery" | Save-Module -Path "C:\"
Copy C:\SecureMFA folder from client’s computer into server “C:\Program Files\WindowsPowerShell\Modules\SecureMFA”
As alternative you can download “SecureMFA” nupkg file manually from https://www.powershellgallery.com/ website. Rename nupkg file’s extension into ZIP. Unzip content into a folder “SecureMFA” 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.
Post installation steps
SecureMFA_SupportTools.json configuration file located in "C:\Program Files\WindowsPowerShell\Modules\SecureMFA" folder must be updated with your configuration data.
Bellow is a sample of a valid SecureMFA_SupportTools.Json config file:
{
"sql_server": "asqlaol1.adatum.labnet",
"sql_database": "SecureMfaOTP",
"ui_input_text": "Please enter user's UPN",
"ui_environment": "MyCompany",
"encryption_passphrase": "d9GhT=7=Ox8-+LaZ"
}
License
Most of the functions for SecureMFA Tools do not require a license. Features which require license are listed below under licensed functions. To use those functions you will require a serial number. License is issued per identity provider for unlimited users.
Functions (No license require)
Show-xOTP : Shows OTP details for the user
Reset-xOTP : Resets OTP account in SQL database
Set-xOTP : Disables or Enables OTP account for the user
Get-xOTP-Status : Shows OTP accounts status
Licensed Functions
Get-xHashiCorp_Vault_ClientToken : Retrieves a client token from HashiCorp Vaut
Profiles
Each command by default uses "SecureMFA_SupportTools.json" for configuration data values. In multi farm environments where you may use a different databases or configuration settings for SecureMFA providers you can use -Profile parameter for each PS function. This requires to update Profiles.json file with square bracket array values, as indicated below.
["MyEnvironment1","MyEnvironment2","MyEnvironment3"]
The file must be named with environment name followed by underscore and "SecureMFA_SupportTools.json" . It must be placed into “SecureMFA” modules directory. Below is a sample how file should be named for “MyEnvironment1”.
MyEnvironment1_SecureMFA_SupportTools.json
Configuration data must be structured the same way as in original “SecureMFA_SupportTools.json" file.
Managing OTP accounts when using Active Directory attributes
OTP providers allow configuring OTP Data Store to be Active Directory Attributes. It allows storing User OTP attributes in the Active Directory domain. This removes the dependency and cost of having MS SQL service configuration to store the OTP database. To allow SecureMFA Support Tools to manage users who are stored in Active Directory attributes you have to update the SecureMFA_SupportTools.json file and enable AD mode with a custom encryption passphrase which is used to encrypt secret data in AD attributes and must match across all your providers. AD mode doesn’t support unencrypted secrets, require a computer to be joined into the Active Directory domain and use accounts that have to modify access to “sMFA-OTP-*” user attributes when executing scripts.
"auth_mode": "AD"
"encryption_passphrase": "d9GhT=7=Ox8-+LaZ"
Functions
Show-xOTP
Shows OTP details for a user .
Show-xOTP -upn test1@adatum.labnet -DecryptSecret
Show-xOTP -upn test1@adatum.labnet -DecryptSecret -otpcode 893117
Reset-xOTP
Resets SecureMFA.com OTP accounts in SQL database.
Reset-xOTP -upn test1@adatum.labnet -HardReset
Set-xOTP
Command to manage users state. It can disable, unlock or enable OTP account for the user.
Enable OTP user command:
Set-xOTP -upn test4@adatum.labnet
Disable OTP user command:
Set-xOTP -upn test4@adatum.labnet -Disable
Unlock OTP user command:
Set-xOTP -upn test4@adatum.labnet -Unlock
Below is an example of command output when disable action is executed against OTP user.
Get-xOTP_Status
Command shows OTP accounts overall status. It lists more detailed information when used with parameters.
Get-xOTP_Status -upn test1@adatum.labnet
This command shows OTP account's details for the user.
Get-xOTP_Status -lastlogons
This command shows last logons count for users by date.
Get-xOTP_Status -failedlogons
This command shows last failed logons count for users by date.
Get-xOTP_Status -show_pending_users
This command shows last all OTP accounts which didn’t scan a QR code.
Get-xOTP_Status -show_enabled_users
This command shows all enabled OTP accounts.
Get-xOTP_Status -show_disbaled_users
This command shows all disabled OTP accounts.
Get-xOTP_Status -show_locked_users
This command shows all locked OTP accounts.
New-xOTP_User
In highly secure environments where you do not allow QR code scans from remote locations and you have a procedure to upload secret key into user’s authenticator app manually you can pre created OTP account in SQL database using following commands:
New-xOTP_User -upn test2@adatum.labnet
This command creates OTP account for test2 user in SQL database. Command will show secretKey output for user which can be used for manual setup with TOTP Authenticator app.
New-xOTP_User -upn test2@adatum.labnet -Encrypt
This command creates OTP account with encrypted secret for test2 user in SQL database.
Get-xHashiCorp_Vault_ClientToken
Retrieves a client token from HashiCorp Vaut. To get a client token from HashiCorp Vault when it uses OIDC configuration for authentication. You need to executed bellow PS command which will retrieve a client access token when authentication is successful with you Identity Provider. A client token can be used to query HashiCorp Vault API for secrets within delegated scope.
$header = Get-xHashiCorp_Vault_ClientToken
Successful authentication will return an object which can be used to query HasiCorp Vault API endpoint.
Because object has multiple items, you need to use header item number for Headers parameter and query HashiCorp Vaul API for data.
Invoke-RestMethod -Headers $header.Item(2) -Method GET -Uri 'http://hscvault.adatum.labnet:8200/v1/kv/data/testsecret'
You can review a full details of issued token by executing bellow command
($header.Item(1) | ConvertFrom-Json).auth
Logs
All provider related logs are stored in Windows Application Event logs.
Windows Application Event
Source: SecureMFA_SupportTools
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 5554: Successful User Management Events
Event ID 5555: Failed User Management Events
Event ID 5556: Successful OTP Events
Event ID 5557: Failed OTP Events
SQL Database Maintenance
Scheduler bellow SQL script to run as weekly job on SQL Server. Script will delete old user records with lastlogon data older than 60 days or value equals NULL .
Delete FROM [SecureMfaOTP].[dbo].[Secrets] WHERE lastlogon < DATEADD(day, -60, GETDATE()) OR lastlogon IS NULL