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.

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 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.

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.

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.

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.

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:

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.

Usually after building an AD FS/WAP farm I test locally from the Internet and the Intranet using (to-date) a fairly reliable source of verification that the service is up and running. I’m referring to, of course, the IdP sign-in page (../adfs/ls/idpinitiatedsignon.aspx). This offers a simple way of validating login via AD FS.

With Windows Server 2016, this page is no longer surfaced “out-of-the-box”.. if you want to do a SAML 2.0 IdP-initiated sign-on, this functionality will need to be enabled. Otherwise, connecting to the obligatory sign-in page, will produce an error similar to the following:

Testing from the Web Application Proxy itself directly, pointing to the AD FS farm, we may see an HTTP 503 Service Not Available error.

Via Powershell, it can be switched back on:

set-adfsproperties -EnableIdpInitiatedSignon $True

Now, before we get too hasty, knowing that we can turn it back on versus actually turning it back on are two different things 🙂 If it’s directly required, IdP-driven sign-on is a feature of your federation setup, then you may have no choice. For example, certain SaaS/Cloud applications simply don’t support SP-initiated workflow.

For some organizations I’ve worked for though, this page is seen as insidious because it reveals the relying parties configured on your AD FS farm anonymously.

AD FS 2.0

AD FS 2012 R2

Going back to AD FS 2.0, customers are often unwilling to float this data anonymously via the sign-in page and want to hide the RP enabled trusts visible on the page, sometimes re-writing the code behind to do so or even hiding it from the browser via obfuscation.

Whatever your view, it’s off by default in Windows Server 2016. Those of a paranoid bent may now breathe …………. in….. out….in… out…. there you go 🙂

I recently added my O365 tenant, for testing purposes, to a AD FS in Windows Server 2016 TP4 and noticed something rather unusual. Via the AD FS Management snap-in it was not possible to assign an access-control policy in AD FS to my Office365 Relying Party (RP). Looking at my RP Trusts, I could see the Access Control Policy section was blank.

Right-clicking over a Relying Party in AD FS 2016 TP4 reveals an additional menu option for editing Access Control Policies:

Doing this on the O365 RP, only the Issuance Authorization Rules pipeline is visible, nothing else.

If we compare that with a normal RP.

Right-clicking and selecting access control policy, the administrator is presented with the option of choosing an appropriate policy for that RP: in our case, the desire to use multi-factor authentication.

Why this does not appear on the O365 pipeline, I can only speculate. It might be partially explained by the fact that creating the Office 365 Identity Platform relying party is normally performed via PowerShell and Microsoft wanted to keep this procedure ubiquitous across all versions of AD FS since v2.0. For example, the following command will create the Office 365 Identity Platform RP should it not exist.

Alternatively, following the principle of Occam’s Razor, it could be Microsoft have simply not got round to updating their code to detect AD FS 2016 during O365 Relying Party creation Either way, from previous experiences of using MFA under Office 365 via AD FS 2012 R2, we do know it IS possible to use MFA with O365, so getting it working with AD FS 2016 just requires a little more effort. ..

Looking at our O365 RP in PowerShell (Get-ADFSRelyingPartyTrust) , we see no access policies configured. Under the O365 Relying Party it’s blank.

Compare this to an RP that does have an access control policy configured:

Since the UI doesn’t allow enabling MFA in an access policy for our O365 RP, playing around with PowerShell reveals that it is possible using the Set-ADFSRelyingPartyTrust cmdlet .

A while back I was lucky enough to chat with a member of the AD FS development team, to compare notes and discuss features missing or lacking in the current release. One item that popped up and which I rued the absence of, was the ability to customize relying parties. It turned out that this was a fairly common feature request. This omission, I’m glad to see, has been addressed in AD FS under Windows Server 2016. While the changes described are mostly cosmetic, they do allow some basic changes to the look and feel of the environment and, most importantly, improve overall user experience. Let’s have a look at some of these.

Our basic configuration consists of a Windows Server 2016 TP4 server with the AD FS role installed and the presence of a relying party trust to a SAML-based web application. Our relying party, called ‘simpleSAMLphp Demo’, will be the guinea-pig for this little exercise, though it plays no real part besides kicking off the sign-in process (RP-initiated sign-on). All changes are made on the AD FS side to customize the login experience.

Message-Level

Here we tinker with messages presented to the connecting user/device via the Set-AdfsRelyingPartyWebContent cmdlet.

In addition to customizing messages, it’s also possible to present specific logo and illustrations on a per RP basis. Here we copy the content to the AD FS server and then run the Set-AdfsRelyingPartyWebTheme cmdlet :

As with Windows Server 2012 R2, we can export the default theme to obtain the javascript (onload.js) that we wish to modify.

Export-AdfsWebTheme –Name default –DirectoryPath c:\content\default

One of the more common onload.js customization changes employed in AD FS 2012 R2 lay with a code change to support the use of sAMAccountName style formatting, similar to that supported in AD FS 2.0. This involved changing the onload.js file and then hardcoding the domain name into the form as described here.

Summary

Well, that’s nice, but these examples are just scratching the surface.. Take a look at the Get-AdfsRelyingPartyWebContent cmdlet and we can see there are multiple additional options that can be changed.