Troubleshooting FQDN Updates: VMware Workspace ONE Access Operational Tutorial

Introduction

Many administrators encounter issues when attempting to change the VMware Workspace ONE® Access (formerly VMware Identity Manager) fully qualified domain name (FQDN).

The following error—error connecting workspace URL—is a common one.

This guide explains the Workspace ONE Access workflow at a high-level and provides practical methods to troubleshoot issues when changing the Workspace ONE Access FQDN.

Audience

This guide is intended for experienced IT administrators of existing environments. Knowledge of Workspace ONE Access is assumed.

Workspace ONE Access Overview

Workspace ONE Access is not designed to face the Internet by itself. You should have a reverse proxy or load balancer in front of Workspace ONE Access.

This screenshot depicts a typical example.

You should install Workspace ONE Access using an internal hostname. In this example, a virtual server is installed on the load balancer to support external access and the external FQDN points to this virtual server.

Note: Workspace ONE Access requires an A-record for its FQDN. CNAME is not supported.

When you install Workspace ONE Access, all URLs are internal. You must change the FQDN to use a publicly available URL. When you change the FQDN, all client access is redirected to this public FQDN. Only the Workspace ONE Access admin pages are still accessible using the internal hostname, such as https://workspace.corp.local:8443.

When you specify a new FQDN, the Workspace ONE Access virtual appliance must verify that it can communicate round-trip through the load balancer and back to itself, as shown in the following screenshot.

This is where issues can arise. If Workspace ONE Access cannot perform this round-trip communication, it refuses to change the FQDN. The appliance is attempting to access https://FQDN/SAAS/jersey/manager/api/health. If it cannot access that URL, Workspace ONE Access displays the error message Error connecting workspace url.

Check the Workspace ONE Access log located in

/opt/vmware/horizon/workspace/logs/configurator.log

and you might see a line similar to the following:

2019-10-10 11:05:46,223 ERROR (tomcat-http–44) [;;] com.vmware.horizon.svadmin.service.ApplicationSetupService – Error validating workspace url

The error message is not very informative; however, this guide will explain how to perform some basic troubleshooting steps.

Verifying DNS Records

There are a few common reasons why Workspace ONE Access fails to change the FQDN. The first reason is that DNS records might be missing.

Ensure that you have forward and reverse DNS entries pointing to your load balancer’s virtual server.

You can use nslookup on the Workspace ONE Access virtual appliance. For example, run nslookup FQDN and if this is successful, run nslookup ip-address to verify reverse lookup.

The following screenshot depicts successfully verified DNS records.

Verifying Workspace ONE Access Communication with Load Balancer

The next possible reason for an unsuccessful FQDN update is that communication between Workspace ONE Access and the load balancer is blocked by the firewall. You must allow port 443 traffic outbound from the Workspace ONE Access virtual appliance to the load balancer’s virtual server.

You can troubleshoot this by running the command curl on the Workspace ONE Access virtual appliance. For more information, see the curl documentation.

Run the command curl -v 3 -ssl https://FQDN. The result should help you to determine why Workspace ONE Access cannot access the load balancer.

Note: The default Curl version available on Workspace ONE Access does not support the fact that TLSv1.0 is deactivated in Access. If you get the following error:

curl: (35) error:140770FC:SSL routines:SSL23_GET_SERVER_HELLO:unknown protocol

Run the following command in the console:

. /usr/local/horizon/scripts/hzn-bin.inc

(There is a SPACE after the period; that is, period SPACE /usr/local/horizon/scripts/hzn-bin.inc). The output of this command is shown in the next screenshot.

This command temporarily activates a later version of Curl and you can continue to troubleshoot.

After you log out, the settings revert so that when you next log in, the original curl version is the active one.

In this screenshot, the error message states, No route to host. This is a false error and was created using the next steps.

Point the DNS record to a non-existing host.
Run ping FQDN, and note that the Workspace ONE Access virtual machine cannot ping the destination.

By using this technique, you can spot firewalls blocking the communication.

To resolve this issue, ensure that the Workspace ONE Access virtual machine can communicate with the virtual server of your load balancer using the FQDN.

