Install Omnissa Horizon Connection Server Certificate

原文：Install Omnissa Horizon Connection Server Certificate — theDXT (Daniel Keer)

Installing an SSL/TLS certificate on the Omnissa Horizon Connection Server (formerly the VMware Horizon Connection Server) is a common task. The whole process may feel daunting if you’ve never installed a certificate on the Horizon Connection Server.

Omnissa Horizon has had a few names, and some of those old names are still present at its core. Most recently it was called VMware Horizon. The original name of Horizon was VMware VDM (Virtual Desktop Manager), later renamed VMware Horizon View, and today, it is called Horizon or Omnissa Horizon.

In this post, I will show you step-by-step how to install a certificate on the Horizon Connection Server and update the VMware Unified Access Gateway appliance to reflect the changes.

Prerequisites

• Install the PFX certificate on the VMware Horizon Connection Server if you need to learn how my post Install PFX Certificate in Windows details all the steps.

The Process

The process is broken up into two sections. The first section details the steps needed on the Omnissa Horizon Connection Server, and the second section details the steps needed on the Omnissa Unified Access Gateway appliance.

Omnissa Horizon Connection Server

• Connect to your Horizon Connection Server
• OpenMMC.
• Add theCertificatesSnap-in.

• SelectComputer accountand clickNext.

• SelectLocal computerand clickFinish.

• ClickOKto close the Add or Remove Snap-ins window.

• Expand outCertificates (Local Computer) > Personal > Certificates.

• You will see that one of the certificates has the friendly name vdm.

We need to change the old certificate’s name from vdm to something else. The VMware Horizon Connection Server is looking for the certificate with the friendly name vdm. It won’t work if there are none or if there are two of them named vdm.

• Right-click on the certificate currently named VDM and click on Properties.

• Change the Friendly name to something other than VDM. I will use the name original cert.
• Click Apply,then click OK.

• Right-click on the new certificate and click on Properties.

• Change the Friendly name to vdm.
• Click Apply,then click OK.

• Open Services.

• Restart the VMware Horizon View Connection Server service.

• The new certificate will be active once the VMware Horizon Connection Server service has finished restarting.

If you run into the ERR_SSL_VERSION_OR_CIPHER_MISMATCH error, double-check everything. This error can show up if you have more than one friendly name of vdm, or exporting the private key wasn’t enabled when the PFX was installed, or the CSR was created using (No template) CNG key.

Omnissa Unified Access Gateway

Before we make any changes to the UAG, we need to collect the certificate thumbprint.

• Go to the URL of your Omnissa Horizon Connection Server in a web browser.
• Click on the lock iconto View site information.

• Click on Connection is secure.

• Click on the certificate icon to show the certificate.

• Under SHA-256 Fingerprints, copy the value for the certificate. We will need this on the UAG.

• Login to the UAG.

• Select Configure Manually

• Toggle the option to show Edge Services Settings.

• Click on Horizon Settings.

• For the Connection Server URL Thumbprint, enter sha256= then enter the fingerprint we copied earlier.
• Click Save.

That’s all it takes to install a certificate on the Omnissa Horizon Connection Server and to update the Omnissa Unified Access Gateway appliance with the updated certificate thumbprint.

Why the friendly name matters more than the certificate

Horizon's core services are still built on the original VMware View code, and one legacy detail has survived every rebranding: the Connection Server finds its server certificate by friendly name, and the name it wants is vdm. If two certificates in the machine store carry that name, or if none does, the service either binds TLS with the wrong certificate or fails to bind it at all — which is why a perfectly valid certificate can still produce ERR_SSL_VERSION_OR_CIPHER_MISMATCH in a browser.

The rules are easy to remember once you have been bitten by them:

• Exactly one certificate in Certificates (Local Computer) > Personal > Certificates may be named vdm.
• Rename the old certificate first, then name the new one. Doing it in the other order temporarily creates two certificates with the same friendly name.
• The certificate must have a private key attached and usable by the local service account. A certificate imported without its key shows up in the store and does nothing.
• Friendly names are not part of the certificate — they live in the Windows store, so they must be set on every Connection Server in the pod, not just the one you exported from.

Certificate requirements to plan for

• Subject alternative names. The SAN list must include the FQDN users type in the browser or the Horizon client URL, and any additional name used by a load balancer or a pair of Connection Servers behind one virtual name. A CN-only certificate is rejected by modern browsers.
• Key type and size. RSA 2048 or 3072, or ECDSA if all your clients support it. Keys created from a "No template" CNG template are a known source of failure here — issue from the normal Web Server template instead.
• Trust chain. Install the issuing CA's intermediates in Intermediate Certification Authorities so clients can build a complete chain. If an intermediate is missing, the server looks fine locally and every external client complains.
• Validity period. The certificate has to outlive your next maintenance window. A certificate that expires during an upgrade freeze is the classic way to lose a weekend.
• One name per certificate where possible. Wildcards work but they widen what a stolen key is worth, and they cannot span an internal domain and an external one.

Choosing between an internal and a public certificate

