6.5.27 VMware Horizon (Omnissa)

Set the vdm certificate on each Connection Server and upload the Internet certificate to each UAG

VMware Horizon, now Omnissa Horizon, has two templates. Use one or both, depending on where your clients connect.

Template Runs on What it changes
Omnissa Horizon Connection Server (formerly VMware Horizon) The CertKit Agent on each Connection Server The certificate named vdm in the local computer’s Personal store, then restarts the Connection Server service
Omnissa Unified Access Gateway (formerly VMware UAG) A Windows agent that can reach the UAG management port The UAG Internet interface certificate, through the UAG REST API

Both templates are in beta. They use the PFX format and need an RSA certificate with a key of at least 2048 bits and the Server Authentication EKU. FIPS mode is not supported on either.

Requirements for both templates

  • Windows PowerShell 5.1 and .NET Framework 4.7.2 or later on the agent host. No extra PowerShell modules are needed.
  • The certificate’s root CA must already be trusted in the local computer store on the agent host. The templates don’t install roots from the PFX.
  • Keep the PFX format the template selects. It must hold exactly one certificate with a private key, plus every intermediate in the chain.
  • Keep the CA’s CRL and OCSP addresses reachable from servers and clients. The templates don’t check revocation.

Connection Server

Prerequisites

  • Install the CertKit Agent on each Connection Server. It must run with administrator rights. The agent service normally runs as Local System.
  • The Connection Server service (wsbroker) must be installed, running, and running as Local System. A custom service account is not supported.
  • Exactly one certificate in Certificates (Local Computer) > Personal > Certificates has the friendly name vdm, and it has a private key. Horizon’s default self-signed certificate counts.
  • No certificate in that store has the friendly name vdm.ec. The template supports the RSA vdm setup only.
  • The Connection Server must already be serving the current vdm certificate on port 443.

Variables

Connection Server certificate DNS name is a name the certificate covers that clients or UAGs use for this server, for example connection01.example.com. The template checks that the certificate covers it, then connects to 127.0.0.1:443 with that name to confirm what Horizon serves. Spaces at either end are removed. Use a different name on each server’s deployment if each server has its own name.

What happens on each run

  1. Checks the server, the service account, FIPS mode, and the certificate. If the listener already serves the new certificate, it stops here and reports success.
  2. Imports the new certificate into the local computer’s Personal store. The private key is converted in memory to an exportable machine key in the Microsoft RSA SChannel Cryptographic Provider with KeySpec 1, the setup Omnissa’s Horizon CSR example uses. The template then tests that the key can be exported, which the Horizon gateways need. Intermediates go into the Intermediate Certification Authorities store.
  3. Records which Horizon services are running.
  4. Renames the old certificate to CertKit previous vdm <thumbprint> and gives the new certificate the vdm name.
  5. Restarts the Connection Server service. Like the Services console, it stops the services that depend on it first and starts them again afterward.
  6. Waits for every Horizon service that was running in step 3 to run again, then waits for port 443 to serve the new, trusted certificate.

Each service stop, start, and check can take up to five minutes. Each wait ends as soon as its check passes.

Restart and disruption

The restart takes this Connection Server out of service until Horizon is back up. Drain it from your load balancer first, deploy to one Connection Server at a time, and check client connections and the load balancer address before you return it to service.

Rollback

If anything fails after step 4, the template puts the vdm name back on the old certificate, restarts the service the same way, and waits for the old certificate to be served and the Horizon services to run. The deployment still reports as failed.

The template never deletes certificates. Old certificates stay in the store under their renamed friendly name. If an import fails before step 4, the new certificate and intermediates can stay in the store unused. Remove them by hand when you’re sure you don’t need them.

UAG and load balancer thumbprint pins

The Connection Server template can’t see or change remote pins. If a UAG’s Horizon Settings list a Connection Server URL Thumbprint, renewing the Connection Server breaks that UAG’s connection to it. Update the thumbprint as part of the renewal, or remove it when the Connection Server certificate comes from a CA the UAG trusts. Check load balancers that pin backend certificates the same way.

The template doesn’t change Horizon’s internal pairing or True SSO certificates.

Unified Access Gateway

Prerequisites

  • Install the CertKit Agent on a Windows host that can reach the UAG management address over HTTPS (port 9443 by default) and the Internet interface on port 443. Requests go straight to the UAG and don’t use a system proxy.
  • An enabled UAG admin account with the ROLE_ADMIN role that can sign in with a password. A monitoring account can’t deploy. If you set up SAML sign-in for the admin UI and it turns off password sign-in, the template can’t sign in.
  • SAML encryption certificate rollover must be off. The template stops when it is on, because the IdP metadata may need updating.
  • The template uses the UAG REST API that Omnissa documents for UAG 2503 and later.

Variables

Variable What to enter
UAG management host and port One appliance’s management hostname or IP, for example uag01.example.com:9443. The port defaults to 9443. Don’t add a path.
UAG administrator username The admin account name. It can’t contain a colon.
UAG administrator password That account’s password.
UAG Internet-interface IP or hostname The same appliance’s Internet-facing IP or hostname. Don’t use a load balancer address or VIP, because the check could reach a different appliance.
UAG authentication mode Jwt by default, in Advanced view. Use Basic only for older releases if JWT doesn’t work.

