Using PowerShell to Deploy VMware Unified Access Gateway

Using PowerShell to Deploy VMware Unified Access Gateway

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

Introduction

For more information on Unified Access Gateway (UAG) deployment and configuration covering UAG 3.9, also see the tutorial in this VMware Knowledge Base article.


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?

  1. 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.
  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. Note that if you are running OVFTool version 4.4.0 and possibly newer versions, you must omit the :PASSWORD part in the target= value in the PowerShell .ini file otherwise the vCenter password entered while running uagdeploy.ps1 will not be accepted. e.g. instead use the form target=vi://administrator@vsphere.local@192.168.0.21/DC1/host/esx1.example.int. :PASSWORD in the target line works with OVFTool version 4.2.0.

 

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 uag.ini (or ap.ini with older Access Point versions). 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@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.
  crlLocation   crlLocation=http://crl.myca.com CRL Location
  enableCertCRL   enableCertCRL=true Use CRL from Certificates
  enableCertRevocation   enableCertRevocation=true Enable Cert revocation
  enableOCSP 3.9+ enableOCSP=true Enable OCSP
  ocspURL 3.9+ ocspURL=https://ocsp.example.com OCSP server
[General] adminDisclaimerText 3.10+ adminDisclaimerText=x y z Specifies a text message to be shown to an admin when logging on to the UAG Admin UI.
  adminPasswordExpirationDays 3.2+ adminPasswordExpirationDays=100 Number of days after which the admin user password will expire.
  cipherSuites 3.3 cipherSuites=TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256,
TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,
TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256,
TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384
List of cipher setting for HTTPS/TLS. The list is comma separated and all on one line.
  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, threenic-large, onenic-XL, twonic-XL, threenic-XL. The large options deploy UAG as 4 vCPU 8GB RAM and the extra-large (XL) options deploy UAG as 8 vCPU and 32 GB RAM.
  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.

  sshEnabled 3.5+ sshEnabled=true Default is false. Enables console ssh access on TCP port 22. This is not recommended for production deployments. On vSphere deployments it is better to use vCenter console access instead of ssh.
  sshKeyAccessEnabled 3.9+ sshKeyAccessEnabled=true Enables ssh key access login.
  sshPasswordAccessEnabled 3.9+ sshPasswordAccessEnabled=false Allows password access for ssh to be disabled when sshEnabled=true. This is for cases where ssh key access only is required.
  sshPublicKey1
...
sshPublicKey99
3.9+ sshPublicKey1=c:\temp\myssh_public.key ssh public keys to be configured on UAG when sshEnabled=true and sshKeyAccessEnabled=true
  ssl30Enabled 3.3 ssl30Enabled=false Enables SSL 3.0. Not recommended. Default is false.
  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@

192.168.0.21/DC1/host/esx1.myco.int

 

target=vi://administrator@vsphere.local@

192.168.0.21/DC1/host/my folder/esx1.myco.int

 

target=vi://administrator@vsphere.local@

192.168.0.21/DC1/host/Cluster1/

 

target=vi://administrator@vsphere.local@

192.168.0.21/DC1/host/my folder/Cluster1/

 

target=vi://administrator@vsphere.local@

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.

 

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.

  tls10Enabled 3.3 tls10Enabled=false Enables TLS 1.0. Set to true or false. Default is
  tls11Enabled 3.3 tls11Enabled=false Enables TLS 1.1. Set to true or false.
  tls12Enabled 3.3 tls12Enabled=true Enables TLS 1.2. Set to true or false.
  tls13Enabled 3.10+ tls13Enabled=true Enables TLS 1.3. Set to true or false.
  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

 

authMethods=saml-auth && sp-auth

authMethods=saml-auth

Default when not specified is for pass-through authentication.

 

e.g. for RSA SecurID authentication specify:

authMethods=securid-auth

 

saml-auth is supported from UAG 3.8+.

  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.
  idpEntityID 3.8+ idpEntityID=http://www.example.com Used when authMethods contains saml-auth. This is the entityID of the 3rd party SAML IdP.
  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.
  securityHeaders   securityHeaders={"Cache-Control":"no-cache,no-store,must-revalidate,pre-check=0,post-check=0,max-age=0,s-maxage=0","Pragma":"no-cache"} Adds optional HTTP response headers in cases where they are not present in responses from the proxyDestinationUrl server.
 

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.

[IDPExternalMetadata1]
...[IDPExternalMetadata99]
metadataXmlFile 3.8+ metadataXmlFile=c:\temp\myIDP.xml SAML 2.0 Identity Provider (IdP) Metadata file obtained from the 3rd party IdP.
  forceAuthN 3.8+ forceAuthN=true Used with 3rd party SAML IdP to add forceAuthN to the SAML request to the IdP. This forces authentication to occur by the IdP even if the previous authentication session is still valid. Default is false.
