VMware Workspace ONE Access: Troubleshooting FQDN Updates › sites › default › files › Trouble… · Troubleshooting FQDN Updates: VMware Workspace ONE Access Operational Tutorial

WHITE PAPER–FEBRUARY 2020

Troubleshooting FQDN Updates: VMware Workspace ONE Access Operational Tutorial

VMware Workspace ONE Access

2

TROUBLESHOOTING FQDN UPDATES: VMWARE WORKSPACE ONE ACCESS OPERATIONAL TUTORIAL

Table of Contents Introduction ........................................................................................................................................................................................ 3

Audience ......................................................................................................................................................................................... 3

Workspace ONE Access Overview .................................................................................................................................................. 4

Verifying DNS Records ........................................................................................................................................................................ 6

Verifying Workspace ONE Access Communication with Load Balancer ............................................................................................. 7

Verifying Certificates are Trusted on the Load Balancer .................................................................................................................... 9

Conclusion ......................................................................................................................................................................................... 15

About the Author.......................................................................................................................................................................... 15

3


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.

https://www.vmware.com/content/vmware/vmware-published-sites/us/products/workspace-one/access.html.html

4


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.

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.

5


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.

6


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.

7


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 disabled 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.

https://curl.haxx.se/

8


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

1. Point the DNS record to a non-existing host.

2. 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.

9


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

10


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.

https://www.sslshopper.com/ssl-checker.html

11


This screenshot depicts a valid certificate with a broken chain.

12


This screenshot depicts a valid certificate chain.

13


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

14


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/m

anager/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.

15


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

[email protected].

https://techzone.vmware.com/mastering-workspace-one-access

https://techzone.vmware.com/users/peter-bjork

mailto:[email protected]

VMware, Inc. 3401 Hillview Avenue Palo Alto CA 94304 USA Tel 877-486-9273 Fax 650-427-5001 www.vmware.com. Copyright © 2019 VMware, Inc. All rights reserved. This product is protected by U.S. and international copyright and intellectual property laws. VMware products are covered by one or more patents listed at http://www.vmware.com/go/patents. VMware is a registered trademark or trademark of VMware, Inc. and its subsidiaries in the United States and other jurisdictions. All other marks and names mentioned herein may be trademarks of their respective companies. Item No: vmw-wp-temp-word 2/19

Documents

VMware Workspace ONE Access: Troubleshooting FQDN Updates › sites › default › files › Trouble… · Troubleshooting FQDN Updates: VMware Workspace ONE Access Operational Tutorial