Use the Migration Dashboard to Migrate to Workspace ONE Access Connector 22.09

Migrate your existing directories and virtual apps collections from Workspace ONE Access 19.03 or 19.03.0.1 connectors to 22.09 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.

Migration Stages

The migration process includes the following stages:

Install 22.09 Connectors
Install the new 22.09 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 22.09 connectors. The new Directory Sync, User Auth, Kerberos Auth, and Virtual App services from the 22.09 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 22.09.
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 before beginning the migration.
Prepare one or more Windows servers for the 22.09 connectors.
See Requirements for Migrating to Workspace ONE Access Connector 22.09 for more information.
If you are using an on-premises Workspace ONE Access virtual appliance, upgrade it to 22.09 before migrating the connectors.
If you are installing the User Auth service, make sure that your environment does not contain any 22.05, 21.x, or 20.x User Auth service instances. As part of migration, you will install 22.09 connectors. All the User Auth service instances in your environment must be version 22.09. 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 22.09 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.
Before migrating directories, enable the Sync group members to the directory when adding group option and verify that users, groups, and group memberships are synced correctly.
1. In the Workspace ONE Access console, select Settings > Login Preferences.
2. Click Edit, select the Sync group members to the directory when adding group check box, and click Save.
3. Go to the directory's Sync Settings tab, expand the Groups section, and click Save. Then expand the Users section and click Save.
  Important: This step is required to ensure that the change in the Login Preferences page takes effect.
4. Wait until a few directory sync runs complete successfully with the correct users, groups, and group memberships syncing to Workspace ONE Access.
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 Latest Workspace ONE Access Connector option in Step 5, the migration is considered complete and the 19.03.x connector is deleted from the tenant. If you decide later to use legacy connectors and you change your connector selection using the Reset Connector Selection button, the 19.03.x connector will not appear. You will have to reinstall the 19.03.x connector to reactivate it with the service.

Procedure

In the Workspace ONE Access console, select Integrations > Connectors (Legacy) to go to the Legacy Connectors page.
On the Legacy Connectors page, click the Reset Connector Selection button, and click Proceed in the confirmation pop-up.
In the Connector Usage Confirmation dialog box, select Latest Workspace ONE Access Connector, click OK, and confirm your selection.
Select Integrations > Directories to go to the Directories page.
The Directory and Virtual Apps Migration page appears.
Click Start Migration.
The Migration Dashboard appears. The dashboard displays the steps that you will take to complete the migration. Review the information on the page.
In the Migration dashboard, in the Install the latest Workspace ONE Access Connector(s) section, click Get Started.

The Connectors page appears.
In the Connectors page, click New.
Follow the Add New Connector wizard to download the connector installer and the required configuration file, then install the new connector.

For installation information, see the Installing VMware Workspace ONE Access Connector 22.09 guide.
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:
- When you generate the configuration file for the connector in the Workspace ONE Access console, make sure that you create a password that meets the rules.
  The password must have a minimum of 14 characters and include at least one number, one uppercase character, and one special character. Only the following special characters are allowed:
  @ ! , # $ { } ( ) _ + . < > ? *
  All characters must be visible, printing ASCII characters.
- During installation, the option to enable FIPS mode appears on the Specify Configuration File page of the installer. Do not select the Enable FIPS option. FIPS mode is not supported when you migrate from legacy connectors to the 22.09 connector.
- 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 new connector on a 19.03.x connector server. Restart the system only after the entire connector migration process is complete.
- If you are installing the User Auth service, make sure that all User Auth service instances in your environment are version 22.09, and that there are no 22.05, 21.x or 20.x User Auth service instances. You cannot proceed with migration if you have mixed versions of the User Auth service.
When the connector installation is successfully completed, go to the Integrations > Directories page in the admin console and click Continue Migration.
In the Migrate Directories section of the Migration dashboard, migrate all your directories, one by one.

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 22.09 connector hosts that have the Directory Sync service installed. Select one or more hosts to use to sync the directory.
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 22.09 connector hosts that have the Kerberos Auth service installed. Select one or more hosts to use for Kerberos authentication.
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 22.09 connector hosts that have the User Auth service installed. Select one or more hosts to use for Password authentication.
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 22.09 connector hosts that have the User Auth service installed. Select one or more hosts to use for RADIUS authentication.
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 22.09 connector hosts that have the User Auth service installed. Select one or more hosts to use for RSA SecurID authentication.
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 22.09 connector, and no load balancer configured, enter the connector's FQDN.
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 Review button next to the directory in the Directory Migration dashboard.
  
  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.
9. Migrate the rest of the directories.
In the Migrate Virtual Apps Collections section, select the connectors to which to migrate your virtual apps collections.
1. Click Migrate.
2. In the Migrate Virtual Apps Collections window, select the 22.09 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:

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.
In the Complete Migration section, click Start Preview to start the migration process.
In the Preview stage, the new 22.09 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 Integrations > Identity Providers page and the converted authentication methods in the Integrations > Connector Authentication Methods page. All authentication methods except for Kerberos are in outbound mode.
Follow these guidelines in the Preview stage:
- For each directory, you must run the first directory sync in Preview stage without safeguards. Select Sync > Sync without Safeguards on the directory page.
  Keep in mind that the first sync takes a long time because all users and groups are updated.
  After the directory sync completes successfully, verify that the correct users, groups, and group memberships were synced before proceeding with the rest of the migration process.
- If People Search is enabled in your deployment, you must manually sync the directories without the safeguard settings. To sync a directory without safeguards, select Sync > Sync without Safeguards on the directory page.
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.
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 Integrations > Directories page, click Continue Migration, and, in the Directory Migration dashboard, click Abort in the Complete Migration section.

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 Directories section.
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 Integrations > 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.

Results

All your directories and virtual apps collections are migrated to the new 22.09 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 page 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 page.

What to do next

When the migration is complete, you must uninstall the old 19.03.x connectors from the servers on which they are installed.
If you migrated ThinApp virtual apps collections, uninstall the Linux connectors.
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 and Horizon Cloud integrations, ensure that the Horizon Connection Servers, or the Horizon Cloud tenant's underlying Horizon servers, have valid certificates signed by a trusted Certificate Authority (CA). If the Horizon 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 servers. This is a new requirement beginning with Workspace ONE Access connector 21.08. You upload the certificates using the connector installer. See Installing VMware Workspace ONE Access Connector 22.09 for more information. Make sure that you restart the connector services after uploading the certificates.