Configuring the Horizon Edge Service in VMware Unified Access Gateway: VMware Horizon Operational Tutorial

VMware Unified Access Gateway 3.7 and later VMware vSphere 6.5 U1 and later

Overview

Introduction

VMware provides this operational tutorial to help you with your VMware Horizon® environment. VMware Horizon simplifies the management and delivery of virtual desktops and apps on-premises, in the cloud or in a hybrid or multi-cloud configuration. This tutorial walks through configuring the Horizon edge service on VMware Unified Access Gateway™.

Audience

This operational tutorial is intended for IT professionals and Horizon administrators of existing production environments. Both current and new administrators can benefit from using this tutorial. Familiarity with networking and storage in a virtual environment is assumed, including Active Directory, and directory services. Knowledge of additional technologies such as VMware Horizon is required.

Configuring the Horizon Edge Service

Introduction

This section guides you through the configuration and deployment of the VMware Unified Access Gateway appliance and configuration of the Horizon edge service using a PowerShell script. The exercises also describe how to set up Horizon edge service to enable external access to internal virtual desktops and applications.

In this tutorial, the Unified Access Gateway appliance is deployed with two NICs. One NIC faces the Internet, and the second one is dedicated to management and backend access. Horizon edge service will be configured to allow external access to virtual desktop and applications hosted on the internal network.

These exercises cover Horizon 7, Unified Access Gateway 3.7 deployed in vSphere 6.5 U1, and are applicable to Unified Access Gateway 3.3 and later.

The steps are sequential and build upon one another, so make sure that you complete each step before going to the next step.

The purpose of this tutorial is to provide a deployment option for an environment that could be used for production. If you want a more basic deployment with a single NIC for proof-of-concept, see Deploying Unified Access Gateway with One NIC through vSphere.

Architecture

The architectural diagram in this section shows an example environment that emulates a typical environment, including DMZ and internal networks.

In this example, external requests to the vApp are sent to the vPod Router, which directs those requests to the appropriate resource, based on the incoming port. Ports 4000-6500 are reserved for the environment components so all traffic coming in on these ports is forwarded to the appropriate edge service for the Unified Access Gateway server. In addition, ports 443 and 9443 are forwarded to the Unified Access Gateway server over the respective ports.

The vApp networks (internal, DMZ, and transit) are created within the vApp. The internal and transit networks are NATed to the SE-UCS-Network for outbound internet connectivity while the DMZ network routes through the vPod Router for inbound and outbound access. Note that the vPodRouter does not have a NIC on the internal network and thus cannot route external traffic to resources on the internal network.

vPod Router | ESXi01 6.5.0 U1 | Control Center | Horizon Connection Server | vCenter Server 6.5 U1 hosted on ESXi01

Architecture Overview Diagram

The following architectural diagram shows an example of two major networks that you can deploy your servers into. For this set of exercises, you deploy the Unified Access Gateway appliance on a DMZ and assign the respective NICs. The Horizon Connection Server and VMs for VDI and RDSH are hosted on the internal network.

At the top of the diagram is vCenter networking. At the bottom of the diagram is the vApp network required to support the environment. For these exercises, the focus is on the network hosted on ESXi, and represented by the following three networks:

  • VM Network & Management: Represents the dedicated network to access the Management Console
  • Internal Network: Represents the internal network on the 172.16.0.x range. The Control Center, ESXi, and vCenter are part of the internal network.
  • DMZ Network: Represents the DMZ network on 192.168.110.x which is where the Unified Access Gateway appliance is to be deployed. The Unified Access Gateway Internet-facing NIC is associated with this network.

Network Interfaces

Unified Access Gateway supports deployments with one, two, or three NICs. This means that the server can be partitioned to receive traffic on a single interface or to route traffic to different interfaces, based on the source of the request. Most often, if you need to implement multiple NICs, you already follow this standard with other web applications in your organization.

You must determine what is appropriate for your environment when selecting the number of NICs during installation. It is important for you to understand the expected behavior when two or three NICs are enabled.

Two sections are provided to explore these options. As a first step toward understanding basic deployments, you can install Unified Access Gateway with one NIC using vSphere Client, described in Deploying Unified Access Gateway with One NIC Through vSphere. You can then advance to the next step and install Unified Access Gateway with two NICs as a production environment using PowerShell, described in Deploying Unified Access Gateway with Two NICs Through PowerShell.

General Considerations

In the exercises for deploying the Unified Access Gateway server through vSphere, the vCenter setup is hosted in a nested template. This is not usually the case when working with users in a live environment.

User environments can include multiple networks and can optionally have a Network Protocol Profiles (NPP) that corresponds to the networks to connect to the Unified Access Gateway. Prior to version 3.3, NPP was a requirement. Since version 3.3, NPP is no longer required.

