Configure Omnissa UAG with Omnissa Horizon

原文：Configure Omnissa UAG with Omnissa Horizon — theDXT (Daniel Keer)

In this post, I will show you step by step how to configure the Omnissa UAG (Unified Access Gateway) to work with Omnissa Horizon (formerly VMware Horizon).

Prerequisites

• Horizon connection server installed.

If you need to learn how, my post Install Horizon Connection Server details all the steps.

• Horizon connection server with a certificate installed.
• Horizon connection server certificate thumbprint.

If you need to learn how, my post Install Omnissa Horizon Connection Server Certificate details all the steps.

• UAG deployed.

If you need to learn how, my post Deploy Omnissa UAG on VMware vCenter details all the steps.

The Process

• Log in to the UAG.

• Select Configure Manually.

• Click the Edge Service Settings toggle to view the settings.

• Click the gear icon next to Horizon Settings.

• Click the toggle to Enable Horizon to view the Horizon settings.

• Next, we need to configure the Horizon settings.

There are many settings on the UAG that we don’t need to configure.

• For Connection Server URL, enter the URL of the connection server, including the protocol and port.

If your domain ends with .local, it is recommended to use the IP instead of the FQDN.

In my example, my domain is dxt.local, so I will use the IP of my Horizon connection server. I will enter https://192.168.172.20:443.

• For Connection Server URL Thumbprint, enter the thumbprint of the certificate used by your connection server. It will need to start with the algorithm.

In my example, the certificate algorithm I will use is SHA256, and the hash is c7a3e468d6d886e7c6e2d6e31dda609a357e719ef1. I will enter sha256=c7a3e468d6d886e7c6e2d6e31dda609a357e719ef1.

• Click on theEnable Blast toggle.

Blast is Horizon’s preferred remote connection method.

• For Blast External URL, enter the external URL you will use for Horizon, along with the port number. The default ports for TCP and UDP are 8443.

In my example, I will enter https://horizon.thedxt.ca:8443.

• Click on the toggle for Enable UDP Tunnel Server.

The UDP tunnel is used for poor connections.

• Click on the toggle for Enable Tunnel.

The tunnel is used for RDP, USB, and multimedia redirection (MMR).

• For Tunnel External URL, enter the external URL to be used for Horizon, along with the port number. The default is TCP port 443.

In my example, I will enter https://horizon.thedxt.ca:443.

• Review all the settings you entered and click Save.

• Wait a few moments for the configuration to take effect.

• Click on the arrow next to Horizon Settings to expand everything. Use the refresh icon to refresh the status.

It’s normal for Blast to take a bit longer than the others to come up.

• Confirm that all the Horizon settings you configured are green.

• Install your SSL certificate.

For more details on installing a certificate on the UAG, see my blog post, Omnissa Unified Access Gateway Certificate Install.

• Connect to your Horizon Connection Server.
• Log in to the Horizon admin console.

• Click on Settings > Servers.

• Click on Gateways.

• Click on Register.

• Enter the UAG hostname and click ok.

In my example, the hostname is DXT-HO-UAG01. I will enter that.

• Once the UAG receives a connection, all the information will be populated.

• Configure the locked.properties file on your Horizon connection server as needed.

For more information about configuring the locked.properties file for Omnissa Horizon, my blog post Configure locked.properties for Omnissa Horizon goes into detail.

What the Unified Access Gateway actually does

The Unified Access Gateway is a hardened Linux appliance that sits in the DMZ and takes over every connection that arrives from outside the corporate network. It terminates the external TLS session, authenticates the user against the Connection Server, and then proxies the session on to the desktop or published application using Blast Extreme, PCoIP or the Tunnel (RDP, USB redirection and multimedia redirection). Nothing is stored on it: it holds no desktop state, has no domain account and needs no Windows licence.

That design has three consequences worth understanding before you start clicking through the console.

• It is not a VPN. Only Horizon traffic is proxied. Users who need file shares, intranet sites or RDP to arbitrary servers need a separate remote access solution alongside it.
• It must be reachable in both directions. Clients on the outside, and the Connection Server plus the desktop network on the inside. Two NICs with static routes, or a single NIC with careful routing, are both supported; two NICs is the cleaner design and the one to use in production.
• It is only as good as its certificate and its thumbprint. The UAG validates the Connection Server by certificate thumbprint, and clients validate the UAG by its certificate. Get either wrong and you get a red status line instead of a helpful error.

Deploy it from the OVA in vSphere — Deploy Omnissa UAG on VMware vCenter covers that step — and in production deploy two appliances behind a load balancer, in different racks, so a maintenance window on one does not take remote access down.

Ports, DNS and firewall rules

The ports below are the published defaults for a Horizon deployment using Blast Extreme and the Tunnel. Confirm them against the Omnissa network ports documentation for your release before raising a change request, then verify with a capture rather than assuming the firewall rule works.

Two DNS points cause more tickets than any firewall rule. First, clients must be able to resolve the external name (for example horizon.example.com) to the load balancer or the UAG, while internal clients may resolve the same name to the Connection Server — split-horizon DNS has to be deliberate about which is which. Second, the UAG appliance is not domain-joined and does not use your internal DNS by default, so a Connection Server URL that ends in .local usually cannot be resolved at all. That is exactly why the steps above recommend the IP address in that case.

Certificates before you start

Two certificates are in play and they are easy to confuse:

