Documentation

 

 

Introduction

This document explains how to use the SecureAuth Backup Tool

Applies to

SecureAuth IdP 

SecureAuth IdP 8.1 Support

Version 2.2.0 or greater of the SecureAuth Backup tool is required for compatibility with SecureAuth IdP 8.1.

Discussion
What is the SecureAuth Backup Tool?

The SecureAuth Backup Tool allows a backup to be performed for the SecureAuth IdP installation

Disclaimer

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 WHAT SO EVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

System Requirements

The SecureAuth Backup Tool requires a SecureAuth IdP Appliance on Microsoft Windows Server 2008 R2, 2012, or 2012 R2, running SecureAuth IdP version 6.0.0 or greater. Starting with version 2.2.0 this tool requires Microsoft .NET Framework 4.5 or greater.

Installation

To install the SecureAuth Backup Tool, please follow the instructions below:

  1. Download the SecureAuth Backup Tool and copy the archive to your SecureAuth IdP Appliance
  2. Extract the archive to D:\MFCApp_BIN\Extras
  3. Once extracted you can find the tool at D:\MFCApp_BIN\Extras\SABackupTool
Using the Backup Tool

The Main Menu appears when the SecureAuth Backup Tool is launched. Use this screen to select which operation to perform.

1. The Minimum Backup option 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

2. The Full Backup option archives the entire D:\SecureAuth directory structure AND the following OS configuration information:

  • The .NET RSA Key used to encrypt\decrypt the web.config files
  • All WCF and 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 SCEP service
  • All files pertaining to the IDM Engine

3. Use the Restore option to restore a backup

4. The Instructions option opens a web browser with all instructions pertaining to the Backup Tool

The SSL / TLS Binding Certificate used for the IIS World Wide Web Publishing Service (W3SVC) is not archived by the Backup Tool. To archive the SSL Certificate, please see the Microsoft support document Export a Server Certificate (IIS 7) for instructions on how to manually perform the backup.



Use these instructions to perform a Minimum Backup.

The Minimum Backup can be used to migrate web.config files from one server to another

Decrypt the web.config Files

Before performing a minimum backup, it is necessary to decrypt the web.config files through the SecureAuth administrative interface

 

 SecureAuth IdP 8.1.0 or greater...

1. Launch the SecureAuth administrative interface

2. Click the Decrypt WebConfig link

3. Click the Select/Unselect All link and the Decrypt button

 SecureAuth IdP 8.0.1 - 8.0.3...

1. Launch the SecureAuth administrative interface

2. Click the Decrypt WebConfig link

3. Click the Select/Unselect All link and the Decrypt button

 SecureAuth IdP 7.x...

1. Launch the SecureAuth administrative interface

2. Click the Decrypt WebConfig link

3. Click the Select/Unselect All link and the Decrypt button

Begin the Minimum Backup

1. Launch 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 the spacebar can be pressed to advance manually.

The legal disclaimer appears.

2. Type AGREE at the prompt if the terms are accepted, and press Enter. If the terms are not accepted, press Enter and the script exits automatically.

3. From the Main Menu, type 1 and press Enter to select the Minimum Backup option

4. Enter a strong password to protect the backup and press Enter

The web.config files within the archive can contain sensitive information regarding network infrastructure. A strong password should be used to ensure this information is protected. For assistance selecting a strong password, visit the Norton Identity Safe Password Generator site. After typing in a password, press Enter to continue. 

Passwords may only contain the following special characters ? \ [ ] .

An unsupported character may cause the backup and / or restore process to fail


The description screen will now appear. 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.

After the Preflight stage, the Backup Tool enters the Archiving stage. During this phase the actual backup of the SecureAuth files occurs.

A message appears when the archive process is complete. After 5 seconds, an automatic redirection to the Main Menu is executed.


Decrypt the web.config Files

Before performing a full backup, it is necessary to decrypt the web.config files through the SecureAuth administrative interface
 

 SecureAuth IdP 8.1.0 or greater...

1. Launch the SecureAuth administrative interface

