The self-service password reset portal allows to reset, change and unlock Active Directory accounts. The portal enforces multi-factor authentication to verify a user’s identity. Users must enter a one-time passcode, which is generated on their phones via authenticator applications like Microsoft Authenticator, Google Authenticator, Symantec VIP, etc. Second-factor authentication will be the user’s password challenge or authorization token received via email. Portal supports role-based access controls (RBAC) and multiple domain profiles. 

Features

Unlicensed version

• Password unlock/change/reset for 24 Active Directory user accounts.

• Active Directory access via integrated authentication or LDAP.

• Multiple LDAP servers for resilient configuration.

• Multiple profiles to access to unlimited Domains.

• Password Change/Reset honors Active Directory password history and complexity policies.

• Role base access to unlock/change/reset workflows.

• Multi factor authentication.

• TOTP authentication is used for first factor authentication.

• OTP account deactivation.

• OTP account lockout feature.

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

• OTP account secrets encryption with AES 256-bit encryption.

• Active Directory user password challenge for second factor authentication.

• Email Authorization code for password reset workflow.

• Unlimited email authorization codes.

• Email authorization codes validity length customization.

• Configuration of whitelist of domains to receive authorization code.

• Configuration of subnets from which unlock/change/reset workflows can be executed (IPv4 and IPv6).

• Logs in Windows Applications Log.

• Allows UI interface branding using CSS theme and logo image.

• API interface.

Licensed version (additional features)

• Password unlock/change/reset for unlimited Active Directory user accounts.

• Free version notes are removed.

Deploy Self-service password reset portal (SSPR)

Prerequisites

• To run Self-service password reset portal system needs to meet following requirements:

- IIS 10 or above.

- OS with Windows x64 architecture.

- ASP.NET Core 3.1 Runtime (minimum v3.1.10). The installer URL can be obtained from: https://dotnet.microsoft.com/download/dotnet-core/thank-you/runtime-aspnetcore-3.1.10-windows-hosting-bundle-installer

Specify a path to downloaded file using -dotnet_hosting_bundle_path “c:\temp\dotnet-hosting-3.1.10-win.exe” parameter to deploy it during SSPR Portal installation . If donnet hosting bundle is not deployed manually or package location is not provided during installation, SSPR portal installation process will terminate with error.

• To store users OTP accounts data, it will require one of the following components:

- MS SQL Service (Can be any supported version by Microsoft)

- Microsoft Active Directory Domain (When OTP data is stored using AD attributes)

To deliver authorization codes for password reset operation to a user it will require:

- SMTP service endpoint.

• For SQL service and Active Directory access you will need :

- Dedicated service account.

- Additional SQL account or Client certificate may be required if environment cannot use integrated authentication to access SQL service.

Service account needs to have access to reset password, unlock, enable/disable user accounts in Active Directory OU. More information how access can be delegated see in “Service Account Access” section.

For SQL access it needs to have “db_datareader” and “db_datawriteraccess” to “SecureMfaOTP” database. 

Installation steps

 To install Self-service password reset portal(SSPR) you must complete bellow steps. All commands must be executed in elevated PowerShell (PS) command prompt. Installation will install and configure Website on IIS server, configure IIS Application pool with service account identity.

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

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

As alternative you can download “SecureMFA_SSPR” nupkg file manually from https://www.powershellgallery.com/  website. Rename nupkg file’s extension into ZIP. Unzip content into a folder “SecureMFA_SSPR” 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_SSPR” 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 “SSPR Portal OTP Accounts” 

3)      Start installation with following PS command. You’ll need to provide your SQL server details.

If you are not running SSPR Portal using Active Directory service account, you cannot use SQL integrated security to access database, you need set “-sqlintegratedsecurity $false" during installation . You’ll be prompted to provide  "sql user account" and "sql user password" details for your environment. 