[OCSPSigningCertificates] ocspSigningCert1
...

ocspSigningCert99

3.9+ ocspSigningCert=c:\temp\mysigningcert.pem Issuer certificate for OCSP URL trust.
[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 file below.

Specifies the regular expression that matches

URIs that should be forwarded to the proxyDestinationUrl.

  securityHeaders   securityHeaders={"Cache-Control":"no-cache,no-store,must-revalidate,pre-check=0,post-check=0,max-age=0,s-maxage=0","Pragma":"no-cache"} Adds optional HTTP response headers in cases where they are not present in responses from the proxyDestinationUrl server.
 

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 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]

...

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

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 :smileycheck: :smileyx: DHCPV4         ipMode0=DHCPV4
2 :smileycheck: :smileycheck: DHCPV4+DHCPV6         None required as this is the default.
3 :smileycheck: :smileycheck: DHCPV4+AUTOV6         ipMode0=DHCPV4+AUTOV6
4 :smileycheck: :smileycheck: DHCPV4+STATICV6     fe80::250:56ff:feb1:e800 64

ipMode0=DHCPV4+STATICV6
v6ip0=fe80::250:56ff:feb1:d01a

v6ipprefix0=64

5 :smileycheck: :smileyx: STATICV4 192.168.0.128 255.255.255.0    

ip0=192.168.0.128

netmask0=255.255.255.0

6 :smileycheck: :smileycheck: STATICV4+DHCPV6 192.168.0.128 255.255.255.0    

ipMode0=STATICV4+DHCPV6
ip0=192.168.0.128

netmask0=255.255.255.0

7 :smileycheck: :smileycheck: STATICV4+AUTOV6 192.168.0.128 255.255.255.0    

ipMode0=STATICV4+AUTOV6

ip0=192.168.0.128

netmask0=255.255.255.0

8 :smileycheck: :smileycheck: 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 :smileyx: :smileycheck: DHCPV6         ipMode0=DHCPV6
10 :smileyx: :smileycheck: AUTOV6         ipMode0=AUTOV6
11 :smileyx: :smileycheck: 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@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@192.168.0.21/Datacenter1/

target=vi://administrator@vsphere.local@192.168.0.21/Datacenter1/host

target=vi://administrator@vsphere.local@192.168.0.21/Datacenter1/host/Cluster1/

or

target=vi://administrator@vsphere.local@192.168.0.21/Datacenter1/host/esxhost1

or

target=vi://administrator@vsphere.local@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.

Attachments
Comments

Looking for the ap-deploy-27.zip files to download.  The AP 2.7 documentation pointed me here, but I can't find them.  Can you help?

The script didn't change for Access Point 2.7 so you can just use the latest (apdeploy-260). Make sure your source= line in the .ini file refers to the 2.7 .OVA file.

Hi Mark,

We've been having problems configuring RSA integration despite following your excellent Video VMware Access Point RSA SecurID Authentication Setup on Vimeo‌ . Put simply, the appliance will not start correctly when we specify the inclusion of the sdconf.rec file (having extracted it directly from the zip file from the Auth Manager). If we configure the INI file with everything else apart from the referenced file, the appliance starts up, but understandably doesn't perform auth.

GSS seem to be scratching their heads too, even stating that SecurID needed to be configured on the connection servers and that I should be using the Fling for the Access Point OVA Deployment Utility which doesn't cater for RSA integration.

I even tried sending the JSON requests directly to a non RSA deployed appliance, but this fails too. Seems like a bit of a black art to get the appliance working properly.

Best regards

Andrew

Hi Andrew.

As you may know, VMware does not support any Fling for production use. The documented method is to use this PowerShell script, which as you say also supports RSA SecurID setup.

You can either set up RSA SecurID authentication on Horizon Connection Server or on Access Point. I'm sorry if you were wrongly advised.

We should be able to resolve your problem.

When you specify the RSA sdconf.rec file when doing an Access Point deployment, it does result in Access Point performing a check at startup. This involves communicating with RSA Authentication Manager Server based on the values within sdconf.rec and the IP addresses you specified in the .ini file. If this check fails, then Access Point will not startup correctly. This check must pass.

Assuming that you are using the 2.5.x version of Access Point as shown in the video, I think there are 4 possible reasons why it is failing.

1. You have the IP addresses incorrectly set in the .ini file. If this is a 1 NIC setup then this will be the IP address of Access Point. You specify this IP address twice in the .ini file.