Add the template once for each UAG.

What happens on each run

  1. Checks the PFX and confirms the chain is trusted on the agent host.
  2. Signs in and confirms the account is an enabled ROLE_ADMIN user.
  3. Reads the appliance settings and stops if FIPS mode or SAML encryption certificate rollover is on.
  4. Connects to the Internet interface on port 443. If it already serves this certificate, the template stops and reports success.
  5. Uploads the PFX to the Internet interface with PUT /rest/v1/config/certs/ssl/pfx/end_user.
  6. Checks the Internet interface every five seconds, for up to two minutes, until it serves the new certificate with a trusted chain. Hostname mismatches are ignored in this check.

The template doesn’t change the admin interface certificate. It doesn’t check the management interface certificate either, so a self-signed one is fine.

Restart and disruption

Drain the appliance before deploying, and deploy to one UAG at a time.

No automatic rollback

If the upload times out, the result is unclear. The template doesn’t retry and reports the previous thumbprint. If the upload works but the check fails, the template reports failure and leaves the appliance as it is. Keep the previous PFX and its password so you can upload it again by hand in the admin UI under Advanced Settings > TLS Server Certificate Settings.

Common problems

Connection Server

  • “Run elevated as a local administrator”: the agent isn’t running with administrator rights.
  • “The Horizon Connection Server service (wsbroker) is not installed on this computer”: the agent is on the wrong server. Install it on each Connection Server.
  • “wsbroker uses a custom service account”: the template supports Local System only.
  • “wsbroker must be running before certificate deployment”: start the Connection Server service and deploy again.
  • “This initial template has not been validated for FIPS Connection Servers”: FIPS mode is on. The template doesn’t support it.
  • “The certificate DNS names do not cover …”: Connection Server certificate DNS name isn’t on the certificate. Fix the name, or add it to the certificate.
  • “Candidate chain is not trusted”: install the root CA in the local computer’s Trusted Root Certification Authorities store.
  • “The PFX does not include every intermediate in the validated chain”: keep the PFX format the template selects so the chain is included.
  • “Expected exactly one current vdm certificate; found N”: clear the vdm friendly name from every certificate but the one Horizon serves now, or set it on that one if none has it.
  • “A vdm.ec certificate exists in LocalMachine\My”: the server uses an ECDSA vdm.ec certificate. The template supports RSA vdm only.
  • “Current vdm certificate has no private key; rollback would not be possible”: reinstall the current certificate with its key before deploying.
  • “The local HTTPS listener is not using the current vdm certificate”: Horizon isn’t serving the certificate named vdm. Often the name changed without a restart. Restart the Connection Server service, confirm port 443 serves the vdm certificate, then deploy again.
  • “The imported Horizon key must be an exportable RSA SChannel machine key”: Windows couldn’t store the key the way Horizon needs it. The new certificate wasn’t activated, and Horizon still serves the old one. Send the full message to CertKit support.
  • “Horizon services not running within 300 seconds”: the message names each service and its state. A Blast Secure Gateway left Paused usually means it can’t read the private key. Check its log for keystoreutil.exe and NCryptExportKey. The template rolls back to the old certificate.
  • “The local HTTPS listener did not serve the expected trusted certificate within 300 seconds”: the message shows the expected and received thumbprints and any TLS error. A different thumbprint means Horizon didn’t load the new certificate. A matching thumbprint with an error means a trust or DNS name problem.
  • “ROLLBACK FAILED”: set the vdm friendly name back on the thumbprint in the message and restart the Connection Server service by hand.

UAG

  • “uagHost must be an HTTPS hostname/IP with optional port”: remove any path or user@ from UAG management host and port.
  • “UAG … returned HTTP 401” or “HTTP 403”: check the password, the account’s role, whether SAML admin sign-in has turned off password sign-in, and whether UAG authentication mode fits the UAG version.
  • “UAG POST /rest/v1/jwt/login returned HTTP 404” or “UAG login did not return access_token”: JWT sign-in isn’t available on this release. Set UAG authentication mode to Basic.
  • “UAG GET /rest/v1/config/adminusers/… returned HTTP 404”: the UAG doesn’t have the admin user API the template uses to check the account’s role. The template stops rather than guess.
  • “An enabled UAG ROLE_ADMIN account is required”: the account is disabled or has only the monitoring role.
  • “This initial template has not been validated for FIPS UAG appliances”: FIPS mode is on. The template doesn’t support it.
  • “SAML encryption certificate rollover is enabled”: turn it off, or update the IdP first and renew by hand.
  • “Candidate certificate chain is not trusted on this host”: install the root CA on the agent host.
  • “UAG upload failed or its result is uncertain”: check the Internet interface certificate in the admin UI before you deploy again. The message includes the previous thumbprint.
  • “UAG accepted the upload, but the Internet listener did not serve the expected trusted certificate”: check that UAG Internet-interface IP or hostname points to this appliance, not a VIP, and that the agent host trusts the chain. Restore the previous PFX if users are affected.
  • Users still see the old certificate after a successful run: they connect through a load balancer to another UAG. Deploy to each appliance.

For a product overview, see certificate automation for VMware Horizon.