Install-SecureMFA_SSPR_Portal -sqlserver “asqlaol1.adatum.labne,1433” -sqldbname “SecureMfaOTP” -sqlintegratedsecurity $true -dotnet_hosting_bundle_path “c:\temp\dotnet-hosting-3.1.10-win.exe”

 NOTE: SQL configuration can be updated after installation by updating ‘DefaultConnection’ parameter in ‘C:\inetpub\SSPR\appsettings.json’ file. SQL connection is established using Microsoft library class “Microsoft.Data.SqlClient”. For advance failover configuration please look into Microsoft documentation for valid SqlConnection.ConnectionString Property values. (https://docs.microsoft.com/en-us/dotnet/api/system.data.sqlclient.sqlconnection.connectionstring) 

4)      Using SQL manager provision “db_datareader” and “db_datawriteraccess” to “SecureMfaOTP” database for SSPR Portal service account or SQL user. 

5)      Within “C:\inetpub\ SecureMFASSPR\” directory (Default installation path) you will find “appsettings.json” configuration file. For minimal configuration you need to modify following settings:

• “smtp server details” (All configuration settings start with smtp_ under SSPR section)

• "portal_general_information" – Update with information what info users must see on a landing page. Leaving it blank will hide “General Information” section from users. The text can be written in basic HTML language or in plain text.

• "portal_profiles" – this list contains semicolon separated list of Domain profile(s) you need to have in your infrastructure. Each profile must have own section in appsettings.json file (it must be named using the same name as it was used to specify in portal_profiles list). Each profile will contain unique LDAP server(s) details for Active Directory access and other configuration settings which will apply only for that profile. For more details please look into “Domain Profiles” section. 

6)      When buying a license for unlimited users you’ll need to update "company" , "serialkey" and “subscriptionid” information in “appsettings.json” configuration file to unlock the app. 

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

8)      In PRODUCTION environment bind SSL certificate to IIS “SecureMFASSPR” website using IIS Manager and change port from 80 to 443.

Verification

 To verify if “SSPR Portal” has been installed successfully. Navigate to endpoint URL which is displayed in PS installation command under “SSPR Portal service endpoints for access”. You should see following screen:

SSPR Configuration

 Within “C:\inetpub\ SecureMFASSPR\” directory (Default installation path) you will find “appsettings.json” JSON configuration file which allows to make configuration changes to SSPR Portal. For any changes to take immediate effect you need to restart IIS Application pool “SecureMFASSPR”

“SSPR” Section

This section applies global settings to a portal and all domain profiles.

Below are the details of supported values:

"company","serialkey","subscriptionid" – those values needs to be updated only when you buy a license for  a product.

SMTP server configuration settings are specified using values which start with "smtp_"

"data_encryption" and "data_encryption_passphrase" is used to configure encryption for secrets in OTP accounts database. See “Encryption” section for more details.

"portal_profiles" – see “Domain Profiles” section bellow.

"portal_general_information” – Update with information what info users must see on a landing page. Leaving it blank will hide

“General Information” section from users. The text can be written in basic HTML language or in plain text.

"ui_customization", "ui_login_failures", "ui_lockout_minutes" – See “User Lockouts” section.

"totp_email_customization" – TRUE or FALSE . When set to true you can specify "totp_email_validity_seconds" – to configure how long email authorization code is valid and configure "totp_email_allowed_domains" – which allow to specify a white list of domain names  separated with semicolon for which users are allowed to request email authorization codes.

"api_enable" – TRUE or FALSE. Enables or disable API interface.

"api_authorization_header_key" – authorization header (x-api-key) value grant access for API  queries.

"auth_mode" – Specifies storage location for OTP accounts. Can be “SQL” or “AD”. For more details see “Store OTP codes in Active Directory”.

"verboselog" – TRUE or FALSE. Enables more detailed logging into windows event application log. For troubleshooting reasons change verboselog value to “true”

ConnectionStrings Section

 "DefaultConnection" – Configuration settings for connectivity to SQL Server to  access ‘SecureMFAOTP’ database where OTP Accounts data is stored.