2. RSA Authentication Manager is not accessible from Access Point (at the UDP/IP layer) at startup time. It uses UDP. I know if RSA Authentication Manager is unavailable or a firewall is blocking that two-way UDP traffic it fails. Monitoring network traffic may help here.

3. RSA Authentication Manager is not set up correctly and is rejecting the check. You can usually find this issue by running the live logging on RSA Authentication Manager and looking for errors. You may need to clear node secret on RSA Authentication Manager.

4. Something is wrong with sdconf.rec.

Look at these 4 things. If it is still failing, "private message" me your .INI file.

Mark

Hi Mark,

Thanks very much for your response. Item #2 was indeed the culprit here and having discussed the submitted FW rules with the security team, they admitted they had failed to apply one of the UDP ports which continually resulted in the deployment failure.

I hope others find these pointers as useful as I have in getting the access point into production using 2FA.

Kind regards

Andrew

Hi Andrew,

Thanks for posting back. I'm glad you've fixed your firewall issue and that Access Point SecurID two-factor authentication is now working for you.

I've just updated this document to emphasise the need for a firewall to not block the RSA SecurID communication between Access Point and RSA Authentication manager.

Note also, that if you redeploy Access Point at any time, you should "clear node secret" on RSA AM so that the trust can be re-established.

Mark

Hi Mark,

Can I configure the Access Point for Horizon to use Radius authentication but also accept passthrough/SAML when a user initiates a session a session through the Identity Manager portal? If I configure Radius on the Access Point the user always needs to enter 2-factor authentication, even when the user already authenticated through Identity Manager with 2-factor. vIDM is using another Access Point BTW.

You can configure Horizon View for RADIUS in which case Access Point can be configured for pass-thru authentication (the default setup). In this case it will pass through RADIUS and SAML requests to Connection Server.

As you say, if you configure Access Point to require RADIUS authentication, then it will do this always, and will not pass-thru SAML.

Another option is to have one Access Point configured for RADIUS and connecting to a Connection Server configured for password. Then have another Access Point configured for pass-thru connecting to a Connection Server configured for SAML.

Mark

Thanks, that's what I thought.

Hi Mark,

thank you for your script. Just a question. The ver. 2.7+ of AP can have more than an edge service (a.k.a I can configure on the same appliance the web reverse proxy role and the other vs a Connection Server). It's correct? If this is correct, how can use this script to accomplish his goal?

Thank you very much

Francesco

Yes. To use multiple "Edge Services" on Access Point, just specify multiple sections in your .INI file. e.g.

[Horizon]

...

[WebReverseProxy]

...

Make sure you use the script in apdeploy-272-v2.zip or newer.

Mark

I'm using the apdeploy-272-v2, and the username that it uses is Administrator%40vsphere.local instead of a Administrator@vsphere.local, and the deployment obviously fails.

Any ideas?

Will

Although VMware OVF Tool displays the username as Administrator%40vsphere.local it will actually use the name you specified in the .INI file (i.e. Administrator@vsphere.local). If you look at the PowerShell screen shot above, you'll see the same thing but it works fine. OVF Tool does this because it uses a valid URI format where it just displays @ as %40. A browser URL bar will do the same.

If the command is not working for you, it is probably for some other reason.

Make sure your target= value is correct. Set it to something like:

target=vi://administrator@vsphere.local:PASSWORD@192.168.0.21/Datacenter1/host/esx1.myco.int

PASSWORD in upper case will cause OVF Tool to prompt for the real password so don't put the real password in the .INI file. The IP address 192.168.0.21 is the vCenter Server address. If you are not sure of the host or cluster name after the IP address, just put:

target=vi://administrator@vsphere.local:PASSWORD@192.168.0.21/

It will fail but will show you the possible completions which you can then add one at a time to the target line to complete it.

If it is failing for some other reason, send me a private message and include your .ini file. Also be specific about what error you see or what the symptoms are and I should then be able to help to resolve this.

Mark

There is no ap4-radius.ini included in the zip-file. Can you provide an example of configuring radius using powershell and an ini-file?

Oh sorry, it was missing. I've now added it in apdeploy-272-v3.zip and documented all the RADIUS settings in the table above. Thanks for pointing that out!

Thanks, just tested it. When deploying it only asks a shared secret for the first RADIUS-host, not for the second, is that correct?

Also checked the configuration, the second RADIUS host isn't in the configuration, Added enabledAux=true to the config file, but that doesn't work as well. So it seems that deploying it with the INI file only works with 1 RADIUS server?

apdeploy-272-v4.zip adds supports for a secondary RADIUS server. Email me if you have any issues with this.