Verifying Certificates are Trusted on the Load Balancer

Another reason for unsuccessful FQDN updates is that the load balancer has invalid or untrusted certificates.

You can also use the curl command to troubleshoot certificate issues.

In this screenshot, Workspace ONE Access can communicate with the FQDN but still receives an error message.

The errors are subjectAltName does not match workspace.pinata.local

and SSL peer certificate or SSH remote key was not OK.

These errors were generated for illustration purposes. The workflow is as follows:

User attempts to access the FQDN workspace.pinata.local.
However, the load balancer’s certificate is a wildcard for myhorizondemo.com.
Result—the certificate is not valid. The certificate is technically valid but it does not match the FQDN, so Workspace ONE Access refuses to accept it.

There are a couple of solutions to this problem. The first is to make sure that the certificate used by the load balancer’s virtual server is correct. The CN and subjectAltName must match your FQDN.

The next requirement is that Workspace ONE Access must trust the certificate. Your certificate is signed by a Certificate Authority (CA). The root CA certificate must therefore be trusted.

If you are using a self-signed certificate or a certificate signed by a lesser-known CA, you must upload the root CA certificate to the Workspace ONE Access keystore. This forces Workspace ONE Access to trust the certificate used on your load balancer.

Use the Configurator page of Workspace ONE Access to upload the root CA certificate.

When you upload the certificate, make sure that you have the root CA certificate in a Base64 encoded format and perform the copy and paste operation using a text editor that supports ANSI formatting. Do not use notepad.exe because it is a simple text editor, however, you can use Notepad++. Any text editor that supports ANSI works with certificates.

Note: Upload the CA’s root certificate only if Workspace ONE Access does not already trust it. Workspace ONE Access already trusts most public CAs. Usually, you do not have to upload the Workspace ONE Access root CA certificate to your load balancer. If your load balancer accepts the self-signed certificate used by Workspace ONE Access, the workflow should be successful.

Workspace ONE Access often requires the full chain of the certificate to be present on the load balancer. You can verify that the full chain is present by using SSL Checker from SSLShopper. If your instance is available from the Internet, SSL Checker can validate your certificate.

This screenshot depicts a valid certificate with a broken chain.

This screenshot depicts a valid certificate chain.

After you have confirmed that the Workspace ONE Access virtual machine trusts the load balancer’s certificate, the curl command output should be similar to this example:

If you can successfully use curl to access the FQDN, Workspace ONE Access will allow you to change the FQDN.

Another option is to run the following command:

vidm$ curl https://FQDN/SAAS/jersey/manager/api/health

The output is similar to the following example:

{“allOk”:true,”_links”:{“hw-health-messaging”:{“href”:”/SAAS/jersey/manager/api/messaging/health”},”hw-health-calculators”:{“href”:”/SAAS/API/1.0/REST/system/health/calculators”},”hw-health-appmanager”:{“href”:”/SAAS/API/1.0/REST/system/health”},”self”:{“href”:”/SAAS/jersey/manager/api/health”},”hw-health-analytics”:{“href”:”/AUDIT/API/1.0/REST/system/health”}}}

Note: Changing the FQDN takes about 10 minutes.

Do not navigate away from the web page or refresh it. When you can see the white box showing progress, Workspace ONE Access has already verified that it can perform the round-trip communication with itself. For the remaining time, Workspace ONE Access is inserting the new FQDN in other locations.

Conclusion

Before you can change the FQDN of Workspace ONE Access, it must be possible to establish a session from Workspace ONE Access to the load balancer and back to itself. This communication is made over port 443 and requires that the FQDN’s certificate is trusted by Workspace ONE Access.

For more information, see the Workspace ONE Access Activity Path. Activity paths provide step-by-step guidance to help you level-up in your product knowledge. You will find everything from beginner to advanced curated assets in the form of articles, videos, and labs.

About the Author

This guide was written by:

Peter Bjork, Principal Architect, End-User-Computing Technical Marketing, VMware.

To comment on this paper, contact VMware End-User-Computing Technical Marketing at euc_tech_content_feedback@vmware.com.