Skip to main content

Machine Key Tool

Use this guide to install and use the Machine Key Tool.

Applies to

SecureAuth IdP

Discussion

What is the Machine Key Tool?

The Machine Key Tool enables an administrator to backup, restore, and grant / revoke privileges for a SecureAuth IdP Appliance machine key (NetFrameworkConfigurationKey). A machine key is used for encrypting / decrypting the SecureAuth IdP web.config files.

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 Machine Key Tool works with SecureAuth IdP appliances on supported Windows Server versions.

Note

For complete information on which versions are supported, see the SecureAuth compatibility guide for your release.

Installation

  1. Contact Support for the MachineKeyTool.zip file.

    Download the file.

  2. Navigate to the download, right-click on the archive, select Properties, and switch to the General tab.

  3. If there is a button titled Unblock present on the tabbed page, click it and press OK to dismiss the Properties window.

    35455741.png

  4. Navigate to the download, right-click on the archive, and select Extract All...

  5. Extract the archive to D:\MFCApp_Bin\Extras.

    35455742.png

Usage

Backup

  1. To back up the Machine Key, navigate to D:\MFCApp_bin\Extras\MachineKeyTool and run Machine Key Tool.bat.

    The Splash page appears.

    35455743.png

    Press any key and the Legal disclaimer appears.

  2. Type AGREE at the prompt to accept the terms and press Enter.

    35455744.png

    Note

    If the terms are not acceptable, press Enter and the script exits automatically.

    If you accepted the disclaimer, the Main Menu appears.

  3. Type 1 and press Enter to start the backup.

    35455745.png

  4. Provide a strong password to protect the backup then press Enter to continue.

    Warning

    Passwords may only contain letters, numbers, and the following special characters @ # $ % * ( ) + ?.

    If an unsupported character is used, the backup may fail.

    35455746.png

    The backup now begins.

    35455747.png

    The backup process is completed when a screen like this appears:

    35455748.png

  5. Press any key to continue.

Restore

Decrypt the web.config Files

Before performing a restore, it is necessary to decrypt the web.config files through the SecureAuth administrative interface. For more details on doing this, refer to the SecureAuth IdP Realm Guide and go to the section, Decrypting / Encrypting Realms.

To decrypt the web.config files:

  1. To restore a Machine Key from backup, navigate to D:\MFCApp_bin\Extras\MachineKeyTool and run Machine Key Tool.bat.

    The Splash page appears. Press any key and the Legal disclaimer page appears.

  2. Type AGREE at the prompt to accept the terms, then press Enter.

    35455744.png

    Note

    If the terms are not acceptable to you, press Enter and the script exits automatically.

    The Main Menu appears.

  3. Type 2 and press Enter to start the restore.

    35455745.png

  4. Select the backup file to restore by entering its number, then press Enter.

    35455840.png

    Note

    The backup files are located in the D:\MFCApp_Bin\SecureAuth_Archive folder.

  5. Enter the password used to encrypt the backup file.

    35455841.png

  6. Type OK to continue with the restore or CANCEL to abort the restore process.

    35455842.png

    If you select to continue by typing OK, the restore process runs.

    Once completed, a screen like the following appears:

    35455843.png

Privileges

  1. To allocate access control via privileges, navigate to D:\MFCApp_bin\Extras\MachineKeyTool and run Machine Key Tool.bat.

    The Splash page appears.

    35455743.png

    Press any key and the Legal disclaimer page appears.

  2. Type AGREE at the prompt to accept the terms, and press Enter.

    35455744.png

    If the terms are not acceptable to you, press Enter and the script exits automatically.

    If you agree to the terms, the Main menu displays.

  3. Type 3 and press Enter to start the restore.

    35455745.png

    The Privileges menu appears.

  4. Press the letter that specified to the type of rights you want to confer for access to the machine key. This includes the following options:

    A

    Authenticated Users rights - This option is normally selected to grant Authenticated Users access to the machine key when the SecureAuth IdP appliance hosts a realm utilizing the Windows IWA/SSO functionality. For more on this, refer to Authenticated Users.

    D

    Domain Users rights - This option grants machine key access to the Domain Users group and should only be selected under the supervision of SecureAuth support staff. For more on this topic, refer to Domain Users.

    E

    Everyone rights - This option grants machine key access to the Everyone group and should only be used under the supervision of SecureAuth support staff. For more on this topic, refer to Everyone.

    35455857.png

    For more information on these options, refer to the following subtopics.

Machine Key Tool Release History

1.0.0: 2015-05-15

  • Initial release of tool

1.1.0: 2016-05-17

  • Deprecated WebConfigManager

  • Updated 7Zip library to v16.0.0.0 to address reported security vulnerabilities

In this section: