To install the Directory Sync, User Auth, Kerberos Auth, or Virtual App services, run the Workspace ONE Access connector installer on a Windows server that meets all the requirements and select the services you want to install.

You can choose between a quick, default installation that uses default values for most settings or a custom installation that lets you configure various settings.

Default Installation Custom Installation
Uses the following default ports:
  • User Auth Service: 8090
  • Directory Sync Service: 8080
  • Kerberos Auth Service: 443
  • Virtual App Service: 8008
Note: The services run on these ports. Only the Kerberos Auth service port requires inbound connectivity.
Lets you specify custom ports for the services
Note: The services run on these ports. Only the Kerberos Auth service port requires inbound connectivity.
Auto-generates a self-signed certificate for the connector Lets you install a trusted SSL certificate for the connector (required for Kerberos Auth service)
Lets you upload trusted root certificates to the truststore. Scenarios for uploading certificates to the truststore 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 Connection servers.
Lets you configure a proxy server
Lets you configure a syslog server
Lets you select options related to multi-site aggregation and keyword filtering for Citrix virtual apps collections

Regardless of the type of installation you choose, you can run the installer again later and modify all the settings.

During the installation, OpenJDK 11 is also installed on the server.

Prerequisites

  • See Prerequisites for Installing the Workspace ONE Access Connector.
  • As part of the installation process, you download files from the Workspace ONE Access console. You might need to use a browser other than Internet Explorer to download the files. Default Internet Explorer settings might prevent you from downloading the files.