Note: Keep in mind that the Unified Access Gateway requires a netmask, default gateway, and subnet to be defined for each network enabled during deployment.

Prerequisites

Before you deploy Unified Access Gateway using a PowerShell script, you must satisfy the following requirements:

  • Set up a VMware vSphere ESXi host with a vCenter Server
  • Deploy one Horizon 7 Connection Server
  • Set up one Application Pool with at least one app, or one Desktop Pool with at least one virtual desktop
  • Install Horizon Client on a Windows 10 or macOS client machine

You must use the following specific versions of VMware products:

  • VMware vSphere 6.5 U1
  • VMware Unified Access Gateway 3.4
  • Windows 8.1 or Windows Server 2008 R2 or later
  • Machine with VMware OVF Tool 4.3 or later installed

Before you begin:

  • Obtain a Unified Access Gateway virtual appliance image OVA file, such as .euc-access-point-3.4.X.X-XXXXXXXXXXX.ova (see VMware Product Interoperability Matrixes to determine which version to download).
  • Download the Unified Access Gateway PowerShell script version 3.4. 
    1. Navigate to https://my.vmware.com  and log in.
    2. Search under Products for Unified Access Gateway.
    3. Select uagdeploy-VERSION.zip.

Configuring the Horizon Connection Server

In this exercise, you configure the Horizon Connection Server for use with Unified Access Gateway.

The Unified Access Gateway runs the following gateways as part of the Horizon edge service: the Blast Secure Gateway, the PCoIP Secure Gateway, and the HTTPS secure tunnel. You must confirm that these gateway services are not also enabled on the Connection Server because this would cause a double-hop attempt of the protocol traffic, which is not supported and will result in failed connections.

1. Log In to Horizon Administration Console

To access the Horizon Administration Console, navigate to https://server/admin on your Web browser, where server is the host name of the Connection Server instance.

  1. Enter the user name.
  2. Enter the password.
  3. Enter the Domain.
  4. Click Sign in.

2. Configure Connection Server Settings

  1. Click Settings.
  2. Click Servers.
  3. Select Connection Servers.
  4. Select the Connection Server to be used as the front-end server for Unified Access Gateway deployed in this exercise.
  5. Click Edit.

3. Disable Gateway Services on the Connection Server

  1. Select General.
  2. Make sure Use Secure Tunnel connection to machine is deselected.
  3. Make sure Use PCoIP Secure Gateway for PCoIP connections to machine is deselected.
  4. Make sure Do not use Blast Secure Gateway is selected.
  5. Click OK.

Logging In to the vSphere Web Client

To perform most of this exercise, you need to log in to the vSphere Web Client.

1. Launch Chrome Browser

Launch Chrome Browser

Double-click the Google Chrome browser icon on the desktop.

2. Authenticate to the vSphere Web Client

  1. Launch the Chrome browser from your desktop and navigate to your vCenter Server URL.
  2. Enter the username, such as administrator@vsphere.local.
  3. Enter the password, such as VMware1!.
  4. Click Login.

After completing the login, you are presented with the vSphere Web Client.

Preparing the INI File for Deployment

In this section, you learn how to use the INI file to deploy Unified Access Gateway including the Horizon edge service configuration using PowerShell, and how to edit the contents of the INI file for your Unified Access Gateway deployment.

An INI file containing all of the configuration settings is required to deploy the Unified Access Gateway appliance.

In this exercise, you use the uag-Horizon.ini file to provide the respective parameters for your deployment.

You deploy a new Unified Access Gateway appliance called UAGHZ in the example, which has two NICs. NIC1 is Internet-facing and NIC2 is for backend and management. The Horizon edge service will be configured and ready for use on first boot of the appliance.

Note: The values used in this section are based on a test environment. Your values will differ.

1. Open the UAG-2NIC.ini File for Editing

Editing UAG-2NIC.ini

Navigate to your uag-Horizon.ini file. In this example, the file is located in UAG Resources.

  1. Click the File Explorer icon on the taskbar.
  2. Click Desktop.
  3. Click UAG Resources.
  4. Right-click the uag-Horizon.ini file.
  5. Click Edit with Notepad++.

2. Configure General Settings (1/2)

General Settings 1/2

In the General section, provide the following settings in the INI file:

  1. For name, enter a name, such as UAG-2 in this example.
  2. For source, enter the path, such as C:\Users\Administrator\Desktop\UAG Resources\UAG Files\euc-unified-access-gateway-3.3.0.0-8539135_OVF10.ova, and use File Explorer to verify that the OVA file has the name indicated.
  3. For target, enter the destination path related to the vCenter host that you plan to deploy the appliance, such as  vi://administrator@vsphere.local:VMware1!@vc.corp.local/Nested_Datacenter/host/Host_Cluster.
  4. Note: You can replace the password with 'PASSWORD' and the script prompts for the password during the PowerShell execution.
  5. For diskmode, enter thin.
  6. For ds (ds refers to data store), enter datastore2_ESXi01.
  7. For deploymentOption, enter twonic.

