Using Cloud connectivity tokens

Follow

To facilitate bulk deployment of your RealVNC Servers to the RealVNC Connect cloud, RealVNC Server can be joined to the cloud from the command line or via a script using a cloud connectivity token, instead of requiring a user to sign in to the RealVNC Server with their RealVNC account.

Computers can also be added to groups using cloud connectivity tokens if you need to restrict discovery of the computer to certain members of the team.

Cloud connectivity tokens are only available with Enterprise subscriptions.

Generating a cloud connectivity token 

Cloud connectivity tokens are found in the Device Access -> Deployment section of your RealVNC account. To generate a new cloud connectivity token use the Generate Token button in the Cloud connectivity tokens section.

mceclip1.png

Next, select how long the token will be valid for; either one hour or indefinitely.

 mceclip0.png

The token will be generated and will appear in the token column of the table.

mceclip0.png

The token can be applied either at install time (Windows only) or by using the command line/script for an existing RealVNC Server installation.

Deploying a cloud connectivity token

In the below examples, <TOKEN> should be replaced with the token you generated in the Deployment section of your RealVNC Account. Alternatively, you can download a JSON file containing your token and replace <TOKEN> with the path to the downloaded JSON file.

Install time (Windows only)

From RealVNC Server 7.9.0 onwards, you can include a cloud connectivity token as an MSI property JOINCLOUD, for example:

msiexec /i VNC-Server-7.9.0.msi /qn JOINCLOUD=<TOKEN>

You can also specify which group(s) the RealVNC Server should be added to using the JOINGROUP property, and the name that the device should be given using the JOINNAME property.

When using JOINGROUP, the group must already exist in the RealVNC Connect Portal. You can specify multiple groups as a comma separated list.

For both JOINGROUP and JOINNAME, the values must be URL encoded, for example spaces become %20.

Command line

Windows (Powershell)

In an administrator / elevated command prompt run:

& "C:\Program Files\RealVNC\VNC Server\vncserver.exe" -service -joinCloud <TOKEN>

Windows (Command Prompt)

In an administrator / elevated command prompt run:

"%programfiles%\RealVNC\VNC Server\vncserver.exe" -service -joinCloud <TOKEN>

macOS

In Terminal:

sudo /Library/vnc/vncserver -service -joinCloud <TOKEN>

Linux

In a terminal application run:

sudo vncserver-x11 -service -joinCloud <TOKEN>

From RealVNC Server 7.13.0 onwards, RealVNC Server will check if it is already joined to the same team that the cloud connectivity token belongs to. If the team does not match, RealVNC Server will use the cloud connectivity token to join the new team.

To force the token to be used, add the -rejoin option to the -joinCloud command, e.g.

"%programfiles%\RealVNC\VNC Server\vncserver.exe" -service -joinCloud <TOKEN> -rejoin

Script file

The following scripts must be run with elevated/administrator (Windows) or sudo/root (macOS and Linux) privileges.

RealVNC Server 7.13.0 and earlier

As RealVNC Server 7.13.0 and later include a built-in check for whether it is already joined to a team, you can deploy cloud connectivity tokens as shown in the Command Line section above.

RealVNC Server 7.12.1 and earlier

Windows (Powershell)

To deploy a cloud connectivity token using a Powershell script, create a new Powershell file (text file saved with a .ps1 extension) with the following contents:

if ((& 'C:\Program Files\RealVNC\VNC Server\vncserver.exe' -service -cloudstatus | ConvertFrom-JSON | Select-Object -ExpandProperty CloudJoined) -eq $false){
  & "C:\Program Files\RealVNC\VNC Server\vncserver.exe" -service -joinCloud <TOKEN>
}

Windows (Command Prompt/batch)

To deploy a cloud connectivity token using a batch script, create a new batch file (text file saved with a .bat extension) with the following contents:

@ECHO OFF
"C:\Program Files\RealVNC\VNC Server\vncserver.exe" -service -cloudstatus | findstr CloudJoined | findstr false 1>nul
IF %ERRORLEVEL% EQU 0 (
  "C:\Program Files\RealVNC\VNC Server\vncserver.exe" -service -joinCloud <TOKEN>
)

macOS (Shell)

To deploy a cloud connectivity token using a shell script, create a new shell script file (text file saved with a .sh extension) with the following contents:

if [[ "$(/Library/vnc/vncserver -service -cloudstatus | grep CloudJoined | cut -f2 -d':' | tr -d ',')" = "false" ]]; then
  /Library/vnc/vncserver -service -joinCloud <TOKEN>
fi

Linux (Shell)

To deploy a cloud connectivity token using a shell script, create a new shell script file (text file saved with a .sh extension) with the following contents:

if [ "$(/usr/bin/vncserver-x11 -service -cloudstatus | grep CloudJoined | cut -f2 -d':' | tr -d ',')" = "false" ]; then
  /usr/bin/vncserver -service -joinCloud <TOKEN>
fi

Additional Options

Adding a computer to a group

To add a computer to a group using a token the option -joinGroup <GROUP> must be added to the end of the joinCloud command.

You need to replace <GROUP> with the name of the group the computer is to be added to. The group must exist in the RealVNC Connect Portal before it can be used by -joinGroup.

You can also specify that RealVNC Server should be added to multiple groups, by adding -joinGroup <GROUP> for each group you want to add RealVNC Server to.

Changing the name RealVNC Server uses when joining the cloud

RealVNC Server will use the computer's hostname when joining the cloud by default. To use a different name the option -joinName <NAME> must be added to the end of the joinCloud command.

You need to replace <NAME> with the name that you would like to use for the computer.

Negotiating proxy servers

If there’s an intermediate proxy server when you add a computer to a team, supply location and credentials. For example, under Windows:

  • SOCKS proxy server:
    vncserver.exe -service -proxyserver="socks://SERVER:PORT" -proxyusername=NAME -proxypassword=OBFUSCATED-PWD -joinCloud TOKEN
  • HTTP proxy server:
    vncserver.exe -service -proxyserver="http://SERVER:PORT" -proxyusername=NAME -proxypassword=OBFUSCATED-PWD -joinCloud TOKEN

If the proxy server requires a password, first obfuscate that password using the vncpasswd utility, located in the same directory as RealVNC Server. Run the following command, and follow the instructions:

vncpasswd -legacy -print
Was this article helpful?
5 out of 22 found this helpful

Comments

0 comments

Article is closed for comments.