Hi Mark,

Thank you for the awesome script, really takes away a lot of configuration work. I do have one question however: the configuration settings that I specify within the [Horizon] part and the [WebReverseProxy] part don't seem to get populated in the VM once it has been deployed. I've played around and put those two variables at different places in the .ini-file, but still the deployment won't set these values when the AP is being deployed. Do you have any idea what could be causing this?

Thanks.

I've shuffled the [Horizon] and [WebReverseProxy] again and retried redeploying several times, but unfortunately still no bananas. I was wondering: are there any other users who are experiencing this same symptom? Mark, if it might be a misconfiguration, what could it be?

Sure - send me a private message with your .ini file and I'll let you know what the issue is. Make sure your target is referencing the vCenter server and use the sample .ini files to get the structure right.

Hi,

do you know if there is an issue with the new Access Point Appliance version 2.7.2 and RADIUS with SMSPASSCODE? If I use the Access Point Appliance 2.5.1 I can logon with my username and password and then get a message with the passcode. After entering the passcode I can start my desktop session. But when I deploy the Access Point in version 2.7.2 with the same settings (windowsSSOEnabled=true and matchWindowsUserName=true) there is a logon loop. After login with username/password and entering the passcode there is a now a dialog to enter username and password again. It does not help to enter the username and password or passcode again. Is this a software bug?

Thanks!

Verify you are using the current apdeploy-272-v4.zip . Also, you can send me a private message with your .INI file and I'll take a look.

Also, try with windowsSSOEnabled=false.

If this isn't working, you should raise a support request with VMware.

Mark

Hi Mark,

Thanks for your feedback. I have changed the settings to windowsSSOEnabled=false and get the same results. It still does not work with version 2.7.2. I have been using the current apdeploy-272-v4.zip script. I will raise a vmware support request.

Hi markbenson,

I'm getting issues when deploying due to a vSphere Network Name error...however this Port Group definitely exists. Additionally I don't believe the log file is being generated by the script when looking to investigate:

Error: Unexpected option: --net:Internet=Portgroup Name

Completed with errors

Access Point deployment failed. Further information may be found in the log file log-appliance_hostname.txt


The error comes back pretty quickly, so I'm not sure this error is valid, and when I print $logfile it says that the logfile does not exist. In the script I see:

$logfile="log-$apName.txt"

Remove-item -path $logfile -ErrorAction SilentlyContinue


..tried commenting out the Remove-item portion but it still looks as though nothing is being generated


Any pointers would be appreciated!


Thanks


It will be a configuration issue with the .INI file. I've seen this before. As you've noticed, it won't be getting as far as validating the network name or running the OVF Tool command and creating a log file. It fails earlier.

This is usually caused because the .INI file doesn't correctly reference each network.

netInternet=VM Network

netManagementNetwork=VM Network

netBackendNetwork=VM Network

I've seen this error if there are bad characters on the network name lines. e/g/ spaces or tab characters after the names. Check these very carefully. Perhaps use NotePad++ to see if there are any bad characters in these lines. Alternatively send me (by private message) your .INI file, and I'll let you know what is wrong. Look at the sample .INI files supplied, because we know all of those work.

Let us know what it was.

Thanks Mark,

It took 2 sets of eyes, but you are correct..a simple blank space after the ip0=x.x.x.x line caused this error.

The deployment succeeded after that, so thanks for your help!

I had an additional question on setting TLS levels and ciphers. I can see from the script, you can set honorCipherOrder...is the only way to set a custom TLS level and supported cipher to use the REST API?

I'm using the 2 nic configuration and setting static routes for ip1 in the ini file. I noticed that the default route is pointing to eth1 rather than eth0.  What needs to be in the ini file for eth0 to be the default route?

Good. Glad that fixed it for you.

I don't recommend changing TLS/SSL versions and ciphers as these get tested carefully to maximize both security and client compatibility. Access Point achieves a straight "A" rating from a Qualys SSL scan with the default settings. If you really want to change the settings, you can do this by altering the sample PowerShell script for SSL TLS versions and for ciphers. However, my advice is don't.

Mark

It's probably that you have a default gateway setup in vSphere for the network protocol profile associated with the vSphere network for your second NIC. There can only be one default gateway, so if you just have a default gateway for the first network profile it will just use that and associate it with eth0. Check the vSphere docs too.

You can always add specific routes using routes0 routes1 in your .ini file.

Mark

Hi Mark,

When will this article gets updated to Access Point 2.8?

Ivo

I've just updated it today in readiness for Access Point 2.8 support with each product. Refer to the VMware Product Interoperability Matrixes information for details of product compatibility.

