To upgrade Windows-based Workspace ONE Access connector 20.10.x or 20.01.x to version 21.08, you download the new installer from My VMware to your connector server and run the installer. You do not need to uninstall the old version of the connector.

During upgrade, the existing Directory Sync, User Auth, and Kerberos Auth services are suspended. The services are restarted automatically after upgrade finishes.

Important Considerations

  • If you plan to install the Virtual App service, you must download and use a new es-config.json configuration file from the Workspace ONE Access console to establish the connection between the Workspace ONE Access service and the connector. If you are not installing the Virtual App service, you do not need a new configuration file. The upgraded connector can use the same configuration file that is being used by the existing connector.
    Note: If the password of your existing es-config.json configuration file contains the characters & or %, generate a new configuration file with a password that does not contain these characters. The & and % characters are not supported.
  • The configuration of the RSA SecurID (cloud deployment) authentication method has changed in the 21.08 release. If you have configured the RSA SecurID (cloud deployment) authentication method, you must delete it from access policies before upgrading all the User Auth service instances and then reconfigure it after the upgrade. As this results in downtime of RSA SecurID-based login, plan the timing of your upgrade accordingly.

    The high-level steps to perform the upgrade are:

    1. Verify that you are using RSA Authentication Manager appliance 8.2 SP1 or later, which are the versions supported by Workspace ONE Access connector 21.08.
    2. Before you upgrade the connector, remove the RSA SecurID (cloud deployment) authentication method from the access policies in which it is used.
    3. Upgrade all the connectors on which the User Auth service is installed to version 21.08.
    4. If a proxy server is configured with the connectors, verify that the communication port that is configured for the RSA Authentication Manager server is open on the proxy server.
    5. If you have deployed multiple RSA Authentication Manager server instances, you must configure them behind a load balancer and meet the Workspace ONE Access requirements for the load balancer.
    6. 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.
    7. Update the RSA SecurID (cloud deployment) authentication method configuration.
    8. Add the RSA SecurID (cloud deployment) authentication method to access policies.
  • Make sure that you upgrade all connector instances on which the User Auth service is installed to 21.08. Workspace ONE Access does not support mixing versions 21.08 and 20.x of the User Auth service.
  • Workspace ONE Access connector 21.08 supports the following types of proxies:
    • Unauthenticated HTTP proxies
    • Unauthenticated HTTPS (SSL) proxies
    • Authenticated HTTPS (SSL) proxies

Prerequisites

  • Review Upgrading to VMware Workspace ONE Access Connector 21.08.
  • If your connector installation is on a virtual Windows server, take a snapshot of the virtual machine before upgrading.
  • If you plan to install the Kerberos Auth service or Virtual App service, ensure that you join the connector server to the domain.
  • If you have configured the RSA SecurID (cloud deployment) authentication method, ensure that you are using RSA Authentication Manager appliance version 8.2 SP1 or later.
  • If you have configured the RSA SecurID (cloud deployment) authentication method, remove the authentication method from access policies before you upgrade all the connector instances that have the User Auth service installed.
    1. In the Workspace ONE Access console, navigate to the Identity & Access Management > Manage > Policies page.
    2. Review each policy and remove the RSA SecurID (cloud deployment) authentication method if it is part of the policy.

      Make a note of the changes you make so that you have the information required to add the authentication method back after upgrading the connector.

  • If you are upgrading from version 20.01.x, and you have configured a directory of type Active Directory over Integrated Windows Authentication (IWA), deselect the STARTTLS option in the directory configuration in the Workspace ONE Access console before upgrading to the 21.08 connector. After upgrade, the functionality of Active Directory over IWA will be incompatible with the STARTTLS option.

    To edit the directory configuration, navigate to the Identity & Access Management > Manage > Directories page, select the directory, deselect the This directory requires all connections to use STARTTLS check box, and click Save.

    Note: If you applied the hotfix described in Knowledge Base article 77158 to connector 20.01 or upgraded to connector 20.01.0.1 or 20.10, you might have already deselected the STARTTLS option for Active Directory over IWA. Verify that the setting is deselected.
  • In the Workspace ONE Access console, suspend the connector services that are currently installed.
    1. Navigate to the Identity & Access Management > Setup > Connectors page.
    2. Select the connector, then click Manage.
    3. Click the toggle next to each service name to suspend the service.
  • You need the following account information:
    • My VMware credentials
    • If the Kerberos Auth service is already installed, the domain user credentials that are being used to run the service
    • If you plan to install the Kerberos Auth service or the Virtual App service during the upgrade, you need a domain user account to run these services. While these services run with domain user account privileges, the Directory Sync and User Auth services run with lower privileges.
    • If you use the RSA SecurID (cloud deployment) authentication method, you require the RSA Security Console credentials to obtain the information required to reconfigure the authentication method in the Workspace ONE Access console after upgrading all the connector instances.

