Migrating a SharePoint environment is a complex undertaking, but moving Workflow Manager (WFM) to a completely new farm in a different domain is often considered the 'final boss' of SharePoint administration. Whether you are performing a hardware refresh, upgrading your infrastructure, or consolidating domains, preserving your SharePoint 2013 workflows is critical for business continuity.
The challenge lies in the fact that Workflow Manager does not rely on simple active directory accounts for its internal security. Instead, it uses a High-Trust model based on X509 certificates and a unique identifier known as the SharePoint Authentication Realm. If these components don't match between your old and new environments, your workflows will simply cease to function.
In this guide, you will learn the exact sequence of steps required to successfully move Workflow Manager across domains while keeping your existing workflow instances and history intact.
Understanding the Core Architecture: Why Realm Matters
To successfully migrate Workflow Manager, you must first understand how SharePoint identifies itself to the workflow engine. Every SharePoint farm has a unique Authentication Realm. By default, this Realm is identical to the SharePoint Farm ID.
When a workflow is published, SharePoint creates an entry in the App Management database. This entry maps the SharePoint Web ID to a specific Realm ID. The Workflow Manager uses a naming convention for its scopes that looks like this: SiteCollectionID/WebID.
If you move your content databases to a new farm, the Web IDs remain the same, but the Farm ID (and thus the default Realm) changes. This mismatch breaks the link between SharePoint and the Workflow Manager. To fix this, you must manually force the new farm to use the Realm of the old farm.
Phase 1: Pre-Migration Requirements
Before you touch the new environment, you must gather critical data from your source environment. Without these pieces, the migration will fail.
- The Original Farm Realm: Run the following PowerShell command on the old farm and save the output:
powershell Get-SPAuthenticationRealm - Service Bus Primary Symmetric Key: This is required to decrypt the Service Bus configuration. If you don't have this, you cannot restore the Service Bus farm.
- Certificates: Export the SSL certificates used for the Service Bus and Workflow Manager (with private keys).
- Database Backups: You need backups of the following databases:
- Workflow Service Management
- Workflow Resource Management
- Workflow Instance Management
- Service Bus Management
- Service Bus Gateway
- Service Bus Message Container
- App Management Service Application Database
Phase 2: Preparing the New SharePoint Farm
Once your new farm is built in the new domain, you need to align its identity with the old one.
Step 1: Set the Authentication Realm
You must change the Realm of the new farm to match the old one. Use the GUID you retrieved in Phase 1:
Set-SPAuthenticationRealm -Realm "Original-Farm-ID-Guid"
Step 2: Restore the App Management Service
The App Management Service Application is the 'glue' between SharePoint and the App Model (which Workflow 2013 uses). Restore the App Management database to your new SQL server, create a new Service Application in SharePoint, and point it to this restored database. This ensures that the CompositePartitionKey entries, which link Web IDs to the Realm, are preserved.
Phase 3: Restoring Workflow Manager and Service Bus
When restoring Workflow Manager in a new domain, you will use new service accounts. This is perfectly fine because the security is certificate-based, not account-based.
Step 1: Restore Databases
Restore the Workflow and Service Bus databases to the new SQL instance. Note that while some experts suggest skipping the 'Management' databases, it is generally safer to restore them and use the Restore-SBFarm and Restore-WFFarm cmdlets to reconfigure the pointers.
Step 2: Reconfigure Service Bus
Run the Restore-SBFarm cmdlet. During this process, you will provide the new domain service accounts. You must also update the namespace permissions:
Set-SBNameSpace -Name "ServiceBusDefaultNamespace" -ManageUsers "NewDomain\NewServiceAccount"
Step 3: Register the Workflow Service
This is the final step that connects the two worlds. You must use the same scope name that was used in the original farm (usually 'SharePoint').
Register-SPWorkflowService -SPSite "https://your-new-site-url" -WorkflowHostUri "https://wfm-host:12290" -ScopeName "SharePoint" -Force
The -Force parameter is vital here as it overwrites existing child scope permissions and updates them with the new farm's technical details while keeping the workflow definitions intact.
Common Mistakes to Avoid
- Ignoring the Symmetric Key: If you lose the Primary Symmetric Key from the original Service Bus installation, you cannot restore the farm. You would be forced to start with a fresh WFM installation, losing all 'In Progress' workflows.
- Mismatching Scope Names: If your original farm used a custom scope name during
Register-SPWorkflowServiceand you use the default 'SharePoint' on the new farm, the workflows will not be found. - SQL Permissions: Ensure the new domain service accounts have
db_ownerpermissions on all restored Workflow and Service Bus databases before running the configuration cmdlets.
Frequently Asked Questions
Do I need to use the same service account names in the new domain?
No. Workflow Manager and Service Bus are designed to allow credential changes during the Restore- process. As long as the certificates and Realm match, the new domain accounts will work perfectly.
What happens to workflows that are currently 'In Progress'?
If you correctly restore the Instance Management database and keep the Realm ID consistent, 'In Progress' workflows will resume from their last persisted point once the migration is complete.
Does this apply to SharePoint 2016, 2019, and Subscription Edition?
Yes. While the Workflow Manager binaries have evolved into 'Workflow Manager Backend' or 'SharePoint Workflow Manager', the underlying logic involving the Authentication Realm and Service Bus remains the same for all versions using the 2013 Workflow engine.
Key Takeaways
Migrating Workflow Manager across domains is a high-stakes task, but it is entirely predictable if you follow the identity logic.
- The Realm is King: The
Set-SPAuthenticationRealmcommand is the most important step in the entire process. - Web IDs are Permanent: Because SharePoint content database migration preserves Web GUIDs, the Workflow Manager can always find the correct scope if the Realm matches.
- Restore App Management: Don't just move content; move the App Management database to preserve the internal mapping of your high-trust assets.
- Use PowerShell: Avoid the Configuration Wizard for complex migrations; the PowerShell cmdlets provide the granular control needed for cross-domain identity mapping.
By following this structured approach, you can move your SharePoint infrastructure to a new domain without leaving your critical business processes behind.