SQL connection is established using Microsoft library class “Microsoft.Data.SqlClient”. For advance failover configuration please look into Microsoft documentation for valid SqlConnection.ConnectionString Property values and configuration options. (https://docs.microsoft.com/en-us/dotnet/api/system.data.sqlclient.sqlconnection.connectionstring)

 Domain Profiles

 For access to Active Directory domains you will need to update “portal_profiles" list.

“portal_profiles" – this list contains semicolon separated list of Domain profile(s) you need to have in your infrastructure. Each profile must have own section in appsettings.json file (it must be named using the same name as it was used to specify in portal_profiles list). Each profile will contain unique LDAP server(s) details for Active Directory access and other configuration settings which will apply only for that profile.

Below are the details of supported values within “Domain Profile” section:

"ldap_servers" – List for domain controllers IPs or Hostnames. Multiple servers must be separated using semicolon.

"ldap_server_port" -  a port number for LDAP connection

"ldap_server_auth_use_ssl" – TRUE or FLASE (Needs to be set true to establish SSL connection)

"ldap_server_auth_use_kerberos" – TRUE or FALSE (If server is joined to Active Directory it can use Kerberos authentication against LDAP servers when set to true)

"ldap_server_auth_enable_svc_account" – TRUE or FALSE (if set to true it will use bellow service account details to access LDAP server)

"ldap_server_auth_svc_user" –  service account username

"ldap_server_auth_svc_password" - service account password

“ldap_domain_forest" – FQDN of your domain (This value is used to merge username with domain name and lookup for user upn from “SecureMFAOTP” database)

"ldap_domain_netbiosname” – netbios name for your domain.

"ldap_search_basedn" – root directory from which to search for accounts when using profile.  Must be specified using distinguishedName format. SSPR operations will use LDAP search for user accounts under this location and subdirectories.

"ldap_session_timeoutseconds" – timeout value for LDAP queries.

"portal_users_default_role" – default is  "poweruser". See section “Roles” for more details.

"portal_users_ldap_mail_attribute"- default is "mail". This is mail attribute for user for SSPR Portal to retrieve email address to send authorization code for password reset operation. Can be used to specify alternative email attribute.

"portal_users_allowed_networks" – list of subnets which are allowed to use this profile. Multiple subnet must be separated using using semicolon. If left blank any network address will be allowed to access profile. See “Allowed Network Subnets” section for more details.

Sample Configuration

Bellow is example of appsettings.json  configuration file for tree different domain profiles. "ADATUM" and "ADATUM_PRIV" use Kerberos authentication and SSL for access into two different OU locations in the same domain . And  "CDATUM" is connection to legacy domain over unsecure LDAP connection using dedicated account. Access to this profile is restricted to internal network range . Note Active Directory will deny password change/reset operations over unsecure LDAP connection, but unlock operations will work fine.

{

    "Logging":  {

                    "LogLevel":  {

                                     "Default":  "Information",

                                  "Microsoft":  "Warning",

                                     "Microsoft.Hosting.Lifetime":  "Information"

                              }

             },

    "AllowedHosts":  "*",

    "ConnectionStrings":  {

                "DefaultConnection":  "Server=asqlaol1.adatum.labnet;Database=SecureMfaOTP;integrated security=true;user id=;password="

                          },

    "SSPR":  {

                 "company":  "MyCompany",

                 "serialkey":  "m00000000",

                 "subscriptionid":  "1000000000000000000000001",

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

                 "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",

                 "portal_profiles":  "ADATUM;ADATUM_PRIV;CDATUM",

                 "portal_general_information":  "Information for users…",

                 "ui_customization":  "false",

                 "ui_login_failures":  "0",

                 "ui_lockout_minutes":  "5",

                 "totp_email_customization":  "false",

                 "totp_email_validity_seconds":  "600",

                 "totp_email_allowed_domains":  "coporatedomain.com;corporatedomain.net",

                 "auth_mode":  "SQL",

                 "verboselog":  "false"

          },

    "ADATUM":  {

                   "ldap_servers":  "adc1.adatum.labnet;adc2.adatum.labnet",

                   "ldap_server_port":  "636",

                   "ldap_server_auth_use_ssl":  "true",

                   "ldap_server_auth_use_kerberos":  "true",

                   "ldap_server_auth_enable_svc_account":  "false",

                   "ldap_server_auth_svc_user":  "",

                   "ldap_server_auth_svc_password":  "",

                "ldap_domain_forest":  "adatum.labnet",

                   "ldap_domain_netbiosname":  "ADATUM",

                   "ldap_search_basedn":  "OU=User Accounts,DC=adatum,DC=labnet",

                   "ldap_session_timeoutseconds":  "30",

                "portal_users_default_role":  "poweruser",

                   "portal_users_ldap_mail_attribute":  "mail",

                   "portal_users_allowed_networks":  ""

            },

    "ADATUM_PRIV":  {

                        "ldap_servers":  "adc1.adatum.labnet;adc2.adatum.labnet",

                        "ldap_server_port":  "636",

                        "ldap_server_auth_use_ssl":  "true",

                        "ldap_server_auth_use_kerberos":  "true",

                        "ldap_server_auth_enable_svc_account":  "false",

                        "ldap_server_auth_svc_user":  "",

                        "ldap_server_auth_svc_password":  "",

                        "ldap_domain_forest":  "adatum.labnet",

                        "ldap_domain_netbiosname":  "ADATUM",

                        "ldap_search_basedn":  "OU=Privileged Users,DC=adatum,DC=labnet",

                        "ldap_session_timeoutseconds":  "30",

                        "portal_users_default_role":  "user",

                     "portal_users_ldap_mail_attribute":  "mail",

                        "portal_users_allowed_networks":  ""

                 },

    "CDATUM":  {

                   "ldap_servers":  "10.200.200.15:389",

                   "ldap_server_port":  "389",

                   "ldap_server_auth_use_ssl":  "false",

                   "ldap_server_auth_use_kerberos":  "false",

                   "ldap_server_auth_enable_svc_account":  "true",

                   "ldap_server_auth_svc_user":  "service_account",

               "ldap_server_auth_svc_password":  "ServiceAccountPassword",

                   "ldap_domain_forest":  "cdatum.labnet",

                   "ldap_domain_netbiosname":  "CDATUM",

                   "ldap_search_basedn":  "DC=CDATUM,DC=LABNET",

                   "ldap_session_timeoutseconds":  "30",

                   "portal_users_default_role":  "poweruser",

                   "portal_users_ldap_mail_attribute":  "mail",

                   "portal_users_allowed_networks":  "10.0.0.0/10.255.255.255;172.16.0.0/172.16.255.255;192.168.0.0/192.168.255.255;ee80:e1::/ee80:e1::ffff"

            }

}

 OTP Account Creation for Users

 SSPR portal enforces multi factor authentication to verify user’s identity. User must have  OTP Account which is required to complete first factor authentication. User must enrol mobile device by scanning QR code with mobile application like Google's Authenticator Microsoft Authenticator, Symantec VIP and potentially in many other time-based authenticators which supports RFC6238 ( a Time-Based One-Time Password (TOTP) Algorithm).

SSPR Portal doesn’t have ability to generate QR codes for enrolment , but you can enroll users by using one of the following options:

Option 1:

Install ADFS with OTP Provider and Web Portal for Users self-service OTP Enrolment. For more details click HERE.

Option 2:

Create OTP accounts in SQL database manually using “SecureMFA Tools” PS command - New-xOTP_User  For more details click HERE

Service Account Access

 For SQL service and Active Directory access you will need dedicated service account. Additional SQL account or Client certificate may be required if environment cannot use integrated authentication to access SQL service. Service account needs to have access to reset password, unlock, enable/disable user accounts in Active Directory OU. You can use “Active Directory Users and Computers snap-in” to configure access to OU by using  “Delegation Control Wizard” or run bellow PS script to provision minimal access required for SSPR Portal service to have access to run all workflows.

### PS command for Active Directory delegation to OU to ALLOW reset password, unlock, enable/disable accounts 

$OU = "OU=User Accounts,DC=adatum,DC=labnet"

$OU = "OU=Privileged Users,DC=adatum,DC=labnet"

$ServiceAccount = "svc_sspr"

Import-Module ActiveDirectory 

#Variables

$Container = 'ad:' + $OU

$type = [System.Security.AccessControl.AccessControlType] "Allow"

#SET AD permisions

$acl = get-acl $Container

$ADServiceAccount = Get-ADUser $ServiceAccount

$sid = new-object System.Security.Principal.SecurityIdentifier $ADServiceAccount.SID

$identity = [System.Security.Principal.IdentityReference] $SID

$adRights = [System.DirectoryServices.ActiveDirectoryRights] "ReadProperty"

$inheritanceType = [System.DirectoryServices.ActiveDirectorySecurityInheritance] "Descendents"

$ace = new-object System.DirectoryServices.ActiveDirectoryAccessRule $identity,$adRights,$type,"00000000-0000-0000-0000-000000000000",$inheritanceType,"bf967aba-0de6-11d0-a285-00aa003049e2"

$acl.AddAccessRule($ace)

Set-acl -aclobject $acl $Container

$acl = get-acl $Container

$ADServiceAccount = Get-ADUser $ServiceAccount

$sid = new-object System.Security.Principal.SecurityIdentifier $ADServiceAccount.SID

$identity = [System.Security.Principal.IdentityReference] $SID

$adRights = [System.DirectoryServices.ActiveDirectoryRights] "CreateChild"

$inheritanceType = [System.DirectoryServices.ActiveDirectorySecurityInheritance] "All"

$ace = new-object System.DirectoryServices.ActiveDirectoryAccessRule $identity,$adRights,$type,"bf967aba-0de6-11d0-a285-00aa003049e2",$inheritanceType,"00000000-0000-0000-0000-000000000000"

$acl.AddAccessRule($ace)

Set-acl -aclobject $acl $Container

$acl = get-acl $Container

$ADServiceAccount = Get-ADUser $ServiceAccount

$sid = new-object System.Security.Principal.SecurityIdentifier $ADServiceAccount.SID

$identity = [System.Security.Principal.IdentityReference] $SID

$adRights = [System.DirectoryServices.ActiveDirectoryRights] "WriteProperty"

$inheritanceType = [System.DirectoryServices.ActiveDirectorySecurityInheritance] "Descendents"

$ace = new-object System.DirectoryServices.ActiveDirectoryAccessRule $identity,$adRights,$type,"28630ebf-41d5-11d1-a9c1-0000f80367c1",$inheritanceType,"bf967aba-0de6-11d0-a285-00aa003049e2"

$acl.AddAccessRule($ace)

Set-acl -aclobject $acl $Container

$acl = get-acl $Container

$ADServiceAccount = Get-ADUser $ServiceAccount

$sid = new-object System.Security.Principal.SecurityIdentifier $ADServiceAccount.SID

$identity = [System.Security.Principal.IdentityReference] $SID

$adRights = [System.DirectoryServices.ActiveDirectoryRights] "WriteProperty"

$inheritanceType = [System.DirectoryServices.ActiveDirectorySecurityInheritance] "Descendents"

$ace = new-object System.DirectoryServices.ActiveDirectoryAccessRule $identity,$adRights,$type,"bf967a68-0de6-11d0-a285-00aa003049e2",$inheritanceType,"bf967aba-0de6-11d0-a285-00aa003049e2"

$acl.AddAccessRule($ace)

Set-acl -aclobject $acl $Container

$acl = get-acl $Container

$ADServiceAccount = Get-ADUser $ServiceAccount

$sid = new-object System.Security.Principal.SecurityIdentifier $ADServiceAccount.SID

$identity = [System.Security.Principal.IdentityReference] $SID

$adRights = [System.DirectoryServices.ActiveDirectoryRights] "ReadProperty"

$inheritanceType = [System.DirectoryServices.ActiveDirectorySecurityInheritance] "Descendents"

$ace = new-object System.DirectoryServices.ActiveDirectoryAccessRule $identity,$adRights,$type,"bf967915-0de6-11d0-a285-00aa003049e2",$inheritanceType,"bf967aba-0de6-11d0-a285-00aa003049e2"

$acl.AddAccessRule($ace)

Set-acl -aclobject $acl $Container

$acl = get-acl $Container

$ADServiceAccount = Get-ADUser $ServiceAccount

$sid = new-object System.Security.Principal.SecurityIdentifier $ADServiceAccount.SID

$identity = [System.Security.Principal.IdentityReference] $SID

$adRights = [System.DirectoryServices.ActiveDirectoryRights] "ExtendedRight"

$inheritanceType = [System.DirectoryServices.ActiveDirectorySecurityInheritance] "Descendents"

$ace = new-object System.DirectoryServices.ActiveDirectoryAccessRule $identity,$adRights,$type,"00299570-246d-11d0-a768-00aa006e0529",$inheritanceType,"bf967aba-0de6-11d0-a285-00aa003049e2"

$acl.AddAccessRule($ace)

Set-acl -aclobject $acl $Container

$acl = get-acl $Container

$ADServiceAccount = Get-ADUser $ServiceAccount

$sid = new-object System.Security.Principal.SecurityIdentifier $ADServiceAccount.SID

$identity = [System.Security.Principal.IdentityReference] $SID

$adRights = [System.DirectoryServices.ActiveDirectoryRights] "ExtendedRight"

$inheritanceType = [System.DirectoryServices.ActiveDirectorySecurityInheritance] "Descendents"

$ace = new-object System.DirectoryServices.ActiveDirectoryAccessRule $identity,$adRights,$type,"ab721a53-1e2f-11d0-9819-00aa0040529b",$inheritanceType,"bf967aba-0de6-11d0-a285-00aa003049e2"

$acl.AddAccessRule($ace)

Set-acl -aclobject $acl $Container

#Enable inheritance on all AD user accounts in OU

$users = Get-ADUser -ldapfilter “(objectclass=user)” -searchbase $OU

ForEach($user in $users)

{

    # Binding the users to DS

    $ouusr = [ADSI](“LDAP://” + $user)

    $sec = $ouusr.psbase.objectSecurity

    if ($sec.get_AreAccessRulesProtected())

    {

        $isProtected = $false ## allows inheritance

        $preserveInheritance = $true ## preserver inhreited rules

        $sec.SetAccessRuleProtection($isProtected, $preserveInheritance)

        $ouusr.psbase.commitchanges()

        Write-Host “$user is now inherting permissions.” -ForegroundColor Green;

    }

    else

    {

        Write-Host “$User Inheritable Permission already set.”

    }

}

 For SQL access service account neds to have “db_datareader” and “db_datawriteraccess” to “SecureMfaOTP” database.

Roles

Access to SSPR portal workflows is restricted based on roles. Following roles are supported:

Guest – Role has access to ‘Unlock Account’ workflow.

User – Role has access to ‘Change Password’ and ‘Unlock Account’ workflows.

Poweruser - Role has access to ‘Reset Password’, ‘Change Password’ and ‘Unlock Account’ workflows.

SSPR Portal workflows

Different workflows require different challenge responses by user for second factor authentication. Bellow diagram shows logical flows for each workflow.

Authentication

After successful first factor authentication with OTP code user’s session gets authentication cookie which is valid for 10 min.  If user will not complete any of SSPR Portal workflows within 10 min. time range , user will be prompted to login again with OTP code. After completing any of workflows authentication cookie is revoked. 

User Lockouts

 To use this feature, you must set "ui_customization" value to true. If you set “ui_login_failures” more than a zero you will see failed user authentication attempts in ‘SecureMFAOTP’ database. When user reaches “failedlogoncount” number of attempts set in “ui_login_failures” value user’s account will be locked out for a period of time set in "ui_lockout_minutes" . If you want to disable this feature you must set “ui_login_failures” to zero. All values are configured in appsettings.json file.

appsettings.json config settings to enable 5 min lockouts for 15 failed OTP passcode attempts :

"ui_customization" : “true”

"ui_login_failures" : "15"

"ui_lockout_minutes" : "5" 

Disable User 

This feature allows to disable SecureMFA OTP account and immedicably restrict MFA authentication without disabling user in Active Directory. User will be getting account is disabled message while trying to authenticate into SSPR Portal If user’s SecureMFA OTP account has been disabled by support team. 

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

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) 

appsettings.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 needs to be encrypted in Database and it looks like bellow. 

Theme customizations

 SSPR Portal allows user interface (UI) branding by modifying CSS theme which is located in C:\inetpub\SecureMFASSPR\wwwroot\css\site.css

And logo can be updated by replacing C:\inetpub\SecureMFASSPR\wwwroot\logo.png file with your image.

Allowed Network Subnets

"portal_users_allowed_networks" – allows to configure from which network location(s) users can access domain profile . Update a list with subnets from which users are allowed to use a profile. If left blank users can access profile from any network.

Allowed network locations are configured in “appsettings.json” file for each domain profile. 

NOTE:  List of locations must be specified as indicated in bellow format (Lower range address / upper range address) and each location is separated by semicolon. CIDR format is not supported. Range values are inclusive. 

To cover CIDR block range use following rules:

For IPv4 addressing – host range (For example   10.1.1.0/24 translates into host range: 10.1.1.1 /10.1.1.254)

For IPv6 addressing – network range (For example fe80::/64 translates into network range: fe80:0000:0000:0000:0000:0000:0000:0000 / fe80:0000:0000:0000:ffff:ffff:ffff:ffff or you can use a valid short IPv6 address text representation ( defined by rfc5952) : fe80::/fe80::ffff

Below is a sample of valid configuration

"ui_allow_qr_display_from_networks": “10.0.0.0/10.255.255.255;172.16.0.0/172.16.255.255;192.168.0.0/192.168.255.255;ee80:e1::/ee80:e1::ffff” 

Store OTP codes in Active Directory 

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 appsettings.json file to enable AD mode and update encryption passphrase with your custom string which will be used to decrypt 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_OTP_AD_attributes.ps1” on Read-Write domain controller. File can be found in “C:\Program Files\WindowsPowerShell\Modules\SecureMFA_SSPR” directory. You need to execute this script on Read-Write domain controller with AD account which is member of Schema Admins group. SSPR Portal when operates in AD mode 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 REQUIRED IF YOU PLAN TO RUN SecureMFA SSPR Portal 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.  

API Interface 

API SSPR Portal interface allows to validated OTP codes using API interface for SecureMFA Windows Providers (MFA-WIN-OTP). Windows providers are installed onto Windows OS and allows to request OTP code verification together with Native Windows Kerberos authentication. Windows providers wraps onto native windows authentication provider to request additional MFA authentication step. Integration is done by using Windows authentication plug-in architecture. 

In addition, SSPR Portal allows to receive HTTP POST messages and deliver it using SMTP service to the destination.  This feature allows to have API interface for MFA-API-OTP provider on premise. All HTTP messages communicating with API interface must deliver data with request body in JSON format and API authorization header must have a valid x-api-key value for the running service. For security reasons OTP validation response data will be encrypted and it will be decrypted by receiving provider.

NOTE: SSPR API Portal doesn’t require a license and must be enabled using ("api_enable":  "true") configuration setting in appsettings.json file. Client Providers which will use API interface must have a valid license to unlock all the futures.

Test API Service Status

To confirm if API service is running you will need to send HTTP GET message against API endpoint using applications like fiddler, postman etc. API message needs to include a valid header authorization key value (x-api-key) for your configuration. In our case we use fiddler to send GET command to API endpoint:  asspr.adatum.labnet/api/securemfaotp

Successful response should show bellow message:

Test API Email Send

To confirm if API service can deliver message using SMTP service you will need to send HTTP POST message against API endpoint using applications like fiddler, postman etc. API message needs to include a valid header authorization key value (x-api-key) for your configuration. In our case we use fiddler to send POST command to API endpoint: asspr.adatum.labnet/api/securemfaotp

POST Message: {"upn":"test1@adatum.labnet","otp":"123456","email":"test1@myemail.com","logonip":"10.101.101.101","useragent":"win10","product":"mfa-otp-api","company":"MyCompany","comments":"Test message"}

Success response will return following message: JSON=Success

Logs

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

Windows Application Event:

Source: “SecureMFA SSPR”

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 columns:

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;

Upgrade

 Deployment of a new version can be done by pulling latest version from PowerShell Gallery by using bellow command:

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

You’ll need to repeat all deployment steps as it was done for original installation. If it is highlighted 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 will be 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.

SecureMFA Support Tools

 Support tools are packaged into a separate PowerShell module (SecureMFA) which are used for OTP support and maintenance tasks. For more details please click HERE

Deployment Video

Bellow video shows how quickly you can SSPR Portal on a new windows server. Note: The latest SSPR provider migrated the service dependency to .NET Core version 8 runtimes from version 2.0.1.2. All the deployment steps will be the same as in the deployment video, but you will need to install. Net core version 8 runtime instead of 3.1.