• The UAG's own certificate is presented to users. Its subject alternative names must include the external FQDN used by the Blast External URL and the Tunnel External URL, and it should be issued by a CA the clients already trust. Install it after the gateway is registered; the procedure has the same shape as the Connection Server certificate described in Install Omnissa Horizon Connection Server Certificate.
• The Connection Server certificate thumbprint is what the UAG uses to verify the server it is talking to. It is an SHA-256 fingerprint entered in the form sha256=<hex>: include the algorithm prefix, use lower case, and do not paste the colon-separated display format.

If your Connection Server uses an internal CA certificate, import the same root into the UAG trust store, otherwise the tunnel and Blast services come up red even though the thumbprint is correct. Certificates on the Connection Server also drive locked.properties behaviour, so changing one has knock-on effects elsewhere in the pod.

Understanding the Horizon settings on the UAG

The Horizon edge service exposes more fields than most deployments need. The ones that matter are:

• Connection Server URL — protocol, address and port of the Connection Server, for example https://192.168.172.20:443. This is the address the UAG uses for authentication and brokering.
• Connection Server URL Thumbprint — the sha256= value taken from the certificate actually in use, as described above.
• Enable Blast — switch this on for every modern deployment. Blast Extreme is Omnissa's preferred protocol and the only one that uses UDP efficiently over poor links.
• Blast External URL — exactly the URL clients will use, including the port, for example https://horizon.example.com:8443. If this does not match reality the client is brokered to an address it cannot reach.
• Enable UDP Tunnel Server — improves Blast behaviour over congested or lossy links; leave it on unless a firewall cannot pass UDP 8443.
• Enable Tunnel and Tunnel External URL — required for RDP, USB redirection and multimedia redirection, typically https://horizon.example.com:443.
• PCoIP — enable and fill in only if you still run PCoIP. On a Blast-only design leaving it off reduces the attack surface.

Everything else on the page — idle session timeouts, health checks, the gateway location string — can usually stay at default on a first build. Change one thing at a time and refresh the status rather than editing several fields and then guessing which one broke it.

Verifying the gateway after registration

Registration in the Horizon console is not the same thing as a working gateway, so check both ends.

1. On the UAG, expand Horizon Settings and refresh. Every edge service status should be green. Blast routinely takes longer than the others to come up, so wait a minute or two before troubleshooting.
2. In the Horizon admin console go to Settings > Servers > Gateways. The UAG should be listed with a current timestamp, and once it has connected the address and version fields populate. A gateway that appears but stays blank has never completed its handshake.
3. From outside the network, browse to the Blast External URL. You should receive the certificate you installed, with a valid chain and the correct name, and a Horizon web page rather than a connection error.
4. Launch a desktop from an external client and confirm the session appears under Monitor > Sessions in the Horizon console rather than as a direct connection.
5. Confirm the traffic uses the intended path. A Blast session that silently falls back to TCP still works, but it will look terrible on a high-latency link — and the reason is usually UDP 8443 blocked somewhere between client and gateway.

# From a client outside the network: confirm the gateway ports answer
curl -kIv https://horizon.example.com:8443/    # Blast Extreme
curl -I  https://horizon.example.com/          # Tunnel over 443
openssl s_client -connect horizon.example.com:8443 -servername horizon.example.com

# From the UAG console itself: confirm the path to the Connection Server
nc -vz 192.168.172.20 443
nc -vz 192.168.172.20 8443
ip route
cat /etc/resolv.conf

If the UAG can resolve and reach the Connection Server but the edge service is still red, the problem is the thumbprint rather than the network — and if the client cannot reach port 8443 at all, fix the firewall before touching the gateway configuration.

Troubleshooting the common failure modes

• Blast or Tunnel stays red. Nine times out of ten it is the thumbprint: wrong algorithm prefix, upper case hex, colon-separated formatting, or a certificate that was replaced after the value was copied. Re-copy it from the certificate the Connection Server is actually serving.
• The UAG cannot reach the Connection Server. Check that the URL includes the protocol and port, confirm the UAG's DNS settings or that you used an IP address, and test connectivity from the UAG console itself. The appliance has its own static network configuration and default gateway.
• Sessions launch but the client cannot connect. The Blast External URL does not match the address clients use, or the load balancer is not passing the right port through. The brokered URL is built from what you typed in that field.
• Certificate errors on the client. Missing SAN entries, an expired certificate, or clock skew on the UAG — check NTP first, then check the chain.
• Only some clients fail to launch a session. This is usually a Horizon-side configuration problem rather than a gateway problem; the unmanaged VDI black screen notes are a good starting point for session-level faults.
• Blast works but RDP does not. The Tunnel service is disabled, or the Tunnel External URL is missing. Tunnel is a separate service with its own URL and port.

Hardening and day-2 operations

• Turn off what you do not use. Secure Web Reverse Proxy, VMware Tunnel, Content Gateway and the other edge services add code paths you have to patch. A disabled service is a feature.
• Keep the management interface internal. Port 9443 belongs on a management network with source restrictions, not on the internet.
• Keep UAG and Connection Server versions aligned. A UAG far ahead of, or far behind, the Connection Server produces brokering and protocol failures that look exactly like network problems.
• Log centrally. Point the UAG at your syslog collector and put its logs in the same pipeline as the Connection Server and the load balancer, so a session failure can be followed end to end.
• Back up the configuration. Export the edge service settings from the admin console after every change so a rebuild is a restore rather than an afternoon of typing.
• Test the failure cases. Reboot one UAG during a maintenance window and confirm clients fail over to the other, then repeat with the load balancer member disabled. Failover that has never been tested is not failover.

For more information on configuring the Omnissa UAG (Unified Access Gateway) to work with Omnissa Horizon, here is the Omnissa documentation.