Using PowerShell to Deploy VMware Unified Access Gateway

Version 85

    By Mark Benson, Senior Architect and Senior Staff Engineer, End-User-Computing CTO Office, VMware

    Introduction

    Updated September 2017 for version 3.1

     

    From version 2.9 the appliance is is now called Unified Access Gateway (UAG) instead of the old name of Access Point. It's the same, just a different name.

     

    In September 2015, I posted A Technical Introduction to Access Point for Secure Remote Access article. Unified Access Gateway (UAG), formerly known as Access Point, is a VMware virtual appliance which is used with VMware Horizon (View) and Horizon Air (DaaS). In that article I mentioned the ability to perform a scripted deployment of an Access Point virtual appliance using VMware OVF Tool in order to perform a repeatable deployment where all settings can be applied in a way that allows UAG to be production ready on first boot. This procedure is described in the document Deploying and Configuring Access Point.

     

    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 Horizon environment need a much simpler 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 sample PowerShell script that can be used to deploy Access Point 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 Access Point according the procedure in the document Deploying and Configuring Access Point . 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.

     

    What are the requirements for deploying UAG appliances using this script?

    1. For Access Point itself, a vSphere ESX host with a vCenter Server is needed. Decide on the vSphere datastore to be used and the Network name to be used. A vSphere Network Protocol Profile 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 Access Point uses these values so make sure the values are correct.
    2. 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.
    3. 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-access-point-2.9.0.0-5178136_OVF10.ova. Refer to VMware Product Interoperability Matrixes to determine the version to download.
    • Download the correct uagdeploy or apdeploy ZIP file attached below and extract the files into a folder on your Windows machine.
    • 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 Access Point 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 ZIP file 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 NameValueUAG or AP Version Required (if applicable)ExampleDescription
    [CertificateAuth]pemCertspemCerts=C:\Users\Administrator\SSL\north-ca-256.cerUsed 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.
    [General]defaultGateway3.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.

    deploymentOptiondeploymentOption=onenicUAG can be created with either one, two or three network interface cards (NICs). Either specify onenic, twonic or threenic. The default is onenic.
    diskMode2.8+diskMode=thinOVF Tool vSphere Disk Mode. Sets the disk provision mode. Refer to the OVF Tool documentation for further options. Default is thick.
    dnsdns=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.

    dsds=Local Disk 1Datastore name which the appliance will be deployed to.
    folderfolder=My VM Folder/My Sub FolderDeploys the appliance in the named folder. Folders in vCenter are shown under VMs and Templates. The folder specified must exist before deployment.
    forwardrules2.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.

    honorCipherOrder2.7.2+honorCipherOrder=trueDefault 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.
    ip0ip0=192.168.0.10IPv4 address for NIC0 (onenic, twonic or threenic)
    ip1ip1=192.168.0.11IPv4 address for NIC1 (twonic or threenic)
    ip2ip2=192.168.0.12IPv4 address for NIC2 (threenic)
    namename=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.

    netInternetnetInternet=VM NetworkThe name of the vSphere Network for the UAG primary network
    netManagementNetworknetManagementNetwork=VM NetworkThe name of the vSphere Network for the UAG management interface network.
    netBackendNetworknetBackendNetwork=VM NetworkThe name of the vSphere Network for the UAG backend network.
    routes02.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.

    routes12.7.2+List of static routes for NIC1.
    routes22.7.2+List of static routes for NIC2.
    sessionTimeout2.7.2+sessionTimeout=39600000Maximum 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.
    sourcesource=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.

    syslogUrlsyslogUrl=syslog://server.example.com:514Optional 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/Cluster1/

    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.

    tlsPortSharingEnabled3.1tlsPortSharingEnabled=trueEnables the TLS port sharing feature for AirWatch services.
    [Horizon]authMethods2.5+

    authMethods=securid-auth && sp-auth

    authMethods=radius-auth && sp-auth

     

    authMethods=radius-auth

    authMethods=certificate-auth && sp-auth

    Default when not specified is for pass-through authentication.

     

    e.g. for RSA SecurID authentication specify:

    authMethods=securid-auth && sp-auth

    blastExternalUrlblastExternalUrl=https://uag1.horizon.myco.com:443URL used by HTML Access Clients to connect 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.
    matchWindowsUserName2.5+matchWindowsUserName=trueForces subsequent username to be the same username as specified for RADIUS or RSA SecurID authentication.
    pcoipExternalUrlpcoipExtenalUrl=10.20.30.40:4172URL used by Horizon Clients to connect using PCoIP to this UAG appliance. This must include a valid IPv4 address.
    proxyDestinationUrlproxyDestinationUrl=https://cs1.view.myorg.intURL 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 d3An 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:.
    proxyPatternNormally 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.
    tunnelExternalUrltunnelExternalUrl=https://uag1.horizon.myco.com:443URL used by Horizon Clients to connect the secure tunnel to this UAG appliance.
    windowsSSOEnabled2.7.2+windowsSSOEnabled=trueUsed 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=1813Optional destination UDP port used for sending RADIUS accounting records to the primary RADIUS server.
    accountingPort_22.5+For optional secondary server.
    authPort2.5+authPort=1812Destination UDP port used for sending RADIUS authentication requests to the primary and secondary RADIUS server.
    authPort_22.5+For optional secondary server.
    authType2.5+authType=PAPSpecify one of PAP, CHAP, MSCHAPv1, or MSCHAPv2. This must match the configuration of the RADIUS server.
    authType_22.5+For optional secondary server.
    hostName2.5+hostName=192.168.0.100Hostname or IP address of the primary RADIUS server.
    hostname_22.5+For optional secondary server.
    numAttempts2.5+numAttempts=5The number of times a RADIUS request will be sent if there was no reply. Default is 3 times.
    numAttempts_22.5+For optional secondary server.
    radiusDisplayHint2.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".

    realmPrefix2.5+realmPrefix=NorthDomain\Optional text inserted ahead of the username before it is passed to the RADIUS server.
    realmPrefix_22.5+For optional secondary server.
    realmSuffix2.5+realmSuffix=@north.comOptional text inserted after the username before it is passed to the RADIUS server.
    realmSuffix_22.5+For optional secondary server.
    serverTimeout2.5+serverTimeout=10Timeout in seconds after which a RADIUS request will be resent if there was no reply. Default is 5 seconds.
    serverTimeout_22.5+For optional secondary server.
    [SSLCert]pemCertspemCerts=C:\Users\admin\My Certs\mycaservercert.pemOptional SSL Server certificate filename. 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.
    pemPrivKeypemPrivKey=C:\Users\admin\My Certs\mycacertrsakey.pemFilename 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.
    pfxCertAlias3.0+pfxCertAlias=myalias1Optional 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.
    pfxCerts3.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.

    [SecurIDAuth]externalHostName2.5+externalHostName=192.168.0.10Set this to the IPv4 address of UAG
    internalHostName2.5+internalHostName=192.168.0.10Set this to the IPv4 address of UAG
    serverConfigFile2.5+serverConfigFile=C:\temp\sdconf.recSpecifies the sdconf.rec file obtained from RSA Authentication Manager Server.
    [WebReverseProxy]authCookie2.6+authCookie=HZNCookie value to track authorized requests.

    hostEntry1

    ...

    hostEntry99

    2.8+Refer to the hostEntry description in the Horizon section.
    instanceId2.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.

    loginRedirectURL2.6+loginRedirectURL=/SAAS/auth/login?dest=%sURL to redirect request for user login.
    proxyDestinationUrl2.6+proxyDestinationUrl=https://vidmserver.example.comURL 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 d3An 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:
    proxyHostPattern3.0+proxyHostPattern=airwatch.myco.comMatch on URL FQDN. Used in cases where multiple Web Reverse Proxy instances are used.
    proxyPattern2.6+Refer to sample uag10-vidm.ini in the uagdeploy ZIP file below.

    Specifies the regular expression that matches

    URIs that should be forwarded to the proxyDestinationUrl.

    unSecurePattern2.6+Refer to sample uag10-vidm.ini in the uagdeploy ZIP file below.

    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.

     

    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.

     

    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 && sp-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 && sp-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.

     

     

     

     

    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

     

    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.