Instead of using target=vi://administrator@vsphere.local can I use target=vi://DOMAIN\USER

The script is failing as it's resolving the domain name to a DC then trying and failing to connect on port 443 which obviously won't be open.

Access Point 2.8 is still missing from the matrix.

I've just looked at the OVF Tool Documentation and it says that for URLs, the backslash character must be escaped by using %5c instead.

Encoding Special Characters in URL Locators

When you use URIs as locators, you must escape special characters using % followed by their ASCII hex value.

For instance, if you use a “@” in your password, it must be escaped with %40 as in vi://foo:b%40r@hostname,

and a slash in a Windows domain name (\) can be specified as %5c.

So try:

target=vi://DOMAIN%5cUser:PASSWORD@192.168.0.21/Datacenter1/host/esxhost1

where 192.168.0.21 is your vCenter server and the remainder is a reference to your ESX host or cluster.

If that doesn't work, try using the user's UPN instead of DOMAIN\USER.

Let us know if that works.

Hi All,

I have just deployed the new AP 2.8 with the new script, but from Admin UI I noticed that there's no edge configuration. All is disabled and I must insert all manually. What's wrong?

Thank you

Matrix

Unfortunately without seeing your .ini file, it won't be possible to tell.

There is a known bug in the Admin UI where if you don't specify instanceId=VIDM in the WebReverseProxy section, the Admin UI won't show that service as enabled. Not sure if you are using WebReverseProxy section.

Mark

Is there a configuration setting one could add to the .INI file to set the Access Point's time zone? Setting the time zone seems to still requires opening a console window in an otherwise fully automated deployment process.

You can leave the time zone at the default setting (UTC) as the Horizon View protocol manages time zone between the client and virtual desktops/apps.

Finding a list of supported/recommended 2FA solutions that work with Access Point is proving difficult. Given that they are very expensive does it work with Google Authenticator? I understand it doesn't work with VMware Verify, it that on the roadmap?

For RADIUS two-factor authentication in Horizon View and Access Point, we support the standard RFC 2865 - Remote Authentication Dial In User Service (RADIUS) protocol. This also includes Access-Challenge for any authentication that can be supported by text entry of credentials and challenge text through Horizon Clients. We don't have a list, but check that the vendor supports RFC 2865. Many vendors support this standard. I also know that there are some implementations that interface RADIUS authentication with other authentication systems such as Google Authenticator. Check with the vendors.

Access Point also supports SecurID two-factor authentication and is officially certified by RSA.

For future general questions or follow up on Access Point in general, please post a message on the VMware View discussion page as comments here are specifically for the Access Point PowerShell command. Thanks.

Thanks Mark, I was being cheeky. I knew this wasn't quite the right forum for it but I didn't want opinions I was hoping to get a proper answer from the product architect as above!

Hi Mark, when I deploy AP 2.8 with RADIUS and a secondary RADIUS server, the setting "enabledAux" is still false. In the new admin interface, the second RADIUS server is also disabled.

Thanks for pointing this out. It is now resolved in apdeploy-280-v3.zip.

In that case, you can be forgiven!

Hi markbenson‌,

I wondered if you could help with some pointers on the Radius piece, as I'm having some issues getting true SSO to work.

Using only "authMethods=radius-auth" have a scenario where the AP's splash screen offers just the 2FA passcode to connect, then the next screen will allow username and {ldapPassword}. With another configuration on the radius side, I can provide {ldapPassword+2faPasscode} in the same string, but on the second screen only allows {ldapPassword}. Neither of these configurations work with the "windowsSSOEnabled=true" setting.

I'm struggling a little to understand whether I need "authMethods=radius-auth && sp-auth" vs changing a configuration on the Radius side to have the environment provide one single login window for users.

Is there a recommended Radius setting you would advise along with parameters to invoke in this deploy script?

Thanks!

Yes, you should set "authMethods=radius-auth && sp-auth"


"windowsSSOEnabled=true" is used in RADIUS cases where the RADIUS passcode is the same as the users AD password (e.g. solutions that send an SMS text token to the user). This then allows the subsequent AD password prompt needed by Connection Server to be skipped. If in your case the RADIUS passcode is not the same as the AD password, then the user will get two prompts (RADIUS then password). This is how Horizon View works.

Thanks for all the comments.

Comments on this particular document are closed now but you can still ask questions about PowerShell deployment of Access Point and any other aspect of Access Point in the general discussion area. This is so that other members can also answer posts about Access Point deployment.

Mark

Version history
Revision #:
5 of 5
Last update:
‎11-16-2020 10:23 AM
Updated by:
 
Contributors