Migrate your existing directories and virtual apps collections from Workspace ONE Access 19.03 or 19.03.0.1 connectors to 21.08 connectors using the Migration Dashboard. The migration process is a staged approach that lets you test your environment with the new connectors before finishing the migration.

The migration process includes the following stages:

  • Install 21.08 Connectors

    Install the new 21.08 connectors, which contain the Directory Sync, User Auth, Kerberos Auth, and Virtual App services. At a minimum, install the Directory Sync service. Install the User Auth service if connector-based authentication is configured on the legacy connectors. Install the Kerberos Auth service if the Kerberos authentication method is configured on the legacy connectors. Install the Virtual App service if virtual apps collections are configured on the legacy connectors.

  • Migrate Directories

    In this stage, you migrate all your directory data using the Migrate Directory wizard. Most of the required information is pre-populated from your environment but you enter some sensitive values such as the directory Bind user password.

    Migrating the directories in this stage does not change any of your existing directory, authentication method, or identity provider configurations. You are still using the old connectors. The changes will take effect only after you go to the Preview stage.

  • Migrate Virtual Apps Collections

    In this stage, you select the connectors to which to migrate your existing virtual apps collections. The new settings will take effect only after you go to the Preview stage.

  • Preview

    In the Preview stage, you preview your environment with the new 21.08 connectors. The new Directory Sync, User Auth, Kerberos Auth, and Virtual App services from the 21.08 connectors perform directory sync, user authentication, and virtual apps sync. All authentication methods except for Kerberos are in outbound mode.

    The Preview stage is intended for you to test your environment thoroughly with the new services. Verify that directory sync, virtual apps sync, user authentication, and application launch are working as expected.

    In the Preview stage, you cannot create, edit, or delete directories, authentication methods, identity providers, or virtual apps collections.

    From the Preview stage, you can roll back to using the old connectors. When you roll back, the directory data that you migrated in the previous stage is still maintained. If you make any changes later to any of your existing directories, authentication methods, or identity providers, ensure that you migrate the directory data again.

  • Complete Migration

    When you are satisfied with testing your new environment, complete the migration. After you complete the migration, you cannot roll back to using the old connectors.

Prerequisites

  • Review the requirements listed in Requirements for Migrating to Workspace ONE Access Connector 21.08.
  • Verify that all the connectors in your environment are version 19.03.x. If any connectors are an older version, upgrade them to 19.03.x in order to migrate.
  • Prepare one or more Windows servers for the new 21.08 connectors. See the sizing guidelines in Installing Workspace ONE Access Connector 21.08.

    You can install the 21.08 connector on either a new server or the legacy 19.03.x connector server. However, if Kerberos authentication is configured on your legacy connector, you must use a separate Windows server to install the 21.08 Kerberos Auth service. Do not install the new Kerberos Auth service on the 19.03.x connector server. Workspace ONE Access does not support multiple instances of Kerberos on the same server.

    If Kerberos authentication is not configured on your legacy connector and you want to install the new 21.08 connector on the legacy 19.03.x connector server, see Migrating to Latest Connector on a Windows Server Running Workspace ONE Access 19.03.x for additional requirements and guidelines.

  • If you have an on-premises Workspace ONE Access service instance, upgrade it to 21.08 before migrating the connectors.
  • If you are installing the User Auth service, make sure that your environment does not contain any 20.x User Auth service instances. As part of migration, you will install 21.08 connectors. All the User Auth service instances must be version 21.08. Migration cannot proceed if you have mixed versions of the User Auth service.
  • If the RSA SecurID authentication method is configured on the 19.03.x connectors:
    • Verify that you are using RSA Authentication Manager appliance version 8.2 SP1 or later. Workspace ONE Access connector 21.08 supports RSA Authentication Manager appliance 8.2 SP1 and later.
    • If you have deployed multiple instances of the RSA Authentication Manager server, you must configure them behind a load balancer for the integration with Workspace ONE Access to work. Make sure that you meet the requirements listed in Workspace ONE Access Requirements for RSA SecurID Load Balancer in the Managing User Authentication Methods in Workspace ONE Access guide.
    • In the RSA Security console, verify that the connector is added as an authentication agent using the fully qualified domain name (FQDN), for example, connectorserver.example.com. If you have already added the connector as an authentication agent using the NetBIOS name instead of the FQDN, add another entry using the FQDN. Leave the IP address field empty for the new entry. Do not delete the old entry.
    • As part of the migration process, you configure the RSA SecurID authentication method. The information required to configure the authentication method includes the RSA Authentication Manager or load balancer server host name, communication port, access key, and the RSA Authentication Manager or load balancer server SSL certificate if the server uses a self-signed certificate. Because you obtain some of the information from the RSA Security Console, you also need the Security Console credentials.
    • If a proxy server is configured with the connector, the communication port that is configured for the RSA Authentication Manager server must be open on the proxy server.
  • If you are installing the User Auth service on a new Windows server, add the Windows server as an Agent in the RSA Authentication Manager server before starting the connector migration.
  • (Workspace ONE Access on-premises installations only) If any IDPs are associated with multiple directories, modify the configuration so that each IDP is only associated with one directory.
  • Ensure that the directory sync process is not running for any of the directories before you start the migration process.
  • If you enabled the People Search feature, ensure that the photo sync process is not running for any of the directories before you start the migration process.
  • If you are migrating a 19.03.x connector with no directory associated with it, keep in mind that when you select the Workspace ONE Access Connector 21.08 option in Step 5, the migration is considered complete and the 19.03.x connector is deleted from the service. If you later decide to use legacy connectors and you change your connector selection using the Reset Connector Selection button, the 19.03.x connector will not be displayed. You will need to reinstall the 19.03.x connector to reactivate it with the service.