Procedure

  1. Download the Workspace ONE Access connector installer and a configuration file 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. Select Integrations > Connectors.
    3. Click New.
    4. If the Connector Usage Confirmation dialog box appears, review the information, then select Latest Workspace ONE Access Connector.
      Note: The Connector Usage Confirmation dialog box appears the first time you install a new connector in the Workspace ONE Access service.

      (Workspace ONE Access on premises only) If you want to change your selection later, you can use the Reset Connector Selection option that appears subsequently on the Connectors or Legacy Connectors page. See Resetting Connector Selection in Workspace ONE Access for more information.

      The Add New Connector wizard appears.

    5. In the Add New Connector wizard Download Installer page, click GO TO MYVMWARE.COM.
      The VMware Customer Connect web page appears in a new window. Keep the wizard open as you will return to it after downloading the installer.
    6. Log in to VMware Customer Connect and download the Workspace-ONE-Access-Connector-Installer-22.09.exe file from the Workspace ONE Access Connector Download page.
    7. Return to the Workspace ONE Access console and click Next in the Download Installer page of the Add New Connector wizard.
    8. Generate the configuration file by creating a password and clicking Download Configuration File.
      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.
      Important:
      • 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.

      • Make a note of the password. You must enter the password and the path to the configuration file when you run the connector installer.

        The configuration file and its password are also required for future connector upgrades. Save the password in a secure manner for future use. If you do not have the password when you upgrade the connector, you can generate a new configuration file.

      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.
    9. After downloading the configuration file, click Next in the wizard.
  2. Copy the installer and configuration files to the Windows server on which you want to install the services.
  3. Double-click the installer file to run the Workspace ONE Access connector installation wizard.
    The installer verifies prerequisites on the server. If .NET Framework is not installed or does not match the required version, you are prompted to install it and to restart the server. After the .NET Framework installation is complete, run the installer again to resume the installation process.
    Caution: Do not restart the system if you are installing the connector on a 19.03.x connector server as part of connector migration. If you do so, your 19.03.x connector will become unusable. Restart the system only after the entire connector migration process is complete.
  4. On the Welcome page, click Next.
    ""
  5. Read and accept the license agreement, then click Next.
    The "I accept the terms in the license agreement" option is selected.
  6. Select the services you want to install.
    All services are selected.
    By default, the services are installed in C:\Program Files. To change the installation folder, click Change and select the folder.
  7. Click Next.
  8. On the Specify Configuration File page, perform the following actions.
    1. Select the configuration file that you downloaded from the Workspace ONE Access console.
      If the configuration file is in the same folder as the installer and has the default name es-config.json, it appears in the text box automatically.
    2. Enter the password that you set for the configuration file while generating it.
    3. If you want to install the connector in FIPS mode, select the Enable FIPS check box.
      FIPS refers to the Federal Information Processing Standard, which specifies security requirements for cryptographic modules. Before selecting this option, see Workspace ONE Access Connector and FIPS Mode (Workspace ONE Access FedRAMP Only) for requirements for the FIPS mode.
      Caution:
      • Workspace ONE Access connector in FIPS mode is supported with Workspace ONE Access FedRAMP tenants only. Other types of tenants and on-premises Workspace ONE Access installations do not support the connector in FIPS mode.
      • Do not select the Enable FIPS option if you are migrating from legacy 19.03.x or earlier connectors to the 22.09 connector. FIPS mode is not supported in a migration scenario.
      • After installation, you cannot change from FIPS mode to non-FIPS mode or from non-FIPS mode to FIPS mode. Make your decision accordingly.

    The Enable FIPS option is selected.
  9. Select between Default and Custom installation.
    The Default option is selected.
  10. If you selected Default installation, follow these steps.
    1. (Kerberos Auth service and Virtual App service only) On the Specify Service Account page, specify the user name and password of the domain user account to use to run the Kerberos Auth service and the Virtual App service.

      Enter the User name in the format DOMAIN\Username, such as EXAMPLE\administrator. Alternatively, click Browse and select the domain and user.

      If you are unable to locate domains or users when you click Browse, type them in the text box in the format required format.

      Important: The Kerberos Auth service only supports the following special characters in the domain user account password:

      ! ( & % @ / = ? * , .

      If the password contains any other special characters, Kerberos Auth service installation fails.

      Important: In Workspace ONE Access connector 22.09.1.0, the Virtual App service does not support the # character in the domain user account password.
      ""
      Note: The Specify Service Account page appears only if you are installing the Kerberos Auth service or Virtual App service.
    2. Click Next.
    3. In the Ready to Install the Program page, review your selections, then click Install.
      The services are listed, along with the ports. Proxy and syslog servers are not configured. The SSL certificate is self-signed.
      The installation takes a few minutes.
      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 connector on a 19.03.x connector server as part of connector migration. Restart the system only after the entire connector migration process is complete.
  11. If you selected Custom installation, follow these steps.
    1. In the Specify Proxy Server Information page, enter a proxy server, if required.
      The enterprise services access Web services on the Internet. If your network configuration provides Internet access through an HTTP proxy, you must enter a proxy server. See Workspace ONE Access Connector 22.09 Systems Requirements for information about supported proxies.

      You can also specify a list of non-proxy hosts, hosts that should be reached directly without going through the proxy server.

      1. Select the Enable Proxy check box.
      2. Enter the host name, specified as a fully qualified domain name (FQDN), or IP address of the proxy server.
      3. Enter the proxy server port.
      4. If you want to specify any non-proxy hosts, hosts that should be reached directly without going through the proxy server, enter the FQDN or IP address in the Non Proxy Hosts text box. Use the following format, with each entry separated by |:

        host1|host2

      5. If the proxy server requires authentication, select Basic and enter the user name and password for the proxy server.
      The Enable Proxy option is selected.
    2. Click Next.
    3. On the Specify Syslog Server page, if you want to use one or more external syslog servers to store application-level event messages, select the Enable Syslog option and enter each syslog server's IP address or FQDN, and port.

      To specify a single syslog server, use the following format:

      host:port

      To specify multiple syslog servers, 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:54

      or

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

      The Enable Syslog option is selected.
      Note: Only application-level events are exported to syslog servers. Operating system events are not exported.
    4. Click Next.
    5. (Virtual App service only) On the Citrix Configuration page, if you plan to integrate Workspace ONE Access with a Citrix environment that has multi-site aggregation or keyword filtering configured, select the options that apply to your scenario.
      None of the Citrix configuration options are selected.
      • Enable Citrix StoreFront restricted PowerShell session

        Select this option only if your Citrix environment restricts the PowerShell commands that can be executed on StoreFront remotely. If you select this option, you must also create a PowerShell session configuration file on StoreFront to allow the Virtual App service to run the limited commands required for multi-site aggregation and keyword filtering. In the Configuration Name text box, enter the configuration name you specified while creating the session configuration file, without the extension. Only alpha-numeric characters are allowed in the name.

      • Enable Citrix keyword filtering

        Select this option if keyword filtering is enabled on StoreFront.

        For Workspace ONE Access to support keyword filtering, either your Citrix environment must not have any restrictions on the PowerShell commands that can be executed on StoreFront remotely, or you must select the Enable Citrix StoreFront restricted PowerShell session option and set up a PowerShell session configuration file to allow the Virtual App service to run limited commands.

      • Disable Citrix auto-loading of StoreFront modules

        The Virtual App service loads certain modules in StoreFront to support keyword filtering. If you do not want the Virtual App service to load the modules, select this option. The required commands will then be executed through the restricted PowerShell session configuration setup.

      See Configuring Citrix Multi-site Aggregation and Keyword Filtering in Workspace ONE Access in Setting up Resources in Workspace ONE Access for more information.

    6. On the Install Trusted Root Certificates page, upload root or intermediate CA certificates to the truststore, if required.
      Caution: Make sure that the certificate paths do not contain double-byte characters, which are used in some languages. If the path contains double-byte characters, upgrade might succeed but the certificates will not be uploaded correctly.
      The connector will be able to establish secure connections to servers and clients whose certificate chain includes any of the certificates in the truststore. Scenarios for uploading certificates to the truststore include:
      • (On-premises installations only) If your on-premises Workspace ONE Access service instance has a self-signed certificate that you installed, 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 Connection 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.

      You can also upload trusted root certificates later, after installation.

      ""
    7. Click Next.
    8. Review the default ports that the enterprise services run on, and specify different ports if these ports are being used by other applications.

      The Kerberos Auth service port requires inbound connectivity. The User Auth, Directory Sync, and Virtual App service ports do not require inbound connectivity.

      Example ports are 8080 for Directory Sync, 8090 for User Auth, 443 for Kerberos Auth, and 8008 for the Virtual App service.
    9. (Kerberos Auth service only) On the SSL Certificate for Kerberos Auth Service page, select the certificate to use for the connector server.
      A trusted SSL certificate signed by a public or internal CA is required for the Kerberos Auth service. If you do not upload a trusted SSL certificate during installation, a self-signed certificate is auto-generated. You can upload a trusted SSL certificate later.
      • To upload a trusted SSL certificate, select the Would you like to use your own SSL certificate? check box, click Browse, and select the certificate file.

        The certificate file must be in PEM or PFX format. If you upload a PEM file, also upload the private key. If you upload a PFX file, also specify the certificate password. For information about certificate requirements, see Uploading an SSL Certificate for the Kerberos Auth Service.

      • To use the auto-generated, self-signed certificate, deselect the Would you like to use your own SSL certificate? check box.
        Note: If you use the Workspace ONE Access generated self-signed certificate, you will need to add the root certificate generated by Workspace ONE Access to clients' truststores. You can get the root certificate, root_ca.per, from INSTALLDIR\Workspace ONE Access\Kerberos Auth Service\conf after installation.

        While you can use the self-signed certificate for testing purposes, trusted SSL certificates signed by a public or internal CA are recommended for production usage.

      The "Would you like to use your own SSL certificate?" option is selected.
    10. Click Next.
    11. (Kerberos Auth service and Virtual App service only) On the Specify Service Account page, specify the user name and password of the domain user account to use to run the Kerberos Auth service and Virtual App service.
      Important: The Kerberos Auth service only supports the following special characters in the domain user account password:

      ! ( & % @ / = ? * , .

      If the password contains any other special characters, Kerberos Auth service installation fails.

      Important: In Workspace ONE Access connector 22.09.1.0, the Virtual App service does not support the # character in the domain user account password.

      Enter the User name in the format DOMAIN\Username, such as EXAMPLE\administrator. Alternatively, click Browse and select the domain and user.

      ""
      Note: If you are unable to locate domains or users when you click Browse, type them in the text box in the format specified above.
      Note: The Specify Service Account page appears only if you are installing the Kerberos Auth service or the Virtual App service.
    12. In the Ready to Install the Program page, review your selections, then click Install.
      The installation takes a few minutes.
      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 connector on a 19.03.x connector server as part of connector migration. Restart the system only after the entire connector migration process is complete.
  12. After installation finishes successfully, verify that the services are running on the Windows server.
    Service names:
    • VMware Directory Sync Service
    • VMware User Auth Service
    • VMware Kerberos Auth Service
    • VMware Virtual App Service
  13. Go to the Workspace ONE Access console and refresh the Connectors page to verify that the new services appear and are in Active state.
    If the installation fails, delete both the installer and the configuration file that you downloaded from the Workspace ONE Access console, then start the installation process again.

Results

After successful installation, the enterprise services that you installed are registered with the Workspace ONE Access tenant and appear on the Connectors page in the Workspace ONE Access console.

For example:


The Connectors page lists the connector and all the installed services. The status is Active, the health is green, and the version is 22.09.

What to do next

  • In the Workspace ONE Access console, configure the enterprise services you installed. For information about integrating directories using the Directory Sync service, see Directory Integration with VMware Workspace ONE Access. For information about configuring authentication using the User Auth or Kerberos Auth service, see Managing User Authentication Methods in VMware Workspace ONE Access. For information about integrating Horizon, Horizon Cloud Service on Microsoft Azure with Single-Pod Broker or Horizon Cloud Service on IBM Cloud, Citrix, or ThinApp virtual apps using the Virtual App service, see Setting up Resources in VMware Workspace ONE Access.
  • (Kerberos Auth service only) If you are using the Workspace ONE Access generated self-signed certificate for the Kerberos Auth service, you need to add the root certificate generated by Workspace ONE Access to clients' truststores. You can get the root certificate, root_ca.per, from INSTALLDIR\Workspace ONE Access\Kerberos Auth Service\conf.

    While you can use the self-signed certificate for testing purposes, trusted SSL certificates signed by a public or internal CA are recommended for production usage. See Uploading an SSL Certificate for the Kerberos Auth Service.