By Mark Benson, Senior Architect and Senior Staff Engineer, End-User-Computing CTO Office, VMware
Introduction
Updated March 2019 for version 3.5
In September 2015, I posted the article https://blogs.vmware.com/euc/2015/09/what-is-vmware-unified-access-gateway-secure-remote-access.html. Unified Access Gateway (UAG) is a VMware virtual appliance which is used with several VMware End-User Computing products for VMware Horizon, VMware Identity Manager and VMware AirWatch. In that article I mentioned the ability to perform a scripted deployment of a UAG virtual appliance to perform a repeatable deployment where all settings can be applied in a way that allows UAG to be production ready on first boot.
It is possible to deploy UAG in a vSphere environment using the VMware OVF Tool command. Whilst it is great to be able to specify all configuration settings in one go at deployment time, the downside of this is that the OVF Tool command line can become very long and complex. It is also easy to introduce errors on the command line as the command syntax for OVF Tool used in this way can be difficult to get right. Also, it is not possible to validate the settings with OVF Tool and it is therefore very easy to make configuration errors such as setting an admin REST API password that doesn't meet the required complexity rules.
Many Windows administrators managing a VMware End-User Computing product environment need an automated way to deploy UAG in a secure, reliable and repeatable way and to have complete control over the settings. For these reasons, we have developed a PowerShell script that can be used to deploy UAG and which overcomes the main difficulties of using OVF Tool directly on the command line. As this PowerShell script is delivered as a sample script, you can also adapt it as required for your specific needs although in most cases you won't need to modify it at all. The script calls the OVF Tool command but validates the settings and automatically constructs the correct command line syntax. The settings are taken from a simple .INI file. This script runs OVF Tool in a fully supported way for UAG deployment. Note that no password values or private key values are stored within the .INI configuration files.
The PowerShell script sets all configuration settings for OVF Tool at deployment time. This includes setting up the CA issued SSL Server certificate and all other possible settings. After UAG has been deployed by this script, there is no need to make configuration changes after deployment. UAG will be ready for production use on first boot. Using PowerShell and mastering configuration settings in a simple .ini file also simplifies the task or repeat deployments such as when upgrading UAG from one version to the next. You modify the .ova file reference in the .ini and re-run the PowerShell command. This automatically deletes the existing UAG appliance and replaces it with the upgraded image and automatically re-applies all of the initial settings from the .ini file.
What are the requirements for deploying UAG appliances using this script?
- For UAG itself, a vSphere ESXi host and a vCenter Server is needed. Decide on the vSphere datastore to be used and the Network name to be used. If you are deploying a pre 3.3 version of UAG then a vSphere Network Protocol Profile (or IP Pool) must be associated with every referenced network name. This Network Protocol Profile specifies network settings such as IPv4 subnet mask, gateway etc. The deployment of pre 3.3 UAG appliances uses these values so make sure the values are correct. Note: In order to improve vSphere deployment flexibility, UAG 3.3 no longer uses NPPs or IP Pools. This means UAG can be deployed in environments where these are not set up. Instead, settings of IPv4 netmask, IPv6 prefix and defaultGateway (as required) must be specified in the .ini file instead. Refer to the network settings section below for details of the configuration of each UAG NIC for IPv4 and IPv6 combinations supported.
- The PowerShell script runs on a machine running Windows 8.1 (or newer) or Windows Server 2008 R2 (or newer). This can be the vCenter Server itself if it is running on Windows, or can be a separate Windows machine.
- The Windows machine running the script must also have the VMware OVF Tool command installed. Install OVF Tool 4.2.0 or newer. You can download it from here OVF Tool Software and Documentation.
How do I run the script?
- Download a version of UAG virtual appliance image from VMware onto your Windows machine. This is an OVA file. e.g. euc-unified-access-gateway-3.3.0.0-8539135_OVF10.ova. Refer to VMware Product Interoperability Matrixes to determine the latest version to download.
- Download the correct uagdeploy or apdeploy ZIP file attached below and extract the files into a folder on your Windows machine. Note that recent uagdeploy zip files are downloaded from VMware from the same location as the UAG images are downloaded. They are no longer attached to this page.
- On your Windows machine, open a PowerShell console and change directory to the location of your script.
- Create a .INI configuration file for your UAG virtual appliance. In this example, I am going deploy a new UAG appliance called UAG1. I have created a .INI file called uag1.ini which contains all the configuration settings for UAG1. You can use the sample .INI files contained within the uagdeploy ZIP file to create your .INI file and then modify the settings to the values you want.
- Make sure script execution is unrestricted for the current user. You can do this by running the command:
set-executionpolicy -scope currentuser unrestricted - You only need to run this once and only if it is currently restricted.
If you get a warning about running this script, you can unblock that warning by running the command:
unblock-file -path .\uagdeploy.ps1
or
unblock-file -path .\apdeploy.ps1 - Run the command .\uagdeploy.ps1 -iniFile uag1.ini as shown in the screenshot below. If you don't specify the -iniFile option, the script will default to ap.ini. You will be prompted to set a root password for the appliance and an optional password for the admin REST API. You will also be prompted for the vCenter password. Deployment takes around a minute depending on your host and storage performance. If you are prompted to add the fingerprint for the target machine, enter yes.
![PowershellAPDeploy1.png]()
- When the script completes, the UAG appliance is ready to use. No further configuration steps are required.
.INI File Contents
The uagdeploy ZIPfile attached at the bottom of this post contains four example .INI files. uag1-basic.ini is a minimal .INI file which just contains the minimum settings needed. uag2-advanced.ini is a more complex configuration file showing additional settings available. uag3-securid.ini is an example of a configuration including RSA SecurID authentication. uag4-radius.ini is an example of a configuration including RADIUS authentication. You should start with just a basic .INI file to ensure that this deployment method works in your environment. You can then add more advanced settings in your .INI file and repeat the deployment. If you have already deployed the named UAG appliance, then running the script again will power off the appliance, delete it, and will redeploy it with the current .INI settings. This is a useful capability to use when either upgrading the appliance to a newer version, or just to change any of the settings.
Basic .INI File Example
##############################################
[General]
name=UAG1
source=C:\APs\euc-unified-access-gateway-3.1.0.0-6645767_OVF10.ova
target=vi://administrator@vsphere.local:PASSWORD@192.168.0.21/Datacenter1/host/esx1.myco.int
ds=Local Disk 1
netInternet=VM Network
netManagementNetwork=VM Network
netBackendNetwork=VM Network
honorCipherOrder=true
[Horizon]
proxyDestinationUrl=https://192.168.0.209
##############################################
The following table describes each configuration setting. These must be arranged in the .INI file under the appropriate Group Name shown in the first column and as shown in the sample .INI files.
Configuring UAG as a Web Reverse Proxy for VMware Identified Manager
UAG (or Access Point) 2.6 and newer can be used as a Web Reverse Proxy in front of VMware Identity Manager version 2.6 (and newer). Make sure you use a 2.6 (or newer) version of UAG or Access Point e.g.
source=euc-unified-access-gateway-3.1.0.0-6645767_OVF10.ova
For exact up to date information on UAG and Access Point compatibility, refer to the VMware Product Interoperability Matrixes.
For this setup, remove the entire [Horizon] section from the .ini file and replace it with a new [WebReverseProxy] section. Use the values shown in the sample uag10-vidm.ini file in uagdeploy ZIP file below. Set the proxyDestinationUrl to the URL of the Identity Manager server. If that service does not use a trusted CA signed SSL server certificate then you will also need to add the proxyDestinationUrlThumbprints value. Leave all other values in [WebReverseProxy] exactly as shown in the sample uag10-vidm.ini.
The setup requires "split DNS" to be setup where the URL hostname for an external user resolved to the address of UAG, and the same URL hostname for an internal user resolves to the address of the Identity Manager server.
Configuration Settings
| Group Name | Value | UAG or AP Version Required (if applicable) | Example | Description |
|---|
| [CertificateAuth] | pemCerts | | pemCerts=C:\Users\Administrator\SSL\north-ca-256.cer | Used for certificate authentication to specify the public CA cert file (in PEM base64 format) that was used to issue the required client certificates. See notes below on Client Device certificate authentication. |
| crlCacheSize | | crlCacheSize=120 | CRL Cache size. Default is 100. |
| crlLocation | | crlLocation=http://crl.myca.com | CRL Location |
| enableCertCRL | | enableCertCRL=true | Use CRL from Certificates |
| enableCertRevocation | | enableCertRevocation=true | Enable Cert revocation |
| [General] | adminPasswordExpirationDays | 3.2+ | adminPasswordExpirationDays=100 | Number of days after which the admin user password will expire. |
| defaultGateway | 3.0+ | defaultGateway=192.168.0.1 | Specifies the default gateway address for the UAG appliance. Used in cases where the Network Protocol Profiles in vSphere do not contain a default gateway. Also used to avoid ambiguity in cases where multiple Network Protocol Profiles are used each specifying a different gateway. An appliance can only have one default gateway and so this value can be used to explicitly specify it. In addition to the defaultGateway, routes for other gateways can be added using the routes0, routes1 and routes2 setting for each NIC. |
| deploymentOption | | deploymentOption=onenic | UAG can be created with either one, two or three network interface cards (NICs). Either specify onenic, twonic or threenic. The default is onenic. This is for the standard 2 vCPU 4GB RAM deployment. It is also possible to specify onenic-large, twonic-large and threenic-large. These large options deploy UAG as 4 vCPU 8GB RAM. This is intended for large Workspace ONE UEM deployments supporting over 10,000 concurrent mobile devices. |
| diskMode | 2.8+ | diskMode=thin | OVF Tool vSphere Disk Mode. Sets the disk provision mode. Refer to the OVF Tool documentation for further options. Default is thick. |
| dns | | dns=192.168.0.1
dns=192.168.0.1 192.168.0.2 | Optional DNS server address. Default is none. Multiple addresses must be space separated. |
| dnsSearch | 3.6+ | dnsSearch=localdomain.com
dnsSearch=domain1.com domain2.com domain3.com | Optional list of DNS search domains added to resolv.conf. |
| ds | | ds=Local Disk 1 | Datastore name which the appliance will be deployed to. |
| fallbackNtpServers | 3.6+ | fallbackNtpServers=ntp3.myco.in ntp4.myco.int | Optional list of fallback NTP servers. |
| folder | | folder=My VM Folder/My Sub Folder | Deploys the appliance in the named VMs and Templates folder. Folders in vCenter are shown under VMs and Templates. The folder specified must exist before deployment. |
| forwardrules | 2.8+ | forwardrules=tcp/5262/10.20.30.40:5262,
tcp/88/10.20.30.40:88,
udp/88/10.20.30.40:88 | A comma separated set of TCP or UDP forwarding rules. It is used as a generic protocol forwarding mechanism. Each item in the list is of the following format. tcp|udp/listen-port-number/destination-ip-address:destination-port-number The first part is tcp or udp listen-port number is the destination port number of a TCP connection or UDP datagram received by UAG. The number must not be one of the port numbers already in use on UAG. The TCP or UDP protocol will be forwarded by UAG iptables to the destination-ip-address and destination-port number. |
| honorCipherOrder | 2.7.2+ | honorCipherOrder=true | Default value is false. When set to true, the cipher list order for the SSL/TLS 443 listener is determined by the server. This allows forward secrecy ciphers to be presented first in the cipher list to improve security. With UAG 2.7.2 and newer it is recommended that this is set to true. |
| ip0 | | ip0=192.168.0.10 | IPv4 address for NIC0 (onenic, twonic or threenic) |
| ip1 | | ip1=192.168.0.11 | IPv4 address for NIC1 (twonic or threenic) |
| ip2 | | ip2=192.168.0.12 | IPv4 address for NIC2 (threenic) |
| licenseEdition | 3.4 only | licenseEdition=Standard
licenseEdition=Advanced
licenseEdition=Enterprise | Specifies the licenseEdition. Advanced and Enterprise will enable additional features. Refer to the documentation for details.
Not used in versions prior to 3.4 and not used in 3.5 onward. With UAG 3.5 all features are available. |
| name | | name=UAG1 | Name of the virtual appliance as shown in vCenter. It must be between 1 and 32 characters long. If name is omitted, the PowerShell script will prompt for it. |
| netInternet | | netInternet=VM Network | The name of the vSphere Network for the UAG primary network |
| netManagementNetwork | | netManagementNetwork=VM Network | The name of the vSphere Network for the UAG management interface network. |
| netmask0 | Mandatory in 3.3+ | netmask0=255.255.255.0 | IPv4 netmask for NIC0 (onenic, twonic or threenic) |
| netmask1 | Mandatory in 3.3+ | netmask1=255.255.255.0 | IPv4 netmask for NIC1 (twonic or threenic) |
| netmask2 | Mandatory in 3.3+ | netmask2=255.255.255.0 | IPv4 netmask for NIC2 (threenic) |
| netBackendNetwork | | netBackendNetwork=VM Network | The name of the vSphere Network for the UAG backend network. |
| ntpServers | 3.6+ | ntpServers=ntp1.myco.in ntp2.myco.int | Optional. Sets a list of non default NTP servers for UAG time synchronization. Normally this doesn't need to be set as UAG uses default Internet time servers. |
| routes0 | 2.7.2+ | routes0=192.168.1.0/24 192.168.0.1,
192.168.2.0/24 192.168.0.2 | List of static routes for NIC0. Comma separated list of static routes in the form of: network in CIDR format followed by a space followed by the gateway IP address. A network with addresses 192.168.1.0 to 192.168.1.255 and a subnet mask of 255.255.255.0 is represented in CIDR format as 192.168.1.0/24. |
| routes1 | 2.7.2+ | | List of static routes for NIC1. |
| routes2 | 2.7.2+ | | List of static routes for NIC2. |
| sessionTimeout | 2.7.2+ | sessionTimeout=39600000 | Maximum session time in milliseconds allowed for a logged on user. Default is 36000000 (10 hours). User is automatically logged off after this timeout and is required to log in again. |
| snmpEnabled | 3.6+ | snmpEnabled=true | Enables SNMP GET and GETNEXT support on UDP port 161. This is to provide basic information and monitoring data such as sysDescr, sysName, sysUptimeInstance and CPU and memory information using the SNMP protocol. e.g. run the following command on the UAG console (on a single line) to list the information. snmpwalk -v 2c -c public 127.0.0.1 1.3.6 |
| source | | source=C:\Temp\euc-access-point-2.9.0.0-5178136_OVF10.ova | Full path filename of the UAG .ova virtual machine image. The file can be downloaded from VMware. |
| syslogUrl | | syslogUrl=syslog://server.example.com:514 | Optional syslog server URL. This allows syslog events to be forward to a syslog management server. |
| target | | target=vi://administrator@vsphere.local:PASSWORD@ 192.168.0.21/DC1/host/esx1.myco.int target=vi://administrator@vsphere.local:PASSWORD@ 192.168.0.21/DC1/host/my folder/esx1.myco.int target=vi://administrator@vsphere.local:PASSWORD@ 192.168.0.21/DC1/host/Cluster1/ target=vi://administrator@vsphere.local:PASSWORD@ 192.168.0.21/DC1/host/my folder/Cluster1/ target=vi://administrator@vsphere.local:PASSWORD@ 192.168.0.21/DC1/host/esx1.myco.int/Resources/my_resou rcepool | Specifies the vCenter Server information and target ESX host. Refer to the OVF Tool documentation for details of the syntax of target. PASSWORD in upper case is not the actual vCenter password but is a special term used to make OVF Tool prompt the user for the actual vCenter password value. The prompt will appear during execution of the PowerShell script. This avoids the need to store real password values in this .ini file. Note that target must reference a vCenter host or cluste. Deploying direct to a vSphere host is not supported. In this example, 192.168.0.21 is the IP address of the vCenter host and administrator@vsphere.local is the vCenter administrator username. Note that folder names, host names and cluster names used in the target value are case sensitive. If you are unsure of the value to use for target, you can omit folder names etc. and OVF Tool will then provide a list of possible values for the next level. This allows you to accurately build up the full target specification one level at a time. |
| tlsPortSharingEnabled | 3.1 | tlsPortSharingEnabled=true | Enables the TLS port sharing feature for AirWatch services. |
| uagName | 3.6+ | uagName=uag1 | Optional. Sets hostname of appliance. Normally UAG appliance will perform a DNS reverse lookup on the eth0 IP address to determine the name, or if that is not available, will set it to a default hostname. uagName allows it to be explicitly set at deployments time. |
| v6ip0 | 3.3+ | v6ip0=fe80::250:56ff:feb1:d01a | IPv6 address for NIC0 (onenic, twonic or threenic) Refer to "Network Setting for each NIC" section below. |
| v6ip1 | 3.3+ | v6ip1=fe80::250:56ff:feb1:d01a | IPv6 address for NIC1 (twonic or threenic) Refer to "Network Setting for each NIC" section below. |
| v6ip2 | 3.3+ | v6ip2=fe80::250:56ff:feb1:d01a | IPv6 address for NIC2 (threenic) Refer to "Network Setting for each NIC" section below. |
| v6Prefix0 | 3.3+ | v6ipPrefix0=64 | IPv6 prefix for NIC0 (onenic, twonic or threenic) Refer to "Network Setting for each NIC" section below. |
| v6Prefix1 | 3.3+ | v6ipPrefix1=64 | IPv6 prefix for NIC1 (twonic or threenic) Refer to "Network Setting for each NIC" section below. |
| v6Prefix2 | 3.3+ | v6ipPrefix2=64 | IPv6 prefix for NIC2 (threenic) Refer to "Network Setting for each NIC" section below. |
| [HighAvailability] | virtualIPAddress | 3.4+ | virtualIPAddress=192.168.0.10 | "Floating" virtual IP address for a group of UAG appliances. Used for the High Availability feature. A group of UAG appliances with used with high availability must have NIC 1 (eth0) on the same subnet, and they must all be configured with the same groupID value. |
| groupID | 3.4+ | groupID=1 | Used to group a set of UAG appliances that are on the same subnet. e.g. if UAG1, UAG2 and UAG3 are on the same subnet and all have a groupID value of 1, then high availability feature will work across all 3. A second group could use groupID=2 and a different floating IP address. |
| [Horizon] | authMethods | 2.5+ | authMethods=securid-auth authMethods=radius-auth authMethods=radius-auth authMethods=certificate-auth | Default when not specified is for pass-through authentication. e.g. for RSA SecurID authentication specify: authMethods=securid-auth |
| blastExternalUrl | | blastExternalUrl=https://uag1.horizon.myco.com:443 | URL used by Horizon native clients and HTML Access clients to connect Blast to this UAG appliance. |
| hostEntry1 ... hostEntry99 | 2.8+ | hostEntry1=192.168.0.125 radius-server1.myorg.int hostEntry2=192.168.0.126 rsa-am1.myorg.int hostEntry3=192.168.0.127 s1 s1-alias | A list of 1 or more /etc/hosts file entries to be added to UAG. This is useful if there is a requirement for host name resolution on UAG and DNS is not accessible from UAG. The hosEntry list must start at 1 and the list must be incremental and consecutive. |
| matchWindowsUserName | 2.5+ | matchWindowsUserName=true | Forces subsequent username to be the same username as specified for RADIUS or RSA SecurID authentication. |
| pcoipDisableLegacyCertificate | 3.5+ | pcoipDisableLegacyCertificate=true | A self signed legacy certificate is normally available on TCP port 4172 to allow legacy PCoIP clients to connect. Newer clients use the trusted CA signed certificate when installed on UAG for TCP port 443. Setting this to true disables the presentation of the legacy self-signed certificate. If legacy PCoIP clients do not need to connect then this should be set to true. Scanners that find a self-signed certificate on TCP port 4172 may report a security vulnerability if this is not set to true. |
| pcoipExternalUrl | | pcoipExternalUrl=10.20.30.40:4172 | URL used by Horizon Clients to connect using PCoIP to this UAG appliance. This must include a valid IPv4 address. |
| proxyDestinationUrl | | proxyDestinationUrl=https://cs1.view.myorg.int | URL representing the Horizon backend server such as an individual View Connection Server or a load balnced alias URL representing a group of View Connection Servers. |
| proxyDestinationUrl Thumbprints | | proxyDestinationUrlThumbprints=sha1:3e ef ed c6 86 75 a6 15 ff c8 96 27 5a 4c ee 8e 16 fd 6e d3 | An optional comma separated list of certificate thumbprints of the certificates on each backend View Connection Server. If the Horizon View environment is using trusted CA signed certificates, this setting can be ignored. For self signed or otherwise untrusted certificates enter the thumbprint values preceded by sha1:. |
| proxyPattern | | | Normally not required for Horizon as the default value is usually what is required. Allows an alternative URL pattern to be specified to control the URLs that can be passed to the proxy destination. |
| radiusClassAttributeList | 3.6+ | radiusClassAttributeList=group1
radiusClassAttributeList=group1,group2 | Optional list of RADIUS classes used for authorization within Horizon RADIUS 2FA. If a list is specified, then access will be denied unless the RADIUS server returns a Class Attribute in the Access-Accept with a value that is specified in this list. |
| trustedCert1 ... trustedCert99 | | trustedCert1=c:\temp\CA-Cert-A.pem
trustedCert2=c:\temp\CA-Cert-B.pem | Certificates in PEM format to be added to the certificate trust store for trusting certificates issued by the CAs presented on outgoing SSL/TLS connections. e.g. to Connection Server. |
| tunnelExternalUrl | | tunnelExternalUrl=https://uag1.horizon.myco.com:443 | URL used by Horizon Clients to connect the secure tunnel to this UAG appliance. |
| windowsSSOEnabled | 2.7.2+ | windowsSSOEnabled=true | Used in conjunction with Horizon RADIUS authentication in cases when the RADIUS passcode is the same as the Windows domain user password. This then skips the subsequent domain password prompt to allow single sign-on. |
| [RADIUSAuth] | accountingPort | 2.5+ | accountingPort=1813 | Optional destination UDP port used for sending RADIUS accounting records to the primary RADIUS server. |
| accountingPort_2 | 2.5+ | | For optional secondary server. |
| authPort | 2.5+ | authPort=1812 | Destination UDP port used for sending RADIUS authentication requests to the primary and secondary RADIUS server. |
| authPort_2 | 2.5+ | | For optional secondary server. |
| authType | 2.5+ | authType=PAP | Specify one of PAP, CHAP, MSCHAPv1, or MSCHAPv2. This must match the configuration of the RADIUS server. |
| authType_2 | 2.5+ | | For optional secondary server. |
| hostName | 2.5+ | hostName=192.168.0.100 | Hostname or IP address of the primary RADIUS server. |
| hostname_2 | 2.5+ | | For optional secondary server. |
| numAttempts | 2.5+ | numAttempts=5 | The number of times a RADIUS request will be sent if there was no reply. Default is 3 times. |
| numAttempts_2 | 2.5+ | | For optional secondary server. |
| radiusDisplayHint | 2.5+ | radiusDisplayHint=XXX Token | radiusDisplayHint is a short string that will be included in the client prompt. In this example, the user prompt will be "Enter your XXX Token username and passcode". |
| realmPrefix | 2.5+ | realmPrefix=NorthDomain\ | Optional text inserted ahead of the username before it is passed to the RADIUS server. |
| realmPrefix_2 | 2.5+ | | For optional secondary server. |
| realmSuffix | 2.5+ | realmSuffix=@north.com | Optional text inserted after the username before it is passed to the RADIUS server. |
| realmSuffix_2 | 2.5+ | | For optional secondary server. |
| serverTimeout | 2.5+ | serverTimeout=10 | Timeout in seconds after which a RADIUS request will be resent if there was no reply. Default is 5 seconds. |
| serverTimeout_2 | 2.5+ | | For optional secondary server. |
| [SSLCert] | pemCerts | | pemCerts=C:\Users\admin\My Certs\mycaservercert.pem | Optional SSL Server certificate filename for the user port (TCP 443). This should reference a .PEM format file containing the SSL Server certificate to be deployed onto UAG. The PEM file should contain the SSL Server certifacte and any intermediate and root certificates. If this is omitted, UAG will generate a self-signed SSL server certificate instead. |
| pemPrivKey | | pemPrivKey=C:\Users\admin\My Certs\mycacertrsakey.pem | Filename of the .PEM file containg the RSA private key for the SSL server certificate referenced in pemCerts above. If pemCerts is specified, then pemPrivKey must also be specified. |
| pfxCertAlias | 3.0+ | pfxCertAlias=myalias1 | Optional alias specification used in cases where pfxCerts file contains multiple certificates with private key. It allows specification of which one to use. If there is only one certificate with private key, this setting is not required. |
| pfxCerts | 3.0+ | pfxCerts=C:\Users\admin\My Certs\mycacerts.pfx | If pfxCerts is specified, pemCerts and pemPrivKey are not needed and will be ignored. Specifies a PKCS#12 certificate file normally with .p12 or .pfx extension. The file should contain the SSL server certificate and private key plus any required intermediate certificates. During deployment, the script will prompt for the file password. If the file contains multiple certificates with private key, then pfxCertAlias must be used to specify the alias or friendly name of the certificate required. |
| [SSLCertAdmin] | | 3.2+ | | All the same values as in the [SSLCert] section but specifies the certificate for the Admin UI port (TCP 9443). |
| [SecurIDAuth] | externalHostName | 2.5+ | externalHostName=192.168.0.10 | Set this to the IPv4 address of UAG |
| internalHostName | 2.5+ | internalHostName=192.168.0.10 | Set this to the IPv4 address of UAG |
| serverConfigFile | 2.5+ | serverConfigFile=C:\temp\sdconf.rec | Specifies the sdconf.rec file obtained from RSA Authentication Manager Server. |
| [WebReverseProxy] | authCookie | 2.6+ | authCookie=HZN | Cookie value to track authorized requests. |
| hostEntry1 ... hostEntry99 | 2.8+ | | Refer to the hostEntry description in the Horizon section. |
| instanceId | 2.8+ | instanceId=vIDM | An optional instanceId to name individual WebReverseProxy instances when multiple instances are used. It is not necessary to specify this as this is assigned automatically. |
| loginRedirectURL | 2.6+ | loginRedirectURL=/SAAS/auth/login?dest=%s | URL to redirect request for user login. |
| proxyDestinationUrl | 2.6+ | proxyDestinationUrl=https://vidmserver.example.com | URL representing the backend Web server. |
| proxyDestinationUrl Thumbprints | 2.6+ | proxyDestinationUrlThumbprints=sha1:3e ef ed c6 86 75 a6 15 ff c8 96 27 5a 4c ee 8e 16 fd 6e d3 | An optional comma separated list of certificate thumbprints of the certificates on each backend Web Server. If the Web servers are using trusted CA signed certificates, this setting can be ignored. For self signed or otherwise untrusted certificates enter the thumbprint values preceded by sha1: |
| proxyHostPattern | 3.0+ | proxyHostPattern=airwatch.myco.com | Match on URL FQDN. Used in cases where multiple Web Reverse Proxy instances are used. |
| proxyPattern | 2.6+ | Refer to sample uag10-vidm.ini in the uagdeploy ZIP filebelow. | Specifies the regular expression that matches URIs that should be forwarded to the proxyDestinationUrl. |
| trustedCert1 ... trustedCert99 | | trustedCert1=c:\temp\CA-Cert-A.pem trustedCert2=c:\temp\CA-Cert-B.pem | Certificates in PEM format to be added to the certificate trust store for trusting certificates issued by the CAs presented on outgoing SSL/TLS connections. |
| unSecurePattern | 2.6+ | Refer to sample uag10-vidm.ini in the uagdeploy ZIP filebelow. | Specifies the regular expression that matches URIs that should be forwarded to the proxyDestinationUrl that don't require an authenticated session. |
[WebReverseProxy1] ...[WebReverseProxy99] | | 2.8+ | | With UAG and Access Point 2.8 and newer you can add multiple [WebReverseProxy] sections. The Group Name must have a number appended in the range 1-99 and must be unique. The same values as [WebReverseProxy] are repeated for each additional group. e.g. [WebReverseProxy] ... [WebReverseProxy1] ... [WebReverseProxy99] ... |
Standard SSL, TLS and Cipher Settings
UAG is deployed with the following settings:
- SSL 2.0 disabled
- SSL 3.0 disabled
- TLS 1.0 disabled
- TLS 1.2 enabled
- TLS 1.2 enabled
- TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384
- TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA
- TLS_RSA_WITH_AES_256_CBC_SHA
- TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256
- TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA
- TLS_RSA_WITH_AES_128_CBC_SHA
Managing SSL Server Certificate Files
Deploying a trusted certificate authority (CA) signed SSL server certificate on UAG gives users the assurance that they are connecting to a trusted environment. It also significantly reduces the security risk of a so called man-in-the-middle attack between the user and the service.
If you don't specify a certificate in the [SSLCert] section of the .ini file, UAG will generate a self-signed SSL server certificate. This will work, and can be useful for initial testing, but a self-signed certificate will not be trusted by Horizon and other clients and therefore users will receive a warning when connecting via UAG.
For production environments, it is best to obtain an SSL server certificate from a trusted CA for use on each UAG appliance.
If you have the PEM format files for the SSL server certificate (including any intermediate CA certificates and root CA certificate) you can reference the files in the pemCerts and pemPrivKey values as described later in this section.
From UAG version 3.0, the deployment of the SSL server certificate became much simpler for customers who have their trusted CA certificate and private key in PKCS#12 (.p12 or .pfx) format. From UAG version 3.0, it is no longer necessary to convert the .p12 or .pfx file to PEM format using openssl commands as described below. Instead, you can now just reference the .p12 or .pfx file directly from within the .ini file. In the .INI file, add the following lines.
[SSLCert]
pfxCerts=mycaservercert.pfx
When the script is run, these certificates and private key will be automatically deployed to the new UAG appliance. The referenced pfxCerts file should contain the SSL server certificate with private key, and any intermediate certificates required. During deployment you enter the password associated with the .p12/.pfx file.
If there are multiple certificates with private key, then you can specify which one to use with the pfxCertAlias keyword.
If you have a certificate file with private key and certificate trust chain all in one PKCS#12 format file with either a .p12 or .pfx file extension, then with UAG 3.0 and newer you can use it use it directly without conversion as described above. For UAG and Access Point versions below 3.0 you must convert the PKCS#12 format file into the two PEM format files. PEM format is still supported for UAG 3.0 and newer and can still be needed if you have PEM format files. You can convert from PKCS#12 to the two PEM files with openssl (which you can download from Shining Light Productions - Win32 OpenSSL) by running the following example openssl commands which start with a PKCS#12 file called mycaservercert.pfx.
openssl pkcs12 -in mycaservercert.pfx -nokeys -out mycaservercert.pem
openssl pkcs12 -in mycaservercert.pfx -nodes -nocerts -out mycaservercertkey.pem
openssl rsa -in mycaservercertkey.pem -check -out mycaservercertkeyrsa.pem
Edit mycaservercert.pem and remove any unnecessary certificate entries. It should contain the one SSL server certificate followed by any necessary intermediate CA certificates and root CA certificate.
The pem file may contain text between the certificates such as "Bag Attributes". These lines are not necessary and can be removed. Make sure the .pem file does not contain any single-quote/apostrophe characters. These must be removed.
In the .INI file, add the following lines.
[SSLCert]
pemCerts=mycaservercert.pem
pemPrivKey=mycaservercertkeyrsa.pem
When the script is run, these certificates and private key will be automatically deployed to the new UAG appliance. The private key PEM file should be deleted from the Windows machine once UAG has been deployed.
If you find that the deployment of UAG works when you don't specify the PEM files (i.e. for UAG to use a self-signed SSL server certificate) but fails when you supply your own certificate as described above, then follow these steps. It could be caused by a missing intermediate or root certificate in your specified PEM file.
- Log into the console of UAG as user root and enter the root password you chose when you ran the uagdeploy.ps1 script.
- Using an editor such as vi, look at the log file /opt/vmware/gateway/logs/admin.log
- If you see entries saying "Unable to build the certification path" and "No issuer certificate for certificate in certification path found" it means that you having missing intermediate or root certificate entries in the PEM or .p12/.pfx file specified for.
![ap-missing intermediate cert.png]()
- To correct this, you must make sure that any required intermediate certificates and/or root certificate are present in the PEM file and then re-run the uagdeploy.ps1 script.
Network Setting for each NIC (UAG 3.3 and newer)
Case
| IPv4
| IPv6
| ipMode0
| ip0 | netmask0
| v6ip0
| v6Prefix0
| PowerShell [General] Settings
|
|---|
| 1 | | | DHCPV4 | | | | | ipMode0=DHCPV4 |
| 2 | | | DHCPV4+DHCPV6 | | | | | None required as this is the default. |
| 3 | | | DHCPV4+AUTOV6 | | | | | ipMode0=DHCPV4+AUTOV6 |
| 4 | | | DHCPV4+STATICV6 | | | fe80::250:56ff:feb1:e800 | 64 | ipMode0=DHCPV4+STATICV6
v6ip0=fe80::250:56ff:feb1:d01a v6ipprefix0=64 |
| 5 | | | STATICV4 | 192.168.0.128 | 255.255.255.0 | | | ip0=192.168.0.128 netmask0=255.255.255.0 |
| 6 | | | STATICV4+DHCPV6 | 192.168.0.128 | 255.255.255.0 | | | ipMode0=STATICV4+DHCPV6
ip0=192.168.0.128 netmask0=255.255.255.0 |
| 7 | | | STATICV4+AUTOV6 | 192.168.0.128 | 255.255.255.0 | | | ipMode0=STATICV4+AUTOV6 ip0=192.168.0.128 netmask0=255.255.255.0 |
| 8 | | | STATICV4+STATICV6 | 192.168.0.128 | 255.255.255.0 | fe80::250:56ff:feb1:e800 | 64 | ip0=192.168.0.128 netmask0=255.255.255.0 v6ip0=fe80::250:56ff:feb1:d01a v6ipprefix0=64 |
| 9 | | | DHCPV6 | | | | | ipMode0=DHCPV6 |
| 10 | | | AUTOV6 | | | | | ipMode0=AUTOV6 |
| 11 | | | STATICV6 | | | fe80::250:56ff:feb1:e800 | 64 | v6ip0=fe80::250:56ff:feb1:d01a v6ipprefix0=64 |
The table above shows the 11 IPv4 and IPv6 combination modes supported in UAG 3.3 and newer for each NIC with examples for the first NIC (eth0). The same settings can be applied to the second (eth1) and third (eth2) NICs as required.
NIC0 - eth0 - ipMode0, ip0, netmask0, vcip0, v6Prefix0.
NIC1 - eth1 - ipMode1, ip1, netmask1, vcip1, v6Prefix1.
NIC2 - eth2 - ipMode2, ip2, netmask2, vcip2, v6Prefix2.
Troubleshooting Deployment Problems
1. I get a security warning about running scripts downloaded from the Internet
Verify that the PowerShell script is the script you intend to run, and then from the PowerShell console, run the command:
unblock-file .\uagdeploy.ps1
2. I get an error saying "ovftool command not found".
Make sure you have installed the OVF Tool software on your Windows machine and that it is installed in the location expected by the script. OVF Tool Download.
3. I get an error saying "Invalid Network in property netmask0" or "Cannot initialize property 'netmask0'. Network 'VM Network' has no associated network protocol profile"
The message may state netmask0, netmask1 or netmask2, Check that a value has been set in the .INI file for each of the three networks (netInternet, netManagementNetwork and netBackendNetwork),Also check that a vSphere Network Protocol Profile has been associated with every referenced network name. This specifies network settings such as IPv4 subnet mask, gateway etc. so make sure the associated Network Protocol Profile has correct values for each of the settings.
4. I get a warning message about the operating system identifier being not supported (id: 85)
The full message is: The specified operating system identifier 'SUSE Linux Enterprise Server 12.0 64bit' (id:85) is not supported on the selected host. It will be mapped to the following OS identifier: 'Other Linux (64-bit)'.
This can be ignored. It is mapped to a supported operating system automatically.
5. How do I configure UAG for RSA SecurID authentication?
Add the following two lines to the [Horizon] section of your .ini file:
authMethods=securid-auth
matchWindowsUserName=true
Add a new section at the bottom of your .ini file containing:
[SecurIDAuth]
serverConfigFile=C:\temp\sdconf.rec
externalHostName=192.168.0.90
internalHostName=192.168.0.90
The IP addresses should both be set to the IP address of UAG. The sdconf.rec file is obtained from RSA Authentication Manager (RSA-AM) which should be fully configured according to RSA documentation.
Make sure you are using UAG 2.5 or newer and that the RSA-AM server is accessible on the network from UAG.
If there is a firewall between UAG and your RSA Authentication Manager server, make sure it isn't blocking the communication. This is normally UDP 5500 from UAG to RSA-AM and the reply traffic.
Rerun uagdeploy PowerShell command to redeploy your UAG configured for RSA SecurID. Refer to VMware UAG RSA SecurID Authentication Setup Video for a full step-by-step description of this setup. Also Refer to the RSA Ready Certification Document for VMware UAG.
Note that when RSA SecurID is configured in the .INI file, then after deployment when UAG first starts up, it performs a check against RSA-AM. If RSA-AM is not available, or if DNS cannot resolve the hostname of RSA-AM referenced in the sdconf.rec file, or if a firewall is blocking the UDP port for this communication, this startup will fail. When this initial handshake fails, the RSA SecurID component on UAG remains disabled. You can open up the sdconf.rec file with a text editor and although it is a binary file, you can see the RSA-AM hostname(s). If you suspect a communication failure, you can log in to the console of UAG as root and run nslookup with that hostname to verify that it can be resolved. Once you have resolved any environment issues, just rerun the PowerShell command to redeploy UAG.
If you need to redeploy UAG with the PowerShell command when it was previously configured for RSA SecurID, then you must first "clear node secret" on RSA-AM so that trust can be re-established.
6. How do I configure UAG for RADIUS authentication?
Add the following two lines to the [Horizon] section of your .ini file:
authMethods=radius-auth
matchWindowsUserName=true
Add a new section at the bottom of your .ini file containing:
[RADIUSAuth]
hostName=192.168.0.100
authType=PAP
authPort=1812
radiusDisplayHint=XXX Token
For more information on these and other settings, refer to the sample uag4-radius.ini file in the latest uagdeploy ZIP file below. Also refer to the [RADIUSAuth] descriptions in the table above.
Make sure you are using UAG 2.5 or newer and that the RADIUS server is accessible on the network from UAG.
If there is a firewall between UAG and your RADIUS server, make sure it isn't blocking the communication. This is normally UDP 1812 from UAG to to the RADIUS server and the reply traffic.
Rerun uagdeploy PowerShell command to redeploy your UAG configured for RADIUS.
Note that when RADIUS is configured in the .INI file, then after deployment when UAG first starts up, it performs a check against the configured RADIUS server. If the server is not available or if a firewall is blocking communication, this startup will fail.
7. How do I configure UAG for Client Device certificate authentication?
Add the following line to the [Horizon] section of your .ini file:
authMethods=certificate-auth && sp-auth
Add a new section at the bottom of your .ini file containing:
[CertificateAuth]
pemCerts=C:\Users\Administrator\Documents\SSL\CA Certs\north-ca-256.cer
The .cer file is the public certificate authority (CA) certificate that was used to issue required client device certificates.
A client device certificate must be installed in the user or computer certificate store on the system where the Windows Horizon Client is installed. This proves the identity of the client computer. Unless the client supplies a valid certificate issued by this CA, then UAG will reject the connection with an error as shown below.
![NoCertError.png]()
Client devices that do supply a valid certificate will get the normal user authentication prompt.
This feature is typically used to ensure that only Windows domain joined client computers can connect to desktops and applications via UAG. The client device certificates can be managed automatically as part of a Windows client machine enrolment policy.
For the Cryptographic Service Provider (CSP) specified in the certificate issuing template, use the "Microsoft Enhanced RSA and AES Cryptographic Provider". This supports SHA256 certificates and TLS 1.2. SHA1 is generally now considered too weak for authentication purposes so you should use SHA256.
![CSPSelection.png]()
For Windows to be able to use the certificate for client authentication purposes, the user on the client computer must have read access to the certificate private key. It is not necessary or desirable to make the private key exportable. The Key Usage of the certificate must include "Digital Signature" and "Key Encipherment (a0)".
8. I get an error saying "Locator does not refer to an object"
This means that the target= value (used by vSphere OVF Tool) is not correct for your vCenter environment. Refer to the table above for examples of the target format used to refer to a vCenter host or cluster. If you are not sure of the names to use, you can start with the top level object, e.g. by specifying:
target=vi://administrator@vsphere.local:PASSWORD@192.168.0.21/
This will then show a list of possible names to use at the next level. You can then expand it, one level at a time based on this list.
target=vi://administrator@vsphere.local:PASSWORD@192.168.0.21/Datacenter1/
target=vi://administrator@vsphere.local:PASSWORD@192.168.0.21/Datacenter1/host
target=vi://administrator@vsphere.local:PASSWORD@192.168.0.21/Datacenter1/host/Cluster1/
or
target=vi://administrator@vsphere.local:PASSWORD@192.168.0.21/Datacenter1/host/esxhost1
or
target=vi://administrator@vsphere.local:PASSWORD@192.168.0.21/Datacenter1/host/my folder/esxhost1
Note that folder names, host names and cluster names used in the target value are case sensitive.
9. I get an error saying "Transfer failed and Error: failed to send http data"
![OVFToolXFFailed.png]()
This will happen if your target entry references an ESXi hostname that cannot be resolved by your local computer.
This will also happen if you are using a version of vSphere OVF Tool that is not compatible with the version of vSphere and vCenter you are using. I have seen this error after upgrading vSphere to version 6.5 where I was using an older 4.1.0 version of OVF Tool which is not compatible. In this case, the solution was to upgrade to OVF Tool version 4.2.0 or newer - see OVF Tool Software and Documentation.
For any questions on UAG, post a message on the discussion section of the Horizon community forum.
