Migrating to VMware Workspace ONE Access Connector 21.08.XX Or Newer


In this post we will go over an in-place migration of VMware Identity Manager Connector 19.03.01 to Workspace ONE Access Connector 21.08.XX or NEWER. This documentation should work the same for newer versions of Workspace ONE Access Connectors such as 22.05.XX (simply replace "21.08.XX" with whatever version you migrating to from the 19.03.XX Connectors, such "22.05").

To clarify, this "in-place" migration retains the 19.03.01 connector (in place and running) while installing the 21.08.1 connector side-by-side. Once the migration is complete, the 19.03.01 connector software may be uninstalled from Windows Programs.


  1. An on-premises 21.08.XX (or newer) or SaaS Workspace ONE Access tenant.
  2. Workspace ONE Access tenant configured and working.
  3. Workspace ONE Access tenant with a Directory integrated with Active Directory (LDAP or IWA).
  4. Workspace ONE Access Super Admin login.


  1. VMware Documentation on Migrating to VMware Workspace ONE Access Connector 21.08 (Use this document as reference here).
  2. VMware Documentation on Upgrading to VMware Workspace ONE Access Connector 21.08 (Not needed here, but good to have as a reference).
NOTE: If needed, reference newer docs on docs.vmware.com for newer versions of Connectors.

High Level Process:

  1. Convert tenant by clicking RESET CONNECTOR SELECTION and selecting Workspace ONE Access 21.08 (or NEWER).

  2. Create a Configuration File for the new 21.08.x Connector Installer.

  3. Install the 21.08.1 Connector on the same system. DO NOT STOP OR UNINSTALL THE 19.03.01 CONNECTOR!
    NOTE: The 21.08.1 Connector version has the update for log4j 2.16. Updates containing log4j 2.17 and newer will be available in future product releases.
      1. You may be prompted to install .NET updates required for the Workspace ONE Access 21.08.1 Connector. If these updates require a reboot, it is ok to reboot for the .NET updates. DO NOT reboot further down after installation of the 21.08.1 or newer Connector is complete.

      2. Do a custom installation of the 21.08.1 Connector Installer.

      3. In order to alleviate a 443 conflict, deselect the KERBEROS AUTH SERVICE to avoid a TCP 443 port conflict issue. If Kerberos is desired, it can be installed after the fact or you can instead choose to migrate to a new Windows Server host vs. an "in-place" migration.

      4. Also, you may wish to do a CUSTOM installation to upload any necessary ROOT, Intermediate, or Issuing CA certificates. If you have them in PEM format, you can use that or individually upload all of the certs into the installer. This must be done during installation now (instead of in the admin UI after install).

      5. DO NOT REBOOT AFTER INSTALLATION (at least, not before the migration is completed).

      6. Do the 21.08.1 install on ALL Workspace ONE Access Connectors being "in-place" migrated before continuing.

  4. Perform the Directory and Connector migration as per the VMware Documentation on Migrating to VMware Workspace ONE Access Connector 21.08.
      1. When you’re ready to migrate, go back to the admin UI of the Workspace ONE Access tenant and refresh/reload the directories screen and walk through the wizard.
      2. If at any point you navigate away and need to get back to the migration wizard screen, just browse to the Directories tab and refresh/reload the admin UI.

  5. Ensure the Migration is Successful
      1. After testing authentications and completing the directory migration wizard, you will note the "LEGACY CONNECTORS" tab goes away. It is now safe to uninstall the 19.03.01 VMware Identity Manager Connector from the Windows Servers.

  6. Decommission and Uninstall 19.03.01 connectors

  7. Reboot the Connectors.

  8. Apply any Post Migration Modifications.
      1. If at this point you wish to install the KERBEROS AUTH SERVICE, you can rerun the installer and add in the KERBEROS AUTH SERVICE.
        WARNING: IF YOU UPDATE/REINSTALL, MAKE CERTAIN TO ADD ALL CERTS AGAIN AND ENSURE ALL OTHER SETTINGS ARE CORRECT (I.E. Fully configure all settings again as leaving them blank will reset them)!
      2. The Kerberos Service will require an internally accepted and trusted certificate. If one is NOT created, the service will create a self signed cert during installation. This self signed cert would then need to be trusted by systems using this for Kerberos authN (i.e. Windows domain joined systems). See my blog post on Removing and Re-adding Kerberos here.
      3. You may also remove any old Java (JRE) versions as the new 21.08.xx Access Connector utilizes OpenJDK. However, first check the JAVA_HOME (both User and System variables) value is set to the new OpenJDK path (typically "C:\Program Files\Workspace ONE Access\OpenJDK") before stopping all Workspace ONE Access services and removing JRE. For more information, see the VMware Workspace ONE Access documentation "Upgrading Java on the Workspace ONE Access Connector Server" for details.
      4. Reboot once complete.