Setting up the VNC Server computer

Configure Active Directory

Make sure the computer is joined to a domain managed by Active Directory and enable the Active Directory Certificate Services role on at least one domain controller.

Configure VNC Server

1. Open VNC Server’s Options > Security page and select Smartcard/certificate store from the Authentication dropdown.
2. Register the user accounts of all prospective VNC Viewer users with VNC Server, either by
   • Opening VNC Server’s Options > Users & Permissions page and following these instructions.
   • Setting the VNC Server Permissions parameter.
     Note prior configuration is required to register domain accounts under Linux. You may also need to qualify usernames with the domain name, for example: DEV.ACMECORP.COM\johndoe.

Linux and Mac

1. Under Linux, configure VNC Server to identify the domain controller hosting the LDAP server.

   Either set the VNC Server LdapCertificateUserStore, LdapCertificateIntermediateStore and LdapCertificateTrustStore  parameters, or configure the LDAP server itself by adding HOST <your DC> to the LDAP library’s configuration file (for example, /etc/ldap/ldap.confunder Ubuntu or /etc/openldap/ldap.conf under CentOS).

2. Under Linux or Mac, obtain a LDAP-compatible library.

   Note that a suitable library may already be present on your system, for example /usr/lib/x86_64-linux-gnu/libldap-2.4.so.2 under Ubuntu, /lib64/libldap-2.4.so.2 under CentOS, or /usr/lib/libldap.dylib under Mac. Alternatively, you may be able to obtain one by installing third party software such as PowerBroker Identity Services or Centrify, designed to integrate with Active Directory.

3. Under Linux, create an /etc/vnc/ldaplib symbolic link pointing to the location of the LDAP-compatible library (above). If third party software is installed, make sure the symbolic link points to the third party version and not the system version.

   *This symbolic link is also required under Mac but VNC Server should create it for you at install-time (providing libldap.dylib can be found).

4. Under Linux, create /etc/vnc/kinit and /etc/vnc/klist symbolic links pointing to /usr/bin/kinit and /usr/bin/klistrespectively. If third party software is installed, make sure the symbolic links point to the third party versions and not the system versions.

   *These symbolic links are also required under Mac but VNC Server should create them for you at install-time.

Setting up the VNC Viewer device

Create a suitable X.509 certificate for the VNC Viewer user

Active Directory Certificate Services is recommended:

• Use an RSA key, or an ECDSA key with a P-256, P-384 or P-521 curve.
• Specify the Client Authentication Extended Key Usage (or no key usages). The OID for this usage is 1.3.6.1.5.5.7.3.2. Note under Windows, VNC Viewer will skip certificates if this key usage has been disabled via Windows key usage properties.
• Make sure VNC Viewer can extract the user account name from the certificate. By default, the name is extracted in “User-Principal Name” format (UPN), either from the certificate’s User Principal Name (stored as a Subject Alternative Name with OID 1.3.6.1.4.1.311.20.2.3) or from an email address stored as a Subject Alternative Name (RFC 822 name). Set the VNC Viewer CertificateUsername parameter to customize user name mapping.

Provision the device with the certificate

Desktops (Windows, Mac and Linux)

If the VNC Viewer user will plug a smartcard or authentication token into the computer, make sure that person knows the PIN.

Under Windows, no setup is required to enable VNC Viewer to load certificates from a smartcard/token. Under macOS Sierra (10.12), no set up is required providing the smartcard/token is supported by Apple’s CryptoKit drivers. Under Linux, and versions of macOS earlier than 10.12, you must use a PKCS #11 library to enable VNC Viewer to load certificates, such as those provided by the OpenSC project. To do this, set the VNC Viewer Pkcs11Lib parameter to the full path of the library, for example /usr/lib/opensc-pkcs11.so.

If the certificate will reside in a certificate store on the computer itself, make sure:

• Under Windows, the certificate is in the Personal > Certificates store (using a tool such as certmgr.msc).
• Under Mac, the certificate is in the login keychain.

Under Linux, please contact Support to see how to load certificates from a certificate store.

Note: you can optionally use a hardware token such as a YubiKey with your certificate. Please see How do I use a YubiKey to connect to a VNC Server using Certificate authentication?

Mobile Devices (Android and iOS)

Export or convert your certificate to PKCS #12 format (with either a .pfx extension or .p12), then follow the steps below for your platform.

Android

1. Download the certificate file to your device.
2. Locate the certificate file, and then tap it to install it as an App certificate on your device, entering the passphrase used when exporting the certificate.
3. Open VNC Viewer, then navigate to the Settings menu via the menu button in the top left.
4. Tap Import Certificates, and select your certificate from the list of certificate(s) listed.
5. The certificate is now ready for use by VNC Viewer. You can view a list of installed certificates using the Show Certificates option in the Settings menu.

iOS

1. Connect your iOS device to a Windows or Mac computer and open iTunes.
2. Use the File Sharing section to transfer the certificate file to your device.
3. Once the certificate file has been transferred, open VNC Viewer and navigate to Settings via the menu button in the top left.
4. Tap Certificates, then Import Certificates. Enter the passphrase used when exporting the certificate.
5. The certificate is now ready for use by VNC Viewer. You can view a list of installed certificates using the Certificates option in the Settings menu.

Check VNC Viewer is set to prefer smartcard/certificate store authentication (desktops only)

 This can be enabled either by:

• Turning on Authenticate using a smartcard or certificate store if possible in the VNC Viewer Properties dialog for connections to the VNC Server computer.
• Setting the VNC Viewer AuthCertificate parameter to <auto>.