Troubleshooting: Realm Management Tool Not Properly Creating a Realm

Version Affected: All versions (Cause 2 specific to version 9.1)
 
 

Overview

The Realm Management Tool sometimes fails to fully create a new realm. There are two distinct causes, so identify which applies before following a resolution:

• See Cause 1 - another process, such as antivirus software or the IIS warm-up tool, is locking the template realm's files while the tool is copying them.
• See Cause 2 - the RealmManagementTool.bat file itself is in a Windows "Blocked" state, so it can't run correctly.

These causes are not related, so a fix for one cause will not resolve the other cause.
 

In this article

• Cause 1: Another Process Locking the Template Realm's Files
• Cause 2: RealmManagementTool.bat Is Blocked by Windows

Cause 1: Another Process Locking the Template Realm's Files

When creating a new realm from an existing template realm, the template realm is being used by another process, which prevents the Realm Management Tool from copying the full set of directory files for the new realm. Antivirus scanners and the IIS warm-up tool are common applications that lock these files — the IIS warm-up tool, because it pings every realm on the appliance, causes IIS to lock certain files as soon as a realm is opened, preventing the tool from copying them over. When this happens, the tool's log shows IIS DirectoryFile verification failed for the new realm.

The screenshot below shows the Realm Management Tool's console log for a new realm, with IIS DirectoryFile verification failed logged before the realm is otherwise marked created.

Resolution 1:

To resolve this:

1. Turn off the IIS warm-up tool so realms are not pinged during creation, preventing IIS from locking their files. Disabling it makes the first request to each realm slightly slower — to offset this, set the Idle Time-out to 0 minutes on the relevant Application Pools in IIS, so the worker process stays active instead of shutting down.
2. If antivirus software is present on the appliance, adjust its scan scope to exclude the D: drive entirely.

Cause 2: RealmManagementTool.bat Is Blocked by Windows

On IdP 9.1, using the Admin Console to access a realm that was just created with the Realm Management Tool can show "An Authentication error has occurred..." Turning off Custom Errors reveals the underlying error: Could not find a part of the path 'D:\SecureAuth\SecureAuthX\Themes'. This happens because RealmManagementTool.bat itself is in a Windows "Blocked" state — a security attribute Windows applies to files copied from another computer — which prevents it from running correctly, so it only partially creates the realm.

The screenshot below shows the resulting Server Error page, with Could not find a part of the path 'D:\SecureAuth\SecureAuth8\Themes' and its DirectoryNotFoundException stack trace.

Resolution 2:

To resolve this:

1. Navigate to the Realm Management Tool folder (for example, D:\MFCApp_Bin\Extras\RealmManagementTool).
2. Right-click RealmManagementTool.bat and select Properties.
3. Click Unblock, then click OK.

The screenshot below shows the file's Properties dialog, with the Security section's Unblock button highlighted.

Once unblocked, use the Realm Management Tool to delete the malformed realm and re-create it — it should now complete successfully.
 
 

SecureAuth Knowledge Base Articles provide information based on specific use cases and may not apply to all appliances or configurations. Be advised that these instructions could cause harm to the environment if not followed correctly or if they do not apply to the current use case.

Customers are responsible for their own due diligence prior to utilizing this information and agree that SecureAuth is not liable for any issues caused by misconfiguration directly or indirectly related to SecureAuth products.