Procedure

  1. If you need a new configuration file, generate it from the Workspace ONE Access console.
    1. Log in to the Workspace ONE Access console as the System domain admin.
      Tip: In cloud deployments, the System domain admin is the admin whose credentials you receive when you get your Workspace ONE Access tenant. In on-premises deployments, the System domain admin is the admin user that is created when you install a Workspace ONE Access instance.
    2. Navigate to the Identity & Access Management > Setup > Connectors page.
    3. Click New.
    4. In the Add New Connector wizard, click Next.
    5. In the Download Configuration File page, generate the configuration file by creating a password and clicking Download Configuration File.
      The password must have a minimum of 14 characters and include an uppercase character, a lowercase character, a numeric digit, and a special character. Do not use the & or % characters. All characters must be visible, printing ASCII characters.
      The configuration file is used to establish communication between the enterprise services you install and the Workspace ONE Access tenant. The file is named es-config.json by default.
      Caution: The configuration file contains sensitive information such as the tenant URL, tenant ID, the client ID and client secret for each of the enterprise services, and the password hash. It is critical that you do not share the file or expose it publicly.
    6. Transfer the configuration file to the connector server.
  2. Download Workspace ONE Access Connector 21.08.0.0 from My VMware.
    1. Log in to https://my.vmware.com.
    2. Navigate to the VMware Workspace ONE Access 21.08 Download page.
    3. Download Workspace ONE Access Connector 21.08.0.0.
  3. Save the installer file on the Windows server on which the earlier version of the connector is installed.
  4. Double-click the Workspace One Access Connector Installer.exe file to run the installer.
    The installer detects that an upgrade is needed and guides you through the upgrade process. The wizard displays an upgrade page.
  5. Follow the wizard to upgrade the connector.
    While upgrading, keep the following in mind:
    • During the upgrade, the installer installs OpenJDK 8.
    • During the upgrade, you can modify any of the settings for existing services. You can also install other services. For example, you can install the new Virtual App service. Or, if your existing installation includes only the Directory Sync service and you want to install the User Auth service and Kerberos Auth service, you can do so during the upgrade.

      See Installing VMware Workspace ONE Access Connector 21.08 for information about requirements, sizing, installation, and settings.

    • With the 21.08 connector, you can specify multiple external syslog servers to store application-level event messages, instead of being limited to one server. You can enter the syslog servers on the Specify Syslog Server Information page of the wizard during the upgrade.

      Use the following format:

      host:port,host:port,host:port

      where host is the fully qualified domain name or IP address of the syslog server and port is the port number. For example:

      syslog1.example.com:514,syslog2.example.com:601,syslog3.example.com:163

  6. After upgrade finishes successfully, verify that the upgraded services are running on the Windows server.
    The connector services have the following names:
    • VMware Directory Sync Service
    • VMware User Auth Service
    • VMware Kerberos Auth Service
    • VMware Virtual App Service

    The services display Running status.

Results

The connector upgrade is complete. You can verify that the new version of the connector is installed by navigating to Control Panel > Programs > Programs & Features on the Windows server and checking the connector version listed.

What to do next

  • In the Workspace ONE Access console, click the refresh icon on the Identity & Access Management > Setup > Connectors page and verify that the upgraded services are active and the health status is green.
    For example:
    The Connectors page lists one connector with the Directory Sync, User Auth, Kerberos Auth, and Virtual App services installed. All the services are Active and display a green check box in the Health column.
  • If the RSA SecurID (cloud deployment) authentication method was configured in your original installation, reconfigure the authentication method after upgrading all the connector instances that have the User Auth service installed.
    1. If you have deployed multiple RSA Authentication Manager server instances, you must configure them behind a load balancer and meet the Workspace ONE Access requirements for the load balancer. See Workspace ONE Access Requirements for RSA SecurID Load Balancer.
    2. If a proxy server is configured with the connectors, verify that the communication port that is configured for the RSA Authentication Manager server is open on the proxy server.
    3. 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.
    4. Update the RSA SecurID (cloud deployment) authentication method configuration for all the directories that included it in the original installation.

      See Configure RSA SecurID Authentication in Workspace ONE Access for information about the new configuration.

    5. Add the RSA SecurID (cloud deployment) authentication method to all the access policies that included it in the original installation.

      You can edit the access policies from the Identity & Access Management > Manage > Policies page.