If every client is managed and you distribute your root CA through policy, an internal certificate is cheap, renewable and completely adequate: the Horizon client validates the name and the chain and the users never see a warning. The moment unmanaged devices, HTML Access from arbitrary browsers or BYOD clients are in scope, you want a certificate from a CA those clients already trust. That decision also affects the Unified Access Gateway: the UAG validates the Connection Server by thumbprint rather than by chain, so a private CA is workable there, but the certificate the UAG presents to clients should come from a public CA in any deployment with unmanaged endpoints. Exporting the certificate you end up with is covered in Exporting a certificate with MMC.

Verifying what the Connection Server is actually serving

Before restarting services, confirm which certificate Windows will use and that it is complete.

# PowerShell: list the personal store with friendly names
Get-ChildItem Cert:\LocalMachine\My |
  Select-Object Subject, FriendlyName, Thumbprint, NotAfter

# Which certificate will the Connection Server pick?
Get-ChildItem Cert:\LocalMachine\My | Where-Object FriendlyName -eq 'vdm' |
  Format-List Subject, Thumbprint, HasPrivateKey, NotAfter

# Thumbprint ready to paste into the UAG (lower case, no colons)
(Get-ChildItem Cert:\LocalMachine\My | Where-Object FriendlyName -eq 'vdm').Thumbprint

# Certificate store and chain verification from the command line
certutil -store My
certutil -verify -urlfetch C:\temp\horizon.cer

# What the server actually presents, from a Linux or macOS client
echo | openssl s_client -connect horizon.example.com:443 \
  -servername horizon.example.com 2>/dev/null |
  openssl x509 -noout -subject -dates -ext subjectAltName

PowerShell prints the thumbprint in upper case without separators; the UAG wants lower case, prefixed with sha256=. Copy it from the same output you verified rather than from a spreadsheet. If chain building is the part that fails, the certificate chain verification walkthrough is the fastest way to find the missing intermediate.

Updating every gateway after a certificate change

A certificate change on the Connection Server is never a local change. The UAG stores the Connection Server's SHA-256 thumbprint and refuses to broker through a server whose certificate does not match, so every gateway in the pod has to be updated in the same window:

1. Copy the new SHA-256 fingerprint from the certificate that is now active.
2. Log in to the UAG (port 9443) and open Edge Service Settings > Horizon Settings.
3. Replace the value in Connection Server URL Thumbprint with sha256=<hex> and save.
4. Refresh the edge service status until Blast and Tunnel are green again, and confirm in the Horizon console under Settings > Servers > Gateways that the gateway is reporting.
5. Repeat for every UAG, then test an external launch. A single forgotten gateway produces failures for exactly the users that land on it.

The full sequence for the gateway side is in Configure Omnissa UAG with Omnissa Horizon.

TLS hardening while you are in there

Replacing a certificate is a good moment to remove protocol versions nobody should be using. Horizon honours TLS behaviour configured in the locked.properties file on the Connection Server, which is the supported, upgrade-safe way to restrict protocols — see Configure locked.properties for Omnissa Horizon for the file's other keys and where it lives.

# locked.properties on the Connection Server - restrict accepted protocols
validProtocols=TLSv1.2,TLSv1.3

# Windows-level control of protocol versions (Schannel), applied per server
HKLM\SYSTEM\CurrentControlSet\Control\SecurityProviders\SCHANNEL\Protocols
  \TLS 1.0\Server   DisabledByDefault = 1, Enabled = 0
  \TLS 1.1\Server   DisabledByDefault = 1, Enabled = 0

Test with an actual client, not with a browser alone: older Horizon clients and thin clients sometimes need a nudge before they negotiate TLS 1.2 correctly.

Renewal checklist for a Horizon pod

1. Issue the new certificate with the same SAN list, from a supported template, with an exportable private key.
2. Install the PFX on every Connection Server in the pod — the process is described in the prerequisites above.
3. Rename the old certificate away from vdm, then rename the new one to vdm, and confirm there is exactly one.
4. Restart the VMware Horizon Connection Server service and verify what the server presents with openssl s_client, not just with MMC.
5. Update the thumbprint on every Unified Access Gateway and confirm the edge service status.
6. Update the load balancer if it terminates TLS in front of the pod, and re-import the certificate there as well.
7. Test both paths end to end: HTML Access over a browser connection and a native Horizon client launch from outside the network.
8. Record the new thumbprint, expiry date and SAN list in your runbook, and add an expiry alert at 60 days so the next renewal is routine rather than an incident.

Troubleshooting TLS errors

• ERR_SSL_VERSION_OR_CIPHER_MISMATCH. Two certificates named vdm, no certificate named vdm, a missing private key, or a key created from a "no template" CNG CSR. Fix the store first; the error is almost never about the cipher list.
• "Your connection is not private" from external clients only. A missing intermediate certificate or a name that is not in the SAN list. Check the chain before you check anything else.
• Internal clients fine, external clients fail after a certificate change. The UAG thumbprint has not been updated, or only some gateways were updated.
• The server still presents the old certificate. The friendly name was not renamed, or the Connection Server service was not restarted.
• Certificate warnings only from a browser. The browser is reaching a different device — a load balancer or NAT rule serving its own self-signed certificate. Check the DNS answer and the certificate you actually receive.
• Intermittent TLS failures. Clock skew between the Connection Server and the client, or between the Connection Server and the UAG. Certificates have validity windows for a reason.

If you want to read more about TLS certificates on the Omnissa Horizon Connection Server, here is the Omnissa documentation.