Home > Blogs > Horizon Tech Blog

Workspace Portal / vIDM – Trouble Changing the FQDN

Updated 24 November 2017. How to enable later version of Curl.

Please note Workspace Portal is nowadays called VMware Identity Manager (vIDM). This blog post applies as well to vIDM.

Are you getting the error message Error connecting workspace url when trying to change the Workspace Portal Fully Qualified Domain Name (FQDN)?

Error Message

You are not the only one. This blog post explains what is going on behind the scenes and gives you some practical methods for troubleshooting issues when changing the FQDN of Workspace Portal.

First and most important, Workspace Portal is not designed to face the Internet all by itself. You need a reverse proxy/load balancer in front of Workspace. Here is a picture of a typical implementation:

Typical Design

Workspace Portal should be installed using an internal hostname. In order to support external access, in our example we have a virtual server on the load balancer. The virtual server has our external FQDN pointing to it.

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

When you specify a new FQDN, the Workspace Portal virtual machine must verify that it can communicate round-trip through the load balancer all the way back to itself. This looks something like this:

FQDN change traffic flow

And this is where most people run into problems.

If Workspace Portal cannot perform this round-trip communication, it will refuse to change the FQDN and display the error message Error connecting workspace url.

When you look at the Workspace Portal log in


do not be surprised if all you see is a line similar to this:

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

This is not very informative unfortunately…but do not lose faith yet. I will explain how to perform troubleshooting.

The appliance is trying to access https://FQDN/SAAS/jersey/manager/api/health. If it cannot it will refuse to do the change FQDN.

There are a couple of common reasons Workspace Portal fails to change the FQDN.

DNS Records Are Missing

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

I troubleshoot this using nslookup on the Workspace Portal virtual machine. I first run nslookup FQDN, and, if this is successful, I run nslookup ip-address to verify reverse lookup. Here is a screenshot of successfully verified DNS records:


The Firewall Is Blocking the Workspace Portal Virtual Machine from Communicating with the Load Balancer

You must allow port 443 traffic outbound from the Workspace Portal virtual machine to the load balancer’s virtual server.

I troubleshoot this running the command curl on the Workspace Portal virtual machine (more info about curl can be found here: http://curl.haxx.se).

Simply run the command curl –v 3 –ssl https://FQDN. Looking at the result, you should be able to figure out why Workspace Portal cannot access the load balancer.

Note: The default Curl version do not support the fact we disabled TLSv1.0. So you will most likely end up with an error message like this:

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

This is luckily easy to fix. Just run “. /usr/local/horizon/scripts/hzn-bin.inc” in the console. (It is period SPACE /usr/local/horizon/scripts/hzn-bin.inc).

This activates a later version of Curl temporarily and you can continue with the troubleshooting..

In the following screenshot the error message says No route to host. I faked this error by simply pointing the DNS record to a non-existing host. I ran ping FQDN, and you can see that my Workspace Portal virtual machine cannot ping the destination. By using this technique you should be able to spot firewalls blocking the communication.

Error Firewall

You resolve this issue by making sure the Workspace Portal virtual machine is allowed to communicate to the virtual server of your load balancer using the FQDN.

Invalid or Untrusted Certificate on the Load Balancer

This issue is not much harder to troubleshoot than the other ones but because certificates tend to be considered a hard topic, certificates may scare you a little. But I will keep it simple.

Again I am using curl to troubleshoot this issue.

Cert. Error

In the previous screenshot you see that Workspace Portal can access the FQDN but receives an error message doing so. Errors are subjectAltName does not match workspace.pinata.local and SSL peer certificate…was not OK. This is another fabricated error message, but I hope you get the point. I am trying to use FQDN workspace.pinata.local, but my load balancer’s certificate is a wildcard for myhorizondemo.com. So the certificate is not valid. The certificate is technically a valid certificate, but it does not match my FQDN, so Workspace Portal refuses to accept it.

There are a couple of different solutions to this problem. The first and most obvious one is to make sure 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 Portal 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 not-so-well-known CA, you must upload the root CA certificate to the Workspace Portal  keystore. This makes Workspace trust the certificate used on your load balancer.

You upload the root CA certificate using the Configurator page  of Workspace Portal.

Upload ca root

When you upload the certificate, make sure you have the root CA certificate in a Base64 encoded format and you perform the copy and paste operation using a text editor supporting ANSI formatting; that is, never use notepad.exe. I use Notepad++ when working with certificates, but any text editor supporting ANSI works.

Note: You have to upload only the CA’s root certificate if Workspace Portal does not already trust it. Workspace Portal already trusts most public Certificate Authorities. Normally you do not have to upload the Workspace Portal root CA certificate to your load balancer. As long as your load balancer accepts the self-signed certificate used by Workspace Portal, everything works fine.

Workspace Portal often requires the full chain of the certificate to be present on the load balancer. You can check this easily by using SSL Checker from SSLShopper. If your instance is available from the Internet, SSL Checker can validate your certificate.

Here is a picture of a valid certificate with a broken chain:


And here is a picture showing the output when you have a correct chain:


After the Workspace Portal virtual machine trusts the load balancer’s certificate, you should get a curl command output similar to this:

curl successful

If you can successfully use curl to access the FQDN, Workspace Portal will be able to change the FQDN.

You can also try running:

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

You should get something like this:


Note: Changing the FQDN takes about 10 minutes.

Make sure you do not navigate away from the web page or refresh it. After you get the white box showing progress, Workspace Portal has already verified it can do round-trip communication with itself, and the remainder is Workspace inserting the new FQDN everywhere else.

So let us recap a bit. When you change the FQDN of Workspace Portal, it must be possible to establish a session from Workspace Portal via the load balancer and back to itself. This communication is made over port 443 and requires that the FQDN’s certificate be trusted by Workspace Portal.

And that is everything!


3 thoughts on “Workspace Portal / vIDM – Trouble Changing the FQDN

  1. Pingback: Workspace Portal 2.1 HA cluster using internal database | Horizon Tech Blog - VMware Blogs

  2. Pingback: Detailed Change Log – Carl Stalhood

  3. Pingback: VMware Identity Manager Load Balancing – Carl Stalhood

Comments are closed.