SecureAuth Backup Tool Usage
Updated September 16, 2021
This document explains how you can use the SecureAuth Backup Tool to back up, restore, or migrate a SecureAuth® Identity Platform installation.
Disclaimers
This software is provided "as is" and SecureAuth Corporation disclaims all warranties with regard to this software including all implied warranties of merchantability and fitness. In no event shall SecureAuth Corporation be liable for any special, direct, indirect, or consequential damages or any damages whatsoever resulting from loss of use, data, or profits, whether in action of contract, negligence, or other tortious action, arising out of or in connection with the use or performance of this software.
Compatibility with SecureAuth Identity Platform
SecureAuth Identity Platform 9.2 or later: version 2.4.9 or later of the SecureAuth Backup tool is required for compatibility
System requirements
The SecureAuth Backup Tool requires a SecureAuth Identity Platform Appliance on:
Microsoft Windows Server 2012, 2012 R2 running SecureAuth Identity Platform version 9.2 or later. Starting with version 2.4.9 this tool requires Microsoft .NET Framework 4.7.2 or later.
Microsoft Windows Server 2016 running SecureAuth Identity Platform version 9.2 or later. Version 2.4.9 requires Microsoft .NET Framework 4.7.2 or later.
Microsoft Windows Server 2019 running SecureAuth Identity Platform version 20.06 or later. Version 2.4.9 requires Microsoft .NET Framework 4.7.2 or later.
Installation
To install the SecureAuth Backup Tool, follow the instructions below:
Download the SecureAuth Backup Tool and copy the archive to your Identity Platform Appliance.
Extract the archive to D:\MFCApp_BIN\Extras
After you extract the archive, you can find the tool at D:\MFCApp_BIN\Extras\SABackupTool
About the Backup Tool
The SecureAuth Backup Tool Main Menu offers the following operations:
 |
Minimum Backup archives the following SecureAuth files:
The web.config files, which hold the configuration settings for realms
The uncompiled language files (.resx)
The compiled language files MFA.SecureAuth.Resource.dll
The SecureAuth license files MFC.SecureAuth.License.dll
The paths.list and servers.list files which hold the configuration information for the SecureAuth Sync Service
The .NET RSA Key used to encrypt\decrypt the web.config files
Full Backup archives the entire D:\SecureAuth directory structure and the following OS configuration information:
The .NET RSA Key used to encrypt and decrypt the web.config files
All Windows Communication Foundation (WCF) and Security Assertion Markup Language (SAML) Signing certificates defined in the web.config files
All IIS backups, including a new backup taken during the archive process
A complete backup of the SecureAuth FileSync Service and supporting files
All files pertaining to the Simple Certificate Enrollment Protocol (SCEP) service
All files pertaining to the Identity Management (IDM) Engine
Restore reinstates a backup.
Migrate migrates your existing SecureAuth files.
All realms are restored to the system except SecureAuth0, the admin realm. SecureAuth0 is not restored or overwritten; only the licensing piece is updated.
Instructions opens a web browser with all instructions pertaining to the Backup Tool.
Warning
The Backup Tool does not archive the SSL / TLS Binding Certificate used for the IIS World Wide Web Publishing Service (W3SVC). To archive the SSL Certificate, see the Microsoft support document Export a Server Certificate (IIS 7) for instructions about how to manually perform the backup.
Use the Backup Tool
Decrypt the web.config files in the SecureAuth administrative interface before you select the operation you'd like to perform. The following instructions are for the Identity Platform 9.2+.
Go to the Identity Platform Advanced Settings (formerly Classic Experience).
If running the Identity Platform release 21.04 and later, go to Advanced Settings as follows:
If running the Identity Platform release 9.3 - 20.06, start the Classic Experience as follows:
If running the Identity Platform release 9.2, start the Classic Experience as usual.
In the Tools menu, click the Decrypt WebConfig link.
Before performing an operation, it's a best practice to decrypt the web.config files manually. If using 2.4.9 or later, you can let the tool automatically decrypt the web.config files, but manual decryption through the SecureAuth administrative interface is faster.
Click Select/Unselect All and then click Decrypt.
With the decryption complete, choose one of the following sections and then follow the steps to perform the operation that's right for your organization.
Use Minimum Backup to migrate web.config files, certificates, custom themes, and the IIS configuration from one server to another.
Start the SecureAuth Backup Tool at D:\MFCApp_BIN\Extras\SABackupTool\SABackup.bat
The splash page for the tool appears. The page advances automatically in 5 seconds, or press the spacebar to advance manually.
In the legal terms screen, type AGREE at the prompt if you accept the terms, then press Enter. If you do not accept the terms, press Enter and the script exits automatically.
In the Main Menu, type 1 and press Enter to select the Minimum Backup option.
At the Password prompt, enter a strong password to protect the backup.
Passwords can contain the following special characters: ? \ [ ] .
An unsupported character might cause the backup and restore process to fail.
Important
The web.config files within the archive can contain sensitive information regarding network infrastructure. Use a strong password to ensure this information is protected. For assistance selecting a strong password, visit the Norton Identity Safe Password Generator site.
After typing a password, press Enter to continue.
At the description prompt, enter a description of this backup (up to 45 characters) and press Enter to continue.
The Preflight stage of the backup begins.
During this phase, the Backup Tool checks various aspects of the SecureAuth environment to help ensure a successful backup is made. If the tool encounters an error, a message with instructions appears onscreen.
The Archiving stage of the backup begins.
During this phase the actual backup of the SecureAuth files occurs.
The archive process is complete when you see the following message.
After 5 seconds, the tool is automatically redirected to the Main Menu.
Use Full Backup to migrate the full installation from one server to another.
Start the SecureAuth Backup Tool at D:\MFCApp_BIN\Extras\SABackupTool\SABackup.bat
The splash page for the tool appears. The page advances automatically in 5 seconds, or press the spacebar to advance manually.
In the legal terms screen, type AGREE at the prompt if you accept the terms, then press Enter. If you do not accept the terms, press Enter and the script exits automatically.
In the Main Menu, type 2 and press Enter to select the Full Backup option.
At the Password prompt, enter a strong password to protect the backup.
Passwords can contain the following special characters: ? \ [ ] .
An unsupported character might cause the backup and restore process to fail.
Important
The web.config files within the archive can contain sensitive information regarding network infrastructure. Use a strong password to ensure this information is protected. For assistance selecting a strong password, visit the Norton Identity Safe Password Generator site.
After typing a password, press Enter to continue.
At the description prompt, enter a description of this backup (up to 45 characters) and press Enter to continue.
The Preflight stage of the backup begins.
During this phase, the Backup Tool checks various aspects of the SecureAuth environment to help ensure a successful backup is made. If the tool encounters an error, a message with instructions appears onscreen.
The Archiving stage of the backup begins.
During this phase the actual backup of the SecureAuth files occurs.
The archive process is complete when you see the following message.
After 5 seconds, the tool is automatically redirected to the Main Menu.
Warning
The migrate and restore operations will overwrite files permanently and cannot be undone. Be sure to back up the current SecureAuth installation before running the restore or migrate process.
Start the SecureAuth Backup Tool at D:\MFCApp_BIN\Extras\SABackupTool\SABackup.bat
The splash page for the tool appears. The page advances automatically in 5 seconds, or press the spacebar to advance manually.
In the legal terms screen, type AGREE at the prompt if you accept the terms, then press Enter. If you do not accept the terms, press Enter and the script exits automatically.
In the Main Menu, type 3 and press Enter to select the Restore option or type 4 and select the Migrate option.
Restore and Migrate are almost the same operation, so you can follow the same steps for each. The difference is that Restore restores everything from backup, whereas Migrate restores from backup without restoring SecureAuth0 and the standard Themes.
The following images show the Restore screens, but the Migrate screens are the same.
Select a backup file to restore or migrate.
Type the file number and then press Enter to continue.
At the Password prompt, enter the password that was used to back up the zip file you're restoring or migrating. Press Enter to continue.
A warning about the restore or migrate process appears. Read the message carefully.
Type OK to continue and press Enter.
To abort the restore or migrate process, type CANCEL and press Enter to continue.
The final Preflight stage of the backup begins.
During this phase, it validates both the SecureAuth Identity Platform environment and the integrity of the backup archive. Any errors detected during preflight will appear onscreen.
File restoration or migration now begins.
Note that some information is displayed based on backup type; therefore, the information you see might not match the info shown below.
The restore or migrate is complete when you see the post-restore or migrate instructions.
Read these instructions carefully and follow them after exiting the backup tool. Note that some screens will display; these are based on backup type and environment. Therefore, not all of the screens below will appear.
Carefully review the instructions below and ensure all applicable steps are followed after a restore or migrate. Failure to follow all applicable steps might result in a damaged SecureAuth Identity Platform installation.
Certificates
The SecureAuth Backup Tool restores the X.509v3 certificates and machine key associated with the archived installation. In version 2.4.9, appropriate privileges are assigned to restored certificates automatically based on the configuration of realms and, in most cases, no administrative intervention should be required. However, if there is customization for the SecureAuth environment, it is possible the detection algorithm may not set a needed privilege. For environments with customization, see the SecureAuth support document SecureAuth Backup Tool: Assigning Certificate Privileges and ensure certificates are assigned proper credentials.
Windows Firewall
During the Restore process, your Windows Firewall settings are reinstated from backup. To ensure contact with the SecureAuth Identity Platform Appliance is not lost when the settings are reinstated, all Firewall profiles were turned off. If your SecureAuth Identity Platform Appliance normally uses the Windows Firewall with Advanced Security, review the restored configuration and re-enable your firewall at the earliest possible opportunity. See the Microsoft support document Windows Firewall with Advanced Security Properties Page.
Release history
Read the following sections to learn about feature and functionality additions to the SecureAuth Backup Tool.
[FEATURE] Updated Decrypt-Webconfig.ps1 to v 0.1.2.
[BUG] Fixed web.config decryption attempt logic to check decryption a second time only when necessary. Also correctly displays result of decryption without false positives.
[ENHANCEMENT] Log fie now indicates the version of SABackup and if Migrate mode is enabled.
[FEATURE] Rewrote Powershell decryption script. Renamed to Decrypt-Webconfig.ps1 and writes to the /logs folder. The script attempts to run a second decryption, if necessary, due to AutoEncrypt re-encrypting web.configs while it is being disabled.
[FEATURE] Added "2016 Light" and "2019" Theme to the list of standard themes excluded from backups.
[FEATURE] Added "Migrate" restore mode which is the same as a normal restore but excludes SecureAuth0 and the following standard themes: 2012, 2013, Legacy, OTP App Default, 2016 Light, 2019
[BUG] Fixed incorrect brace character used instead of parentheses e.g.: IF %errorlevel% EQU 0 { should sayIF %errorlevel% EQU 0 (
[BUG] During unattended operations, the tool would stop at the description screen and prevent a fully automated process. The prompt will no longer appear during unattended operations and default verbiage will show in the description.
[SECURITY] The 7Zip binary has been updated to 16.0.0.0 to address recent security vulnerabilities found in 7Zip. The security vulnerabilities are tracked under CVE-2016-2335 and CVE-2016-2234.
[BUG] User-friendly URLs (also known as vanity URLs) are now properly handled.
[BUG] Deprecated the WebConfigManager to resolve error messages during realm encryption or decryption process.
[FEATURE] .NET 4.6.1 is now officially supported (4.6.0 remains unsupported).
[FEATURE] Enhanced logging was added.
A logs directory was added and the debug functionality will now retain the history.
During a Full Backup, a log file called FullBackupOutput will be created in the logs directory to track progress of the archive process.
More detail was added to the debug log to better help diagnose problems.
[BUG] Resolved "Obtain SHA Hash" bug where the tool would crash if the web.config files were not properly decrypted.
[FEATURE] Added debug logging to the :GetHashType subroutine.
[FEATURE] Added debug functionality.
[BUG] Not all versions of .NET 4.5 were being detected. Updated the detection routine to address this issue.
[BUG] Resolved an issue with the export of SHA-256 certificates.
[BUG] Previous versions of the tool did not detect all SAML configuration types. The routine has been updated and all six SAML configuration types are now correctly recognized.
[BUG] Previous versions of the tool did not detect all SSO configuration types. The routine has been updated and all SSO configuration types are now correctly recognized.
[Feature] Enhanced password checking using FIPS 180-2 SHA-512 HASH on archives made with v2.3.0 or greater.
[Feature] The SABackup Tool will now check whether an appliance is using SHA-1 or SHA-2. If a restore operation is run and there is a mismatch of the SHA types, a warning will be presented.
[FEATURE] Added support for SecureAuth Identity Platform 8.1.
[FEATURE] Added support for realms with custom names (e.g., other than SecureAuth1).
[FEATURE] On all Restore operations, a backup of the IIS config files will be made prior to the restore operation.
[FEATURE] Backups can now have up to 45 characters in the description assigned to them for easier identification.
[FEATURE] Starting with the 2.2.0 version of the SABackup Tool, .NET 4.5.0 or greater is required. The tool will now check for the presence of .NET 4.5 and, if not present, notify the user and exit the script.
[BUG] In previous versions of the SABackup Tool, if the appliance that was backed up had the IIS URL Rewrite module installed, and that backup was later restored to an appliance on which the rewrite module was not installed, errors would occur. This could be the realm(s) on which a .NET error appeared; in some cases the IIS worker processes would fail to start, thus rendering IIS inoperable. The SABackup tool will now record whether or not the URL Rewrite module is installed and expected. Should the appliance on which the restore operation was performed not have the module installed, SABackup will install it to prevent run time issues.
[BUG] The SABackup Tool has a minimum OS requirement of Windows Server 2008. If the tool is run on legacy versions of SecureAuth Identity Platform 5.x with Windows Server 2003, various errors occur. The tool will now check on run to ensure it is not running on a 2003 Server appliance.
[BUG] In previous versions, a full backup would restore the IIS Config settings if the OS versions matched. In some scenarios this was causing SecureAuth0 to become inoperable. The script will now backup but not restore the IIS configs and create all realms through the built-in IIS tools.
[BUG] The SecureAuth Backup Tool needs to be installed at D:\SecureAuth\MFCApp_BIN; however, some users were installing it in another location. When run from a non-standard location, the behavior of the tool was erratic. The tool will now validate its runtime location at startup. If the tool is not installed in the correct location, it will display an error and exit.
[BUG] While creating the manifest file the Backup Tool was trying to store the temp file in C:\Temp. Some customers did not have this directory, which would cause an error. The tool now creates the temp manifest file in the user defined temp directory.
[FEATURE] Advanced error checking was added to the manifest creation routine.
[BUG] Fixed a bug where the script would try to copy a DLL that did not exist on earlier systems. The Backup Tool will now check the SecureAuth version before trying to copy the DLL.
[FEATURE] Added new WebConfigManager with support for OpenIDConnect to Bin.
[FEATURE] Added support code for new WebConfigManager.
[BUG] Fixed a bug with Windows Server 2012 Appliances in which newly created IIS Applications were incorrectly assigned to a non-existent IIS Application Pool during the restore process.
[BUG] Fixed a bug in which the Restore pre-flight screen would wait 60 seconds before continuing; the time has now been reduced to 5 seconds.
[BUG] Fixed spelling and verbiage errors.
[FEATURE] Added Syslog support (SecureAuth Backup Tool Syslog Configuration).
[FEATURE] On restore, the Backup tool will now scan all SecureAuth realms and, if any have WindowsSSO.aspx set as the Begin Site, will grant access to NetFrameworkConfigurationKey for the Authenticated Users group. This removes a manual post-upgrade step.
[FEATURE] On restore, the Backup tool will now scan all SecureAuth realms and, if the Post Authentication behavior is set for SAML, will determine the SAML Signing Certificate configured for the realm and then grant access to the Authenticated Users group to that certificate. This removes a manual post-upgrade step.
[FEATURE] In version 2.0.0 every trouble message was flagged as an error. The messages have now been categorized properly and the companion documentation has been upgraded to reflect these changes as well (SecureAuth Backup Tool Event Log IDs).
This is the initial release of the newly rewritten SecureAuth Backup Tool.