To upgrade your Windows-based Workspace ONE Access connector version 22.05, 21.08.x, 20.10.x, or 20.01.x to version 22.09, you download the new installer from VMware Customer Connect 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, Kerberos Auth, and Virtual App services are suspended. The services are restarted automatically after upgrade finishes.
Important Considerations
- FIPS mode
If you upgrade from a version 22.05 installation that had FIPS mode enabled, the upgraded connector runs in FIPS mode. If you upgrade from a version 22.05 installation that did not have FIPS mode enabled, or from a version earlier than 22.05, the upgraded connector runs in non-FIPS mode. You cannot select or deselect FIPS mode during or after upgrade. To change the FIPS mode setting, you must perform a fresh installation. See Upgrading to VMware Workspace ONE Access Connector 22.09 for more information.
- es-config.json file
The es-config.json configuration file establishes the connection between the Workspace ONE Access service and the connector. In most cases, the upgraded connector can use the same configuration file that is being used by the existing connector. However, in some cases, you must generate a new es-config.json file from the Workspace ONE Access console.
- If you are upgrading from version 20.01.x or 20.10.x and you intend to install the Virtual App service during or after upgrade, you must generate and use a new es-config.json configuration file. If you do not plan to install 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.
- If you are upgrading from version 21.08.x or 22.05, and you generated an es-config.json configuration file after the Workspace ONE Access 21.08 release or September 2021 Cloud release, you do not need to generate a new es-config.json file.
- Regardless of the version from which you are upgrading, if the password of your existing es-config.json configuration file does not meet the current password rules, you must generate a new configuration file with 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.
- If you have forgotten the password for your existing configuration file, generate a new configuration file and use it during the upgrade.
To generate a new file, in the Workspace ONE Access console, go to , click New, create a new file on the Download Configuration File page of the wizard.
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. - The configuration of the RSA SecurID (cloud deployment) authentication method changed beginning with the 21.08 release. If you are upgrading from a 20.10.x or earlier connector that has the RSA SecurID (cloud deployment) authentication method configured, you must delete the authentication method 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:
- 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 and later.
- Before you upgrade the connector, remove the RSA SecurID (cloud deployment) authentication method from the access policies in which it is used.
- Upgrade all the connectors on which the User Auth service is installed to version 22.09.
- 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.
- 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.
- 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.
- Update the RSA SecurID (cloud deployment) authentication method configuration.
- 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 version 22.09. Workspace ONE Access does not support mixing versions 22.09, 22.05, 21.08, and 20.x of the User Auth service.
- Workspace ONE Access connector 22.09 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 22.09.
- 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 are upgrading from a 20.10.x or earlier connector that has the RSA SecurID (cloud deployment) authentication method configured, remove the authentication method from access policies before you upgrade all the connector instances that have the User Auth service installed.
- In the Workspace ONE Access console, navigate to .
- 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. After upgrade, the functionality of Active Directory over IWA will be incompatible with the STARTTLS option.
To edit the directory configuration, navigate to the 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 later, 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 all the connector services.
- Select .
- Select the connector, then click Manage.
- Click the toggle next to each service name to suspend the service.
- Make sure that you have the following account information:
- Your VMware Customer Connect credentials
- If your existing installation includes the Kerberos Auth service or the Virtual App service, you need 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 must have 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
- Double-click the Workspace-ONE-Access-Connector-Installer-22.09.0.0.exe file to run the installer.
The installer detects that an upgrade is needed and guides you through the upgrade process.
- Follow the wizard to upgrade the connector.
- If the Specify Configuration page appears during upgrade, select the new or existing configuration file and specify its password. The default name of the file is es-config.json.
- During the upgrade, the Install Trusted Root Certificates page appears, and you can upload trusted root certificates to the truststore. The connector can establish secure connections to servers and clients whose certificate chain includes any of the certificates uploaded to the truststore. Scenarios where trusted root certificates are required include:
- (On-premises installations only) If your on-premises Workspace ONE Access service instance has a self-signed certificate, you must upload its root, and, if required, intermediate certificate to establish trust between the enterprise services and the Workspace ONE Access service instance.
- (Kerberos Auth service only) If you deploy multiple instances of the Kerberos Auth service behind a load balancer, you must install the load balancer's root CA certificate on the connector instances to establish trust between the connectors and the load balancer.
- (Virtual App service only) If you create virtual apps collections to integrate with VMware Horizon, Horizon Cloud Service on Microsoft Azure with Single-Pod Broker or Horizon Cloud Service on IBM Cloud, and the Horizon servers have self-signed certificates, you must upload the certificate chain to the connector instances on which the Virtual App service is installed to establish trust between the connectors and the Horizon servers. If the Horizon servers have certificates signed by a public CA, you do not need to upload the certificates to the connector truststore. Using certificates signed by a public CA is strongly recommended.
If you upload certificates during upgrade, make sure that you restart the services after the upgrade is complete.
Uploading certificates is an optional step for upgrade. You can also upload certificates after upgrade by running the installer again.
- During the upgrade, the installer installs OpenJDK 11.
- During the upgrade, you can modify any of the settings for existing services. You can also install other services. For example, 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 22.09 for information about requirements, sizing, installation, and settings.
- (Virtual App service only) A new Citrix Configuration page appears during upgrade if you use the custom installation flow. The options on the page apply to Workspace ONE Access integration with a Citrix environment that has multi-site aggregation or keyword filtering configured.
For information, see Configuring Citrix Multi-site Aggregation and Keyword Filtering in Workspace ONE Access in Setting up Resources in Workspace ONE Access and Installing the Workspace ONE Access Connector.
You can configure the options during upgrade, or you can configure them after upgrade by running the connector installer again.
- With the 22.09 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
- 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
Results
The connector upgrade is complete. You can verify that the new version of the connector is installed by navigating to 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 page and verify that the upgraded services are active and their health status is green.
For example:
- If the RSA SecurID (cloud deployment) authentication method was configured in your original installation and you removed it prior to connector upgrade, reconfigure the authentication method after upgrading all the connector instances that have the User Auth service installed.
- 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.
- 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.
- 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.
- 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.
- 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 page.