Procedure

  1. Click the Identity & Access Management tab.
    The migration page appears. Migration Dashboard Intro
    Note: If you had previously selected the option to use Legacy Connectors, the migration page does not appear. You need to change your connector selection. Go to the Identity & Access Management > Setup > Legacy Connectors (or Connectors) page, click the Reset Connector Selection button, and select Workspace ONE Access Connector 21.08.
  2. Review the requirements, then click Get Started.
    The Migration dashboard appears. The page displays the various steps that you will take to complete the migration.
  3. In the Migration dashboard, click the Get Started link in the Install 21.08 Connector(s) section.
    Install 21.08 Connectors pane in the dashboard displays a Get Started button.
  4. In the Connectors page, click New.

    The image displays the Connectors page, which has a New button.
  5. In the Select the connector window, review the information and select the Workspace ONE Access Connector 21.08 option.
    Caution: Workspace ONE Access connector 21.08 does not support integration with Horizon Cloud Service on IBM Cloud, Horizon Cloud Service on Microsoft Azure with Single-Pod Broker, or ThinApp. If you plan to integrate these types of virtual apps, select Legacy Connectors to exit the migration process. Only legacy connectors support these types of virtual apps.
    Important: Make your choice carefully, considering your business needs. If you want to change your selection later, you can do so only up to a certain point in the migration process. See Resetting Connector Selection in Workspace ONE Access.
  6. Follow the Add New Connector wizard to download the connector installer and the required configuration file, then install the new connector.
    The Download Installer page has a link to myvmware.com.
    For installation information, see Installing VMware Workspace ONE Access Connector 21.08. Specifically, see "Prerequisites for Installing the Workspace ONE Access Connector" and "Installing the Workspace ONE Access Connector".
    When you install the connector, make sure that you install the Directory Sync service. Install the User Auth service if connector-based authentication is configured on the legacy connectors.The Kerberos Auth service is required only if the Kerberos authentication method is configured on any of your legacy connectors. Install the Virtual App service if virtual apps collections are configured on the legacy connectors or if you plan to configure them on the new connector.
    Caution: At the end of the installation process, you might get a prompt to restart the system. Do not restart the system if you are installing the 21.08 connector on a 19.03.x connector server. Restart the system only after the entire connector migration process is complete.
    Caution: If you are installing the User Auth service, make sure that all User Auth service instances in your environment are version 21.08, and that there are no 20. x User Auth service instances. You cannot proceed with migration if you have mixed versions of the User Auth service.
  7. When the connector installation is successfully completed, return to the Migration dashboard in the Workspace ONE Access service console.
  8. In the Migrate to New Connectors section, migrate all your directories, one by one.

    The Migrate Directories pane in the Migration Dashboard lists two directories, with a Migrate button next to each.
    The Migrate Directories section lists all the Active Directory and LDAP directories in your tenant. You must migrate all the directories listed before you can complete the migration.
    Note: Migrating the directories in this step does not change any of your existing directory, authentication method, or identity provider configurations and will take effect only after you preview the changes in the next step.
    1. Click the Migrate button next to the directory.
      The Migrate Directory wizard appears. The wizard is customized to the directory you are migrating. Additional pages appear for the authentication methods that are configured on the directory.
    2. On the Directory page, enter the Bind user password for the directory.
      The Directory Sync Host(s) list displays the new 21.08 connector hosts that have the Directory Sync service installed. Select one or more hosts to use to sync the directory.
      Migrade directory wizard - directory page
    3. (Appears only if Kerberos auth method is configured) On the Kerberos page, specify the information required to migrate the Kerberos authentication method.
      • Source Connector: The source connector is preselected. You can select another connector if the preselected connector is not available.
      • Kerberos Auth Host(s): The list displays the new 21.08 connector hosts that have the Kerberos Auth service installed. Select one or more hosts to use for Kerberos authentication.

      Migrate Directory - Kerberos page

    4. On the Password page, specify the information required to migrate the Password authentication method.
      • Source Connector: The source connector is preselected. You can select another connector if the preselected connector is not available.
      • Bind Password: Enter the Bind user password for the directory.
      • User Auth Host(s): The list displays the new 21.08 connector hosts that have the User Auth service installed. Select one or more hosts to use for Password authentication.

      Migrate Directory - Password

    5. (Appears only if RADIUS authentication method is configured) On the RADIUS page, specify the information required to migrate the RADIUS authentication method.
      • Source Connector: The source connector is preselected. You can select another connector if the preselected connector is not available.
      • Shared secret: The shared secret for the RADIUS server.
      • User Auth Host(s): The list displays the new 21.08 connector hosts that have the User Auth service installed. Select one or more hosts to use for RADIUS authentication.

      Migrate directory - Radius page

    6. (Appears only if RSA SecurID authentication method is configured) On the SecurId page, specify the information required to migrate the RSA SecurID authentication method.
      • Source Connector: The source connector is preselected. You can select another connector if the preselected connector is not available.
      • Number of authentication attempts allowed: Enter the maximum number of failed login attempts when using the RSA SecurID token. The default is five attempts.
        Note: If you are migrating multiple directories that use RSA SecurID authentication, configure Number of authentication attempts allowed with the same value for each RSA SecurID configuration. If the value is not the same, SecurID authentication fails.
      • SecurID Server Hostname: Enter the RSA Authentication Manager server host name, for example, myserver.example.com. If you have configured multiple instances of the RSA Authentication Manager server behind a load balancer, enter the load balancer host name instead. For example, lb.example.com.
      • SecurID Server Communication Port: Enter the communication port of the RSA Authentication Manager instance. The default port is 5555. To get the communication port number, log in to the RSA Security Console, navigate to the Setup > System Settings > RSA SecurID Authentication API page, and copy the Communication Port.
      • SecurID Server Access Key: Enter the Access Key from the RSA Authentication Manager instance. To get the access key, in the RSA Security Console, navigate to the Setup > System Settings > RSA SecurID Authentication API page, and copy the Access Key listed under Agent Credentials.
      • SecurID Server CA/SSL certificate: If the RSA Authentication Manager server or the load balancer server has a self-signed certificate, copy and paste the certificate into the text box. If the server has a certificate signed by a public Certificate Authority, uploading a certificate is not required.
      • Authentication Method Timeout in seconds: Enter the number of seconds for which the authentication attempt should be available. The authentication attempt times out after that. The default value is 180 seconds.
      • User Auth Host(s): The list displays the new 21.08 connector hosts that have the User Auth service installed. Select one or more hosts to use for RSA SecurID authentication.

      The SecurID page of the wizard displays.
    7. (Appears only if Kerberos authentication is configured) On the Identity Provider page, enter the connector load balancer's FQDN to use for the new identity provider that will be created for Kerberos authentication during migration.
      The current load balancer FQDN is displayed for reference. This is the current IdP Hostname value in the directory’s identity provider page.
      If you have only one 21.08 connector, and no load balancer, enter the connector's FQDN.
      Identity Provider page of Migrate Directory wizard
    8. In the Summary page, verify your selections and click Save.
      The directory migration data is saved. You can view the settings by clicking the Summary button next to the directory in the Directory Migration dashboard. The Migrate Directories section on the dashboard is green. The migrated directories are listed and a Review button is displayed next to them.
      If you want to make any changes to the information you entered, click Start Over in the Summary page. This discards the migration data you entered for the directory and lets you migrate the directory again.
      The migrated directories are listed, and a Start Over button appears.
    9. Migrate the rest of the directories.
  9. In the Migrate Virtual Apps Collections section, select the connectors to which to migrate your virtual apps collections.
    1. Click Migrate.

      The Migrate Virtual Apps Collections pane has a Migrate button.
    2. In the Migrate Virtual Apps Collections window, select the 21.08 connector to use for each virtual apps collection. All connectors that have the Virtual App service installed appear in the drop-down menu. Select a connector that has the Virtual App service in Active state. The state is displayed next to the connector name. You can add multiple connectors for high availability. If you add multiple connectors, arrange them in fallback order.
      Note: You must migrate all virtual apps collections at the same time. You cannot select specific collections to migrate.
    3. Click Save.
    For example:
    You can select a connector for each virtual apps collection.

    Virtual apps collections will be migrated when you go to the Preview stage.

    Note: You can add more connectors after you complete the migration, You can also change the connectors you selected for virtual apps collections.
  10. In the Complete Migration section, click Start Preview to start the migration process.

    The Complete Migration pane displays a Start Preview button.
    In the Preview stage, the new 21.08 connectors are used. Directory sync is performed by the new Directory Sync service, user authentication is performed by the new User Auth service, Kerberos authentication is performed by the new Kerberos Auth service, and virtual apps sync is performed by the new Virtual App service. In the Preview stage, you cannot make any changes to your directories, authentication methods, identity providers, or virtual apps collections, or create new ones. You can view the converted identity providers in the Identity Providers tab and the converted authentication methods in the Connector Authentication Methods tabs. All authentication methods except for Kerberos are in outbound mode.
    Note: In the Workspace ONE Access 21.08 on-premises virtual appliance, the Connector Authentication Methods tab is named Enterprise Authentication Methods.
    Note: If the People Search feature was enabled in your deployment of the Workspace ONE Access service, you must manually sync the directories without the Safeguard settings. In the Workspace ONE Access console, select the directory in the Identity & Access Management > Directories page and click Sync > Sync without Safeguards.
    Important: Test your environment thoroughly in the Preview stage and verify that it is working as expected. Verify that directory sync, virtual apps sync, user login, and application launch are working.
  11. If you determine that your environment is not working correctly, or if you want to make any changes to your directories, authentication methods, identity providers, or virtual apps collections, cancel the Preview stage and return to using the old connectors.
    Go to the Identity & Access Management > Manage > Directories page, click Continue Migration, and, in the Directory Migration dashboard, click Abort in the Complete Migration section.
    The Complete Migration pane has an Abort button and a Complete button.
    If you make any changes to your directories, authentication methods, or identity providers subsequently, make sure that you migrate the directories again in the Migrate to New Connectors section.
  12. After you verify that your environment is working as expected in the Preview stage and you are ready to complete the migration, return to the Directory Migration dashboard by going to the Identity & Access Management > Manage > Directories page and clicking Continue Migration.
    Caution: After you complete the migration, you cannot roll back to the old connectors.

    Click Complete to complete the migration.


    The Complete Migration pane has an Abort button and a Complete button.

