Upgrade instructions for the SURFsecureID ADFS plugin from version 1 to version 2

This page describes how to upgrade the SURFsecureID ADFS Plugin versions 1.0 and 1.0.1 to version 2.0. These are the only versions of the plugin that have been publicly released. An existing installation will run version 1.0 or version 1.0.1 of the plugin. The upgrade instruction for both versions are the same.

Version 2.0 of the ADFS Plugin was tested on Windows 2012R2, Windows 2016 and Windows 2019.

Please contact support@surfconext.nl if you have any questions about the upgrade process.

Summary

The new version of the SURFsecureID ADFS Plugin comes with a new installation process consisting of a text based setup program. You start the setup program from an elevated command prompt on the AD FS server. The setup program will upgrade a running AD FS server with a 1.x version of the ADFS plugin to version 2 of the ADFS plugin without the need for additional configuration. You must run the upgrade on each AD FS server in your farm, starting with the primary server. Do NOT run the uninstall script that came with the version 1.x of the plugin.

What is new in version 2.0

• Version 2.0 of the plugin adds support the SURFsecureID key rollover that is scheduled to take place Juli 2nd 2020. It does this by allowing two signing certificates to be configured. Both the old and the new certificate are included in the 2.0 version of the plugin and are automatically configured by the setup program.
• The plugin includes a new setup program that allows installation/upgrading, uninstallation, and reconfiguring the plugin. The setup program can also run a diagnostic check of the configuration of the plugin. The setup program has a text based user interface and must be started from an elevated command prompt.
• Support for look up of users in multiple domains and trusted forests.
• The ADFS 2.0 Plugin, its dependencies and its configuration files are now located in the ADFS directory (i.e. C:/Windows/ADFS). The plugin no longer stores part of its configuration in the configuration file of the AD FS Service. The assemblies are no longer in the GAC.
• Improved logging and error handling

Installation

The upgrade must be performed on each AD FS Server in the farm, starting at the primary AD FS Server. During the upgrade of the AD FS server, the setup program will restart the AD FS service. If you are using an AD FS farm, you can direct traffic away from the AD FS server being upgraded to prevent downtime.

Notices

• After upgrading the primary AD FS server, a secondary AD FS service that is still running the old version of the ADFS plugin can fail to load the ADFS plugin when that AD FS service restarts. Upgrade that server to resolve the issue.
• These instructions assume your AD FS is using a Windows integrated database (WID) to store its configuration and is not using a central MS-SQL server. The process is similar: first upgrade the primary, then the other servers
• The upgrade process works for ADFS Plugins that use the SURFsecureID Production or Test environments.

Preparation

• We recommend that you create a backup of the AD FS server(s) before you start the upgrade process
• Download the SetupPackage which containing the new ADFS plugin (see link on the top of this page) and unpack it on each AD FS server you want to upgrade. The plugin comes in a self extracting archive "SetupPackage-2.x.x.exe". The SetupPackage and the Setup.exe program inside it have been signed by "SURFnet bv".
• Check the configuration and the plugin on each ADFS server. You do this by running the setup program in check mode. This performs a check of the current installation and will report any problems that it finds:

  • Open an elevated command prompt on the AD FS server

  • Change to the directory where you unpacked the 2.0 version of the plugin and run "Setup.exe -c".

Upgrade process

Primary AD FS server

• Start the upgrade on the primary AD FS Server. The AD FS service must be running
• Open an elevated command prompt on the AD FS server
• Change to the directory where you unpacked the 2.0 version of the plugin and run "Setup.exe -i" to upgrade the plugin. This command will:
  • Read the current configuration of the plugin. Then asks if you want to continue with these settings (which is what you normally would do).
  • With the information from the 1.x configuration files write configuration files in the 2.0 format
  • Stop the AD FS service
  • Remove the 1.x version of the plugin
  • Install the 2.x version of the plugin
  • Start the AD FS service
• Verify in the EventLog of AD FS service that there are no errors (red balloons) for the plugin. There should be a message in the event log of the "AD FS Plugin" with its current configuration when it started
• Test that the plugin works by doing a login that requires MFA

Secondary AD FS server(s)

After the upgrade of the primary is complete, upgrade the ADFS Plugin on the secondary AD FS server(s).

Notes

If you did change any configuration settings of the plugin, which should not be necessary but is possible during the upgrade process, ensure:

• You sent the updated SAML configuration of the plugin (the MfaRegistrationData.txt file in the config directory of the SetupPackage) to SURFnet
• Make the same changes (i.e. use the same configuration) on each AD FS server in the farm.

Diagnostics / troubleshooting

Please contact support@surfconext.nl with question about the plugin.

Problems during installation

• The setup program stores a log of al actions performed in "MFA-extension.SetupLog.txt" in the SetupPackage-2.x.x directory. New messages are appended to the logfile.
• The setup program creates a backup of the files it removes or modifies in a backup directory with a name in the form: "backupYYY-MM-DDThhmmss"

 You can run the setup program in check mode to diagnose installation issues. This does not make any changes:

• Open an elevated command prompt on the AD FS server
• Change to the directory where you unpacked the 2.0 version of the plugin and run "Setup.exe -c"
  A properly working 1.0.* installation of the plugin should not result in error or warnings. If there are, there are more details in the setup log. Please contact support@surfconext.nl when you see this.

Fixing installation problems

There are two ways to fix installation issues. When you are at this point, please contact support@surfconext.nl. We want to understand what went wrong, and want to help you.

Option 1

You can run the setup program in reconfigure mode to try to repair an existing 2.x installation. The reconfigure option:

• (Re)registers the plugin with AD FS, when run on the primary
• Allows you to review and to change the configuration of the plugin
• Writes the (changed) configuration

 To reconfigure the plugin:

• Open an elevated command prompt on the AD FS server
• Change to the directory where you unpacked the 2.0 version of the plugin and run "Setup.exe -r"

If you did change any configuration settings of the plugin ensure:

• Send the updated SAML configuration of the plugin (the "MfaRegistrationData.txt" file in the "config" directory of the SetupPackage) to SURFnet
• Make the same changes (i.e. use the same configuration) on each AD FS server in the farm

Option 2

You can de a complete uninstall and reinstall of the plugin. If you keep the "CurrentSettings.json" file in the "config" directory of the SetupPackage, you do not have to re-enter the configuration parameters. Uninstallation does not remove the SP signing certificate from the certificate store.

To uninstall the plugin:

• Open an elevated command prompt on the AD FS server
• Change to the directory where you unpacked the 2.0 version of the plugin and run "Setup.exe -x" to uninstall the plugin.

To install version 2.x of the plugin:

• Open an elevated command prompt on the AD FS server
• Change to the directory where you unpacked the 2.0 version of the plugin and run "Setup.exe -i" to uninstall the plugin.

Problems with the plugin

When the plugin was installed successfully, but there are problem using the plugin:

• Check the event log of the AD FS Service for errors.
• The plugin has it's own event log "AD FS Plugin". Check this log for errors.