Scripts

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