3. Configure General Settings (2/2)

General Settings 2/2

Continue the General section configuration, and set the following additional values for the parameters in the INI file, keeping in mind that ip0 is the Internet-facing NIC, and ip1 is the internally facing NIC:

  1. For ipMode, enter STATICV4.
  2. For defaultGateway, enter the IP address, such as 192.168.110.1.
  3. For dns, enter the IP address, such as 192.168.110.10.
  4. For ip0, enter the IP address, such as 192.168.110.20.
    Important: ip0 is the Internet-facing NIC.
  5. For ip1, enter the IP address, such as 172.16.0.20.
    Important: ip1 is the internally-facing NIC.
  6. For netmask0 and netmask1, enter the netmask, such as 255.255.255.0.
  7. For netInternet, enter DMZ_VM_DPortGroup.
  8. For netManagementNetwork and netBackendNetwork, enter Internal_VM_DPortGroup.

4. Configure the Horizon Edge Service

Continue to the Horizon section configuration, and set the following additional values for the parameters in the INI file, keeping in mind that the following parameters enable access through the tunnel, Blast, and PCoIP protocols. For this tutorial, we will only use the Blast protocol for testing.

Under the Horizon section configure the following fields:

  1. For proxyDestinationUrl, enter the URL for the Connection Server or internal load balancer to which Unified Access Gateway directs traffic, such as https://s1horizon.vmweuc.com.
  2. For tunnelDestinationUrl, enter the URL used by Horizon clients to establish the Horizon Tunnel session to this Unified Access Gateway appliance, such as https://horizon.vmweuc.com:443.
  3. For blastExternalUrl, enter the URL used by Horizon clients to establish the Horizon Blast or BEAT session to this Unified Access Gateway appliance, such as https://horizon.vmweuc.com. If the TCP port number is not specified, the default TCP port is 8443. If the UDP port number is not specified, the default UDP port is also 8443.
  4. For pcoipExternalUrl, enter the IP used by Horizon clients to establish the Horizon PCoIP session to this Unified Access Gateway appliance, such as 66.170.97.71:4172. It must contain an IPv4 address and not a host name.

5. Configure the TLS/SSL Certificates

Select Name and Location

The SSLCert and SSLCertAdmin contain the information regarding the SSL Certificates for the administration and Internet interfaces.

  1. For pfxCerts under SSLCert, enter C:\AW Tools\airwlab.com.pfx (this certificate is for the Internet interface).
  2. For pfxCerts under SSLCertAdmin, enter C:\AW Tools\airwlab.com.pfx (this certificate is for the administration interface).

Note: The certificate password may get requested during the deployment.

Deploying the Unified Access Gateway Appliance

Now that you have configured the INI file for your Unified Access Gateway deployment, you can run the uagdeploy.ps1 PowerShell script and provide this INI file as the configuration to automate the deployment.

1. Launch PowerShell

Launch PowerShell window

Click the PowerShell icon located on the Windows task bar.

 

2. Navigate to the Unified Access Gateway Resources Directory

Navigate to the Unified Access Gateway Resources Directory under the desktop user folder by entering cd '.\Desktop\UAG Resources' and then press Enter.

3. Execute the Deployment Script

Running the script

After you run the uagdeploy.ps1 script, it prompts for input.

  1. When prompted, enter the information requested, such as in the following example:
    .\uagdeploy.ps1 .\uag-2NIC VMware1! VMware1! false false no
    • The first VMware1! is the root password for the Unified Access Gateway appliance.
    • The second VMware1! is the admin password for the REST API management access.
    • The first false is to NOT skip the validation of signature and certificate.
    • The second false is to NOT skip SSL verification for the vSphere connection.
    • The no is to not join the VMware CEIP program.
  2. When prompted, enter the password for the SSLcert and SSLcertAdmin fields.

To avoid a password request for the certificate, remove the pfxCerts values and provide a PEM certificate, and set the pemCerts and pemPrivKey for the SSLCert and SSLCertAdmin sections of the INI file.

The deployment starts and you can follow the progress on the same window or on your vSphere Web Client, which you opened at the beginning of this tutorial.

4. Confirm that the PowerShell Script Deployment Completes

Deployment finished

After successfully finalizing the deployment, the script automatically powers on the VM UAG-2

The Received IP address presented by the script log is a temporary IP. The final IPs for NIC 1 and NIC2 are assigned to the Unified Access Gateway appliance during the first start. You can return to the vSphere Web Client to validate that as described in the next step.

5. Validate the Deployment

