Configuration Migration Deployment Steps

Article
07/11/2012

Applies To: Forefront Identity Manager 2010

In this section, you perform the following procedures for the Microsoft® Forefront® Identity Manager (FIM) 2010 components:

Warning

In order to migrate from one environment to another, the builds for both the source and the target servers must be identical.

Back up the pilot and production environments by using the Backup and Restore procedures.
Export the FIM Service schema configuration.
Export the FIM Synchronization Service configuration.
Export the FIM Service policy and FIM Synchronization Service configuration resources.
Install the FIM Synchronization Service and the FIM Service in the production environment.
Enable the maintenance mode in the production environment.
Import the FIM Service schema configuration.
Import the FIM Synchronization service configuration.
Install the custom DLLs necessary for custom workflows.
Import the FIM Service policy and FIM Synchronization Service configuration.
Disable maintenance mode in the production environment.

Note

Because of dependencies among configurations, it is necessary to export FIM Service schema configuration separately from FIM Service policy and FIM Synchronization Service configuration. The reason is that the FIM Synchronization Service configuration depends on the FIM Service schema.

Prerequisites

Before you begin these procedures, you must have completed the following steps:

The pilot environment (also known as the test lab) is installed, configured, and validated. It is important to validate all configurations in a safe environment. Adverse configurations can lead to deleted objects in connected systems such as Active Directory Domain Services (AD DS).
The FIMAutomation Windows PowerShell snap-in is available. Installing the FIM Service also installs the Windows PowerShell cmdlets that you use to export and import FIM Service configuration; so, usually no additional steps are necessary. This document assumes that you run all Windows PowerShell scripts on the same computer as the FIM Service. If you want to run the scripts on a different computer, you must install the Windows PowerShell PSSnapin manually on that computer. For more information about installing Windows PowerShell snap-ins, see Add-PS Snapin (https://go.microsoft.com/fwlink/?LinkId=182475). You will need Microsoft.ResourceManagement.dll and Microsoft.ResourceManagement.Automation.dll for the cmdlets to work on a separate computer.
By default, Windows PowerShell does not allow you to run scripts. To enable this functionality, run the following command in Windows PowerShell as an Administrator: Set-ExecutionPolicy RemoteSigned

Important

This document tells you to run Windows PowerShell scripts. Before you run any Windows PowerShell scripts, be sure to review the content of these scripts to ensure that they will work in your environment. You may have to modify the scripts in this guide to meet requirements or adapt to configurations that are specific to your environment.

To perform the following procedures, you must ensure that the user account you are using has permission to read all configuration objects. If you use the FIM Service Administrator, you have that permission by default.

Tip

The best practice is to use the FIM 2010 R2 Administrator account for these tasks, and ensure that there are no Authentication or Authorization workflows configured for changes that the FIM 2010 R2 Administrator makes to configuration objects.

Step 1: Back up Pilot and Production Environments

Back up the FIM Synchronization Service and FIM Service of both the pilot (also known as test or test lab) environment and the production environment before you migrate any configuration settings. To complete this task, see the FIM 2010 Backup and Restore Guide.

Step 2: Exporting the FIM Service Schema Configuration from the Pilot Environment

To export the FIM 2010 R2 Service schema configuration from the pilot environment, it is necessary to export the FIM 2010 R2 objects from the Web service interface.

To export FIM Service Schema Configuration from the pilot environment

On the server in the pilot environment that hosts the FIM Service, open Windows PowerShell. To do this, click Start. In Start Search, start typing Windows PowerShell, and then click Windows PowerShell when it appears on the Start menu.
Run script Appendix A: Configuration Migration Windows PowerShell Scripts. If warnings and errors occur, try to track down the root cause and correct the problem by using the information in the text of the error message. You can see some common troubleshooting steps in Appendix C: Troubleshooting FIM Configuration Migration.
Rename the resulting schema.xml file to PilotSchema.xml. In Windows PowerShell, this file is located by default at %systemdrive%\Users\%username%. You should not edit the contents of these .xml files.
Copy the PilotSchema.xml file to a network share or Universal Serial Bus (USB) drive to save it.

Step 3: Export the FIM Synchronization Service Configuration from the Pilot Environment

The next procedure is to export the FIM 2010 R2 Synchronization Service configuration from the pilot environment.

To export the FIM Synchronization Service configuration from the pilot environment

On the computer that hosts the FIM 2010 R2 Synchronization Service, click Start. Type Synchronization Service, and then click Synchronization Service on the Start menu.

Note

The Synchronization Service was previously known as Identity Manager in ILM 2007.
Click File, and then click Export Server Configuration. If you are prompted, enter the appropriate account credentials or appropriate administrative credentials for the FIM Synchronization Service.
Review the Synchronization Service Manager warning indicating that management agents should not be run and configuration migration changes should not be made during export. Click OK.
Use Browse For Folder to locate or create an empty folder on a trusted backup location. To create a backup folder, browse to the location where you want to create the folder. and then click Make New Folder. Click OK. A series of XML documents is then placed in the folder that you selected as the backup destination.

Important

The export may fail if the backup folder is not empty because the export will not overwrite existing files.
Review the Export Server Configuration Progress Log and then click OK when the export is complete.

The resulting folder contains the complete configuration of the management agents and metaverse of the FIM Synchronization Service. This folder does not include rules extensions. Rules extensions must be imported according to the developer’s or vendor’s best practice.

Step 4: Export the FIM Service Policy and Synchronization Configuration from the Pilot Environment

To export the FIM Service configuration, you must export the FIM objects from the Web service.

To export the FIM Service Policy and Synchronization configuration from the pilot environment

On the server in the pilot environment running the FIM Service, open Windows PowerShell.
Run the script ExportPolicy.ps1, which you can find later in this document. If warnings and errors occur, try to track down the root cause and correct the problem by using the information in the text of the error message. You can see some common troubleshooting steps in Appendix C: Troubleshooting FIM Configuration Migration.

Note

All scripts that this document refers to are located in Appendix A: Configuration Migration Windows PowerShell Scripts.
Rename the resulting policy.xml file to pilot_policy.xml. In Windows PowerShell, this file is located by default at %systemdrive%\Users\%username%.
Copy Pilot_policy.xml to a network share or USB drive.

Warning

You should not edit the contents of these XML files.

Step 5: Install Production Environment

If FIM is not already present in the production environment, it must be installed. You would run installation to complete Scenario 1 of migrating configuration to an empty environment.

Installing the product is beyond the scope of this document. For more information, see the Installation Guide in the FIM 2010 documentation.

This step assumes that you have completed running both the FIM Synchronization Service and FIM Service installers. There is no need to perform additional steps after installation.

Step 6: Enable Maintenance Mode in the Production Environment

To eliminate unpredictable results, it is necessary to bring the production FIM Synchronization Service, FIM Service, and FIM Portal into maintenance mode.

To place the FIM Synchronization Service into maintenance mode, ensure that no Management Agents are running.

To place the FIM Service into maintenance mode, deny access to port 5725.

To deny access to port 5725

Open Windows Firewall with Advanced Security. To do this, click Start. Type Windows Firewall with Advanced Security, and then click Windows Firewall with Advanced Security on the Start menu when it appears.
In the console tree, click Inbound Rules.
In Inbound Rules, right-click the Forefront Identity Manager Service (Webservice) rule, and then click Disable Rule.

To place the FIM Portal into maintenance mode, disable the FIM Portal.

To disable the FIM Portal

Open Internet Information Services (IIS) Manager. To do this, click Start. Type Internet Information Services (IIS) Manager, and then click Internet Information Services (IIS) Manager when it appears on the Start menu.
Expand the objects in the console tree until you see SharePoint - 80.
Right-click SharePoint – 80, click Manage Web Site, and then click Stop.

Tip

If you have a message configured on another Web site in console tree that indicates your portal is undergoing maintenance, ensure that the site is running.

Step 7: Import the FIM Service Schema Configuration into the Production Environment

To import the FIM 2010 R2 Service schema configuration, it is necessary to identify changes between the pilot and production environment and then commit these changes. These changes are sent in to the Web service interface by using the credentials of the current Windows PowerShell user. Ensure that the current Windows PowerShell user has permission to read and write all configuration data in FIM 2010. These changes are subject to Authentication, Authorization, and Action workflows just as if they were made in the FIM Portal.

To import the FIM Service schema to configuration into the production environment

Open Windows PowerShell on the server with the production FIM service.
Copy pilot_schema.xml from the network or USB drive into the current directory that was created in Step 3.

Note

By default, in Windows PowerShell the current directory is the user directory %userprofile% (for example the administrator directory would be C:\Users\Administrators).
Run ExportSchema.ps1 to ensure that changes to the production schema are captured correctly.
Rename the resulting schema.xml file to production_schema.xml.

Warning

Before you import your configuration, ensure that there are no other users or processes communicating with the FIM Service. Also, you may need to run Update Statistics on the FIM Service database if time-outs occur during the imports.
Run SyncSchema.ps1. If warnings and errors occur, try to track down the root cause and correct the problem using the information in the text of the error message. You can see some common troubleshooting steps in Appendix C: Troubleshooting FIM Configuration Migration. The changes.xml file contains a list of changes to commit to the production system. These changes are ordered to guarantee precedence order.
Run CommitChanges.ps1. CommitChanges.ps1 assumes that changes.xml is in the current working directory. Any changes that cannot be completed are posted to the undone.xml file. You can use this file to resume partial imports. The count of UndoneImports is equal to zero (0). If warnings and errors occur or if the count of UndoneImports is not zero, try to track down the root cause and correct the problem by using the information in the text of the error message. You can see some common troubleshooting steps in Appendix C: Troubleshooting FIM Configuration Migration. Then, resume committing changes by using the Import-FIMConfg cmdlet, as shown in the example in ResumeUndoneImports.ps1.
Delete changes.xml and undone.xml, if present, or rename them and move them to another location for archiving.

Step 8: Import the FIM Synchronization Service Configuration into the Production Environment

The next procedure is to use the FIM 2010 R2 Synchronization Service Manager to import the FIM 2010 R2 Synchronization Service configuration.

To import the FIM Synchronization Service configuration into the production environment

Click Start, and then click Synchronization Service.

Tip

If necessary, type Synchronization Service to show the Synchronization Service option on the Start menu.
Click File, and then click Import Server Configuration. If you are prompted, enter the appropriate account credentials or appropriate administrative credentials for the FIM Synchronization Service.
Review the Synchronization Service Manager warning indicating that management agents should not be run and configuration migration changes should not be made during export. Click OK.
Use Browse For Folder to select the backup folder, and then click OK.
Review the Import Server Configuration, and then click OK when complete.

Step 9: Install the Custom DLLs Necessary for Custom Workflows

This document does not provide specific guidance for installing custom DLLs with FIM 2010. For this information, refer to the developer’s or vendor’s installation guidelines.

Note

It is important to ensure that custom DLLs are present before you migrate FIM Service configuration. These DLLs are not migrated when the FIM Service configuration is exported because they are not present in FIM 2010.

Some configuration objects refer to these DLLs. If the DLLs are not present, you may encounter failing requests during or immediately after migration. For example, custom workflow activities typically refer to Microsoft .NET classes, which are located in DLLs that are installed in the Global Assembly Cache (GAC). For more information, see Global Assembly Cache (https://go.microsoft.com/fwlink/?LinkId=182498).

Step 10: Import the FIM Service Policy and Synchronization Configuration into the Production Environment

To import the FIM 2010 R2 Service policy and FIM 2010 R2 Synchronization service configuration, first identify changes between the pilot and production environment, and then commit these changes. Unlike for a schema import, there are two key considerations to be aware of:

The SyncPolicy.ps1 has predefined join criteria for joining data objects. Open SyncPolicy.ps1, and inspect the join criteria that is stored in the $joinrules section. Ensure that the attributes that are used to join Person and Group resources are appropriate for your organization. Also ensure that there are no missing resources in the list.
Be prepared for failures the first time that you import some policy configuration that depends on data. Many customer configurations include sets with explicit references to Person or Group resources. These Person and Group resources, however, require synchronization and policy configuration to be created by the FIM Synchronization Service. You may have to run the CommitChanges.ps1, do a FIM 2010 R2 MA Export, and then run the ResumeUndoneImports.ps1. The CommitChanges.ps1 Windows PowerShell script will import as many changes as possible.

To import the FIM Service Policy and FIM Synchronization configuration to the production environment

Open Windows PowerShell on the server with the production FIM 2010 R2 Service.
Copy PilotPolicy.xml created in Step3 from the network drive or USB drive into the current directory.
Run the ExportPolicy.ps1.
Rename the resulting policy.xml file to production_policy.xml.
Run the SyncPolicy.ps1. A list of changes to commit to the production environment is output to the changes.xml file. The changes in the file are listed to guarantee precedence order.
Run CommitChanges.ps1. The CommitChanges.ps1 assumes that changes.xml is in the current working directory. Any changes that cannot be completed are posted to the undone.xml file. You can use this file to resume partial imports. The count of UndoneImports is equal to zero (0). If warnings and errors occur or if the count of UndoneImports is not zero, try to track down the root cause and correct the problem by using the information in the text of the error message. (You can see some common troubleshooting steps in Appendix C: Troubleshooting FIM Configuration Migration). Then, resume committing changes by using the Import-FIMConfg cmdlet, as shown in the example in ResumeUndoneImports.ps1.

Warning

You may experience errors while importing some of the changes into empty environments. In particular, Sets with explicit references to Person or Group resources often cannot be imported into an empty environment. You must either run an export on the FIM MA to populate the Person resource or change the definition of the Set to exclude the reference to the person.
Review the undone.xml in Notepad to classify the types of changes that could not be completed. To open the file in Notepad, run the command notepad undone.xml.
1. Look for sets that include filters or explicit members with globally unique identifiers (GUIDs) that point back to resolves.
2. Ensure that all attributes with FullyResolved=true have GUIDs that match resources in the production environment.
3. Ensure that all attributes with FullyResolved=false have GUIDs that match Resolve earlier in the file. Ensure that those Resolve ImportObjects can resolve to resources in the production environment. It may be necessary to create the resources manually, remove the references altogether, or run FIM MA export to populate them. A common scenario you may encounter is explicit references on the Administrators set. You can just remove the extra references when migrating to an empty environment.
4. To exclude a change, remove the entire ImportObject section referencing that object from undone.xml.
Any changes that cannot be completed are posted to the undone.xml file. You can use this file to resume partial imports. The count of UndoneImports is equal to zero (0). If warnings and errors occur or if the count of UndoneImports is not zero, try to track down the root cause and correct the problem by using the information in the text of the error message. (You can see some common troubleshooting steps in Appendix C: Troubleshooting FIM Configuration Migration). Then, resume committing changes by using the Import-FIMConfg cmdlet, as shown in the example in ResumeUndoneImports.ps1.
Delete changes.xml and undone.xml, if present, or rename them and move them to another location for archiving.

Step 11: Disable Maintenance Mode of the FIM Synchronization Service and FIM Service

No change is necessary to bring the FIM Synchronization Service out of maintenance mode.

To return the FIM Service to normal operation, allow access to port 5725.

To allow access to port 5725

Open Windows Firewall with Advanced Security.
In the console tree, click Inbound Rules.
On the Inbound Rules page, right-click the Forefront Identity Manager Service (Webservice) rule and then click Enable Rule.

To return the FIM Portal to normal operation, enable the FIM Portal.

To enable the FIM Portal

Open Internet Information Services (IIS) Manager.
Navigate to SharePoint – 80.
Right-click the site, click Manage Web Site, and then click Start.

Tip

If you have a message configured on another Web site in the console tree that indicates that your portal is undergoing maintenance, ensure that site is not running.