2. Click the Decrypt WebConfig link

3. Click the Select/Unselect All link and the Decrypt button

 SecureAuth IdP 8.0.1 - 8.0.3...

1. Launch the SecureAuth administrative interface

2. Click the Decrypt WebConfig link

3. Click the Select/Unselect All link and the Decrypt button

 SecureAuth IdP 7.x...

1. Launch the SecureAuth administrative interface

2. Click the Decrypt WebConfig link

3. Click the Select/Unselect All link and the Decrypt button

Begin the Full Backup

1. Launch 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 the spacebar can be pressed to advance manually. 

The legal disclaimer appears.

2. Type AGREE at the prompt if the terms are accepted, and press Enter. If the terms are not accepted, press Enter and the script exits automatically.


3. From the Main Menu, type 2 and press Enter to select the Full Backup option.

4. Enter a strong password to protect the backup and press Enter.

The web.config files within the archive can contain sensitive information regarding network infrastructure. A strong password should be used to ensure this information is protected. For assistance selecting a strong password, visit the Norton Identity Safe Password Generator site. After typing in a password, press Enter to continue. 

Passwords may only contain the following special characters ? \ [ ] * .  

An unsupported character may cause the backup and / or restore process to fail

The description screen appears. 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 performed. If the tool encounters an error, a message appears with instructions.

After the Preflight stage, the Backup Tool enters the Archiving stage. During this phase the actual backup of the SecureAuth files occurs.


A message appears when the archive process is complete. After 5 seconds, an automatic redirection to the Main Menu is executed.

   

The restore operation will overwrite files permanently and cannot be undone. We recommend taking a backup of the current SecureAuth installation before running the restore process.

Decrypt the web.config Files

Before performing a restore operation, it is necessary to decrypt the web.config files through the SecureAuth administrative interface
 

 SecureAuth IdP 8.1.0 or greater...

1. Launch the SecureAuth administrative interface

2. Click the Decrypt WebConfig link

3. Click the Select/Unselect All link and the Decrypt button

 SecureAuth IdP 8.0.1 - 8.0.3...

1. Launch the SecureAuth administrative interface

2. Click the Decrypt WebConfig link

3. Click the Select/Unselect All link and the Decrypt button

 SecureAuth IdP 7.x...

1. Launch the SecureAuth administrative interface

2. Click the Decrypt WebConfig link

3. Click the Select/Unselect All link and the Decrypt button

Begin the Restore

1. Launch the SecureAuth Backup Tool at D:\MFCApp_BIN\Extras\SABackupTool\SABackup.bat

The splash page for the tool appears. The screen will advance automatically in 5 seconds, or the spacebar can be pressed to advance manually. 

The legal disclaimer appears.

2. Type AGREE at the prompt and press Enter to accept the terms. If the terms are not accepted, press Enter and the script exits automatically.

3. From the Main Menu, type 3 and press Enter to select the Restore option.

4. To choose an archive to restore from backup, type the number of the file and press Enter to continue.

5. Enter the password for the archive to be restored, and press Enter to continue.

A warning about the restore process appears.

6. Read the message carefully.

7. Type OK to continue and press Enter. To abort the restore process, type CANCEL and press the Enter key.

8. The backup tool begins the final stages of the Preflight operation, in which it validates both the SecureAuth IdP environment and the integrity of the backup archive. Any errors detected during Preflight will appear. 

9. The backup tool begins restoring files. Note that some screens are displayed based on backup type, and therefore not all shown below may appear.

The post-restore instructions appear.

10. 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 / or environment. Therefore, not all of the screens below may appear.

Carefully review the instructions below and ensure all applicable steps are followed after a restore. Failure to follow all applicable steps may result in a damaged SecureAuth IdP installation.

Reset File Permissions and Shares Tool

The Reset File Permissions and Shares Tool is a utility shipped with all SecureAuth IdP Appliances. Its purpose is to validate correct settings for privileges on all files and folder in the D:\SecureAuth directory. It also validates correct file shares configured for the SecureAuth Filesync Service. For help using this tool, see the SecureAuth support document Using the Reset File Permissions and Shares Tool.