Validating UAG Appliance status

Return to the vSphere Client to validate the deployment.

  1. Click VM and Templates.
  2. Click UAG-2.
  3. Click View all 2 IP addresses.

Important: If the Unified Access Gateway appliance does not finalize the configuration during the first startup, you receive an error message from vSphere Web Client. If that happens, wait for the appliance to finalize, and refresh the entire Google Chrome browser.

6. Log In to the Unified Access Gateway Administration Console

UAG Admin UI Login
  1. Click the New Tab button to open a new tab.
  2. Browse to the Unified Access Gateway Administration Console using the URL, such as  https://uagmgt-int.airwlab.com:9443/admin or by clicking a bookmark if you created one.
  3. Enter the username, such as admin in this example.
  4. Enter the password created for the Admin API in the Deploy OVF Wizard.
  5. Click Login.

7. Confirm the Administration Console Login on the Internal Network

Succesfull login

A successful login redirects you to the initial window where you can import settings or manually configure the Unified Access Gateway appliance.

Click Select under Configure Manually.

Validating the Horizon Edge Service Configuration

At this point, the Unified Access Gateway appliance has been deployed and you can access the administration console to manage the appliance configuration.

In this exercise, you learn how to review and update the configuration (when necessary) of the Horizon edge service.

1. Access Horizon Settings

Acessing Reverse Proxy Settings
  1. Click the Show toggle next to Edge Service Settings. After you click, it switches to display the Hide option.
  2. Click the Arrow on Horizon Settings to show the status of the communication between the appliance and Horizon.
  3. Click the gear icon next to Horizon Settings.

All items should be GREEN, representing that the appliance can communicate with the Horizon Connection Server through the multiple protocols configured. Items not fully functional are presented in RED.

2. Validate Horizon Edge Service Configuration

Horizon settings

The configuration defined in the INI file is presented and can be updated any time through the Horizon settings.

Click Cancel to close the settings.

Connecting to a Virtual Desktop or Application through Unified Access Gateway

In this exercise, you learn how to configure the Horizon Client to connect to a virtual desktop or application through Unified Access Gateway.

1. Configure the Horizon Client

Horizon Client
  1. Launch Horizon Client.
  2. Click Add Server.
  3. Enter the Unified Access Gateway or load balancer IP or FQDN.
  4. Click Connect.

2. Authenticate through Horizon Client (XML-API Protocol)

After you configure the Connection Server instance to connect to Unified Access Gateway, the Horizon Client will require user credentials to perform the authentication. This is known as XML-API connection and is responsible for authentication, authorization, and session management.

  1. Enter the User name.
  2. Enter the Password.
  3. Select the Domain.
  4. Click Login.

3. Launch a Virtual Desktop or Application (Secondary Protocol)

A successful connection will present the desktops and applications entitled to logged-in users. In this exercise, you can see one virtual desktop (Win10 1803) and four other virtual applications (Calculator, Notepad, Paint, WordPad).

  1. Right-click the desktop or one of the applications.
  2. Ensure that VMware Blast (default) is selected.
  3. Click Launch.

When you launch the desktop or applications, Horizon client opens a secondary connection through Unified Access Gateway based on the display protocol selected. The secondary Horizon protocols must be routed to the same Unified Access Gateway appliance to which the primary Horizon XML-API protocol was routed. This allows the Unified Access Gateway to authorize the secondary protocols based on the authenticated user session.

4. Confirm the Virtual Desktop or Application has been Launched

Confirm that you have successfully launched the virtual resource.

  1. Click Options.
  2. Click Disconnect and Log Off.

5. Reviewing Horizon Protocols Flow

The following diagram demonstrates the flow for the primary (XML-API) and secondary protocols used in this section. These protocols were invoked in exercises 2 and 3; when you authenticated through the Horizon Client and launched the virtual desktop or application.

Summary and Additional Resources

Conclusion

In these exercises, you have learned how to:

  • Deploy the VMware Unified Access Gateway and configure the Horizon edge service through a PowerShell script.
  • Update Horizon edge service configuration through the Unified Access Gateway administration console.
  • Configure Horizon Client to access virtual desktops and applications through Unified Access Gateway.

Additional Resources

For more information, explore the following Activity Paths on Digital Workspace Tech Zone. 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.

Additionally, you can check out the VMware Workspace ONE and VMware Horizon Reference Architecture which provides a framework and guidance for architecting an integrated digital workspace using VMware Workspace ONE and VMware Horizon. 

 

About the Author

This tutorial was written by:

  • Andreano Lanusse, End-User-Computing Staff Architect, Technical Marketing, VMware.

Feedback

Your feedback is valuable. 

To comment on this tutorial, contact VMware End-User-Computing Technical Marketing at euc_tech_content_feedback@vmware.com.