Results

All your directories and virtual apps collections are migrated to the new 21.08 connectors. The new Directory Sync, User Auth, Kerberos Auth, and Virtual App services now perform directory sync, user authentication, and virtual apps sync.

New identity providers are created for each directory and appear in the Identity Providers tab with the name Migrated IDP for directory. The new identity providers are of type Built-in. For Kerberos authentication, a separate identity provider of type Workspace_IDP is created.

All authentication methods except for Kerberos are converted to outbound methods and are renamed with the (cloud deployment) suffix. For example, the Password authentication method is renamed to Password (cloud deployment). You can view and manage the new authentication methods from the Connector Authentication Methods tab.

Note: In the Workspace ONE Access 21.08 on-premises virtual appliance, the tab is named Enterprise Authentication Methods.

What to do next

When the migration is completed, you can uninstall the old 19.03.x connectors from the servers on which they are installed.

After the migration is complete, you no longer need the Integration Broker for Citrix integrations. The required functionality is now part of the Virtual App service.

For Horizon integrations, ensure that the Horizon Connection Servers have valid certificates signed by a trusted Certificate Authority (CA). If the Horizon Connection servers have self-signed certificates, you must upload the certificate chain to the Workspace ONE Access connector instances on which the Virtual App service is installed to establish trust between the connectors and the Horizon Connection servers. This is a new requirement in Workspace ONE Access connector 21.08. You upload the certificates using the connector installer. See Installing VMware Workspace ONE Access Connector for more information. Make sure that you restart the connector services after uploading the certificates.