Certificates

The SecureAuth Backup Tool restores the X.509v3 certificates and machine key associated with the archived installation. Starting with version 2.1, 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 IdP Appliance is not lost when the settings are reinstated, all Firewall profiles were turned off. If your SecureAuth IdP Appliance normally uses the Windows Firewall with Advanced Security, please review the restored configuration and re-enable your firewall at the earliest possible opportunity. Please see the Microsoft support document Windows Firewall with Advanced Security Properties Page.  

Listed below are resolutions to common issues with the SecureAuth Backup Tool:

Error 503 displayed in Administrative Console after Restore

If this error appears, it's likely the IIS configuration files were restored to a different SecureAuth appliance than the one on which the backup was performed. In this scenario, the computer name and password configured for the SecureAuth0Pool application pool are incorrect. Without the proper credentials for the account, the application pool is unable to start, rendering the SecureAuth administrative interface unusable. To resolve this issue, run the RefreshSecureAuth0 script located at D:\MFCApp_Bin\Extras. The script will update the account information for the SecureAuth0Pool and resolve the problem.

Custom Verbiage not displaying properly after Restore of Minimum Backup

If a minimum backup from an older version of SecureAuth is restored to a newer version of SecureAuth, custom verbiage may not display properly. In versions of SecureAuth IdP prior to 7.2, DLLs were not Strong-Named, while newer versions of the product use strong-named DLLs for enhanced security. If the SecureAuth Backup Tool determines an older version of SecureAuth (lacking Strong-Named support) is being restored to a newer version with strong-named support, it will skip restoration of the MFA.SecureAuth.Resource.dll which contains the compiled verbiage.

If the unsigned MFA.SecureAuth.Resource.dll was restored to the newer version of SecureAuth, .NET errors would be generated for users and the installation would be rendered inoperable. By blocking the restore action, this situation does not occur. In this scenario however, the resource files are brought forward and the customized text is viewable in the verbiage editor. To resolve this issue, make a small change in the verbiage editor and then click the Save and Compile button to compile a new MFA.SecureAuth.Resource.dll.

SecureAuth Backup Tool Release History

 

 Version 2.0.x...

2.0.0 2015-01-10


  • Initial release of newly rewritten tool
 Version 2.1.x...

2.1.0 2015-01-26


  • 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
  • Fixed spelling and verbiage errors
  • 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.
  • 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.
  • 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).

2.1.1 2015-01-30 


  • 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

2.1.2 2015-02-09 


  • Added new WebConfigManager with support for OpenIDConnect to Bin
  • Added support code for new WebConfigManager

2.1.3 2015-02-13 


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

2.1.4 2015-05-12 


  • [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.
  • Added advanced error checking to the manifest creation routine.
 Version 2.2.x...

2.2.0 2015-08-03  


  • [FEATURE] Added support for SecureAuth IdP 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  SABackup,  .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 IdP 5.x with Windows Server 2003, various errors occur. The tool will now check on run to ensure it's 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 now validate its runtime location at launch. If it's not in the correct place, it will display an error and exit out.
 Version 2.3.x...

2.3.0 2015-09-27  


  • [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.  

2.3.1 2015-10-29


  • [BUG] Not all versions of .NET 4.5 were being detected. Updated the detection routine to address this issue.
  • [BUG] On Server 2012 there were issues exporting certificates which have been addressed in this version

2.3.2 2015-11-06


  • [FEATURE] Added debug functionality

2.3.3 2015-11-13


  • [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

2.4.0 2016-04-09


  • [BUG] User-friendly URLs (also known as vanity URLs) are properly handled starting with this version
  • [BUG] The WebConfigManager was deprecated to resolve error messages duting realm encrypt / decrypt 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 FullBackupOutput  will be created in the logs directory so progress of the archive process can be tracked
    • Added more detail to the debug log to help better diagnose problems

2.4.1 2016-05-17


  • [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.