Slipping out of the Microsoft stable recently with little fanfare, the AD FS Rapid Restore Tool. As the name suggests, this is a tool geared at aiding in the recovery of your AD FS configuration / environment, in the event of server failure or disaster. To date, effectively backing key material and/or relying parties has been a proverbial thorn-in-the-side for AD FS administrators, so the release of this utility is very interesting.

Does this tool do the trick? Let’s give it a whirl…

Download the MSI and install the tool.  You can get the MSI from here. Supported versions are AD FS 2012 R2 and AD FS 2016. The tool is directly installed on the farm node and the installation process is very straightforward ( a la Next Next Next).

With the tool installed we can launch a Administrative PowerShell prompt and then import the module.

Let’s look at some of the command option via Get-Help Backup-ADFS -full

As can be seen from the graphic above, when we call the Backup-ADFS cmdlet, backup of the AD FS configuration is possible to both the filesystem or to Azure. In these test scenarios, the local file system is used.

A backup folder (e.g. C:\ADFSExport) is created manually as the backup/restore location. The Backup-ADFS cmdlet is then run. Here’s the syntax used for testing.

Backup-ADFS -StorageType “FileSystem” -StoragePath “C:\ADFSExport\” -EncryptionPassword “12345678” -BackupComment “Clean Install of ADFS (FS)” -BackupDKM

Oops.. a warning. As the Microsoft documentation points out, your AD FS SSL/TLS certificate will only be backed up during the export if the private keys are marked as exportable and the associated Manage Private Keys permission is given to the user running the script. In the above example, my certificate does not fit that criteria. A simple way to check beforehand is to attempt to export the SSL certificate via the Certificate Export Wizard.  If “Yes, export the private key” is greyed out, it’s not exportable. Now go find that PFX ……

Where the script can’t handle the service communication certificate migration, the PFX should be manually imported on the replacement server before the restore script is run.

By the way, the token signing and decryption certificates (incl. private keys) used by AD FS are stored in the AD FS configuration database itself. These certificates are then encrypted using something called the Distributed Key Manager (DKM). A container is created in the local Active Directory  of your AD FS during installation of the first AD FS node in the farm. The DKM master key is then stored in this container. The recovery tool provides for backup of the DKM facility and in the export command-line above the “Backup-DKM” is used. I’m no expert on DKM, so if you require a more detailed information, I suggest you go hunting here.

Onto the recovery. Here I wanted to test a number of changes.

Same Server Recovery

For this simple test, we elected to remove the AD FS farm (primary) role  in each case and cleaned out the AD FS container in Active Directory (CN=ADFS,CN=Microsoft,CN=Program Data). A fresh installation of AD FS was then made, the tool installed and then the restore operation begun.  Any existing configuration database was overwritten.

Restore 1 – Basic

To begin with, in the first restore, we help the tool along a little bit by partially rebuilding the AD FS server. I added the AD FS role manually via Server Manager, specified the federation service name, the SSL certificate to use and the relevant service account. Here the recovery script was as follows:

Restore-ADFS -StorageType “FileSystem” -StoragePath “C:\ADFSExport\” -DecryptionPassword “12345678” -RestoreDKM

Restore worked fine. No errors and the WAP connected back to the “new” farm without issues.

Restore 2 – Complete

This option required providing the command-line with a little more information as the role was not pre-installed. Consequently, those missing elements, pre-loading of SSL/TLS service communications certificate aside, needed specifying.

Restore-ADFS -StorageType “FileSystem” -StoragePath “C:\ADFSExport\” -DecryptionPassword “12345678” -RestoreDKM -ADFSName “adfs.mydomain.com” -DBConnectionString “WID” -GroupServiceAccountIdentifier “MYDOMAIN\gmadfs$”

Again, no issues. Impressive.

That SSL error during the initial export was still bugging me though. Just to make sure that SSL export really was supported, I flipped the Service Communications certificate in AD FS to one with an exportable private key (the replacement certificate was one from a local test CA, complete with Server Authentication EKU). The cert then needed to be assigned to AD FS  via PowerShell.

dir cert:\LocalMachine\My
Set-AdfsCertificate -CertificateType Service-Communications -Thumbprint thumbprint
Set-AdfsSslCertificate -Thumbprint thumbprint

 

After an AD FS  restart, with the new certificate in place, I then reran a new export:

As can be seen from the above screenshot, with the exportable cert in place there were no SSL errors this time. Removing AD FS and then rerunning the Restore-ADFS cmdlet an additional  time then demonstrated that the SSL certificate was then imported as part of the recovery.  Nice.

New Server Recovery

Of course, no test is worth its weight in custard unless we actually go the extra mile and try and break stuff.  In the next scenarios, we’ll tweak the configuration a little, moving AD FS to a completely new server and do a database recovery to a new format.

Restore 1 – WID to SQL

As well as introducing a new server, complete with different IP, computer name etc., we will also migrate the recovered solution to a new database form factor, as part of the recovery. Via the script, the original Windows Internal Database (WID)-based AD FS solution will be refactored in SQL Server.

Restore-ADFS -StorageType “FileSystem” -StoragePath “C:\ADFSExport\” -DecryptionPassword “12345678” -RestoreDKM -ADFSName “fed.route443.net” -DBConnectionString “data source=sqlserverFQDN;initial catalog=adfsconfiguration;integrated security=true” -GroupServiceAccountIdentifier “MYDOMAIN\gmadfs”

The change in the script is minimal from previous cases. In order to effect the transition from WID to SQL we simply provide the necessary connection string in the Restore-ADFS cmdlet so that the recovery tool can provision the AD FS configuration and Artifact database on the SQL Server. Running the restore script against Backup ID 8 (in this example).

The restore is complete without errors. On the SQL Server in Management Studio, the databases are successfully provisioned.

On our Web Application Proxy (WAP) in a HOSTS file (or DNS – YMMV), we update the reference to the AD FS farm pointing to the new IP address. Excellent! Cue login test page and successful logon.

Restore 2 – SQL to WID

Believe it or not, the request to move from SQL to Windows Internal Database (WID) does come up from time-to-time on Technet forums, so I thought I’d validate this scenario also. Here we’re moving back our AD FS configuration database(s) running on a SQL workload to WID. We back up our ADFS/SQL server  and then copy the C:\ADFSExport folder to the newly minted server. Here the following syntax is then run:

Restore-ADFS -StorageType “FileSystem” -StoragePath “C:\ADFSExport” -DecryptionPassword “12345678” -RestoreDKM -ADFSName “adfs.mydomain.com” -DBConnectionString “WID” -GroupServiceAccountIdentifier “MYDOMAIN\gmadfs$”

Item 9 is the ADFS/SQL backup which we wish to restore. Again, on the WAP we point away from our old ADFS / SQL pair to our freshly restored ADFS / WID combination and test logon and we’re up and running.

Summary

This is an outstanding tool and one every AD FS administrator should be in possession of. Not to be underestimated, the AD FS Rapid Restore tool not only  adds great value to the recovery process, but also provides an excellent means for copying/mirroring your environment AD FS for testing. Moreover, as can be seen from the previous screenshots, it’s also an excellent way of backing up and charting your AD FS configurations vis-a-vis change management.