TurboVNC | Documentation / Using TurboVNC with Time-Based One-Time Passwords (TOTP)

TOTP, as implemented in the OATH Toolkit, provides a means of adding two-factor authentication (2FA) support to the TurboVNC Server.

Procedure

Install the OATH PAM module:
- Recent Fedora releases:
```
sudo dnf install pam_oath
```
- RHEL/CentOS 6 and newer:
  Install the EPEL repository, then
```
sudo yum install pam_oath
```
- Ubuntu 12.04 LTS and newer:
```
sudo apt-get install libpam-oath
```
RHEL/CentOS 6 only: Create a link for the OATH PAM module under /lib64/security:
```
sudo ln -fs /usr/lib64/security/pam_oath.so /lib64/security/
```

As root, edit /etc/pam.d/turbovnc and give it the following contents:

RHEL/Fedora:

#%PAM-1.0
auth requisite pam_oath.so usersfile=/etc/users.oath
account include system-auth
password include system-auth
session include system-auth

Ubuntu:

auth requisite pam_oath.so usersfile=/etc/users.oath

Set the permissions for /etc/pam.d/turbovnc appropriately.

sudo chown root:root /etc/pam.d/turbovnc
sudo chmod 644 /etc/pam.d/turbovnc

For every user who needs to use TOTP, create a unique secret key for that user:
```
head -10 /dev/urandom | md5sum | cut -b 1-30
```
As root, edit /etc/users.oath and give it the following contents:
```
HOTP/T30 {user1} - {secret1}
...
HOTP/T30 {userN} - {secretN}
```
where {secret1} through {secretN} are the per-user secret keys you generated above. Note that the "HOTP/T30" algorithm is appropriate for use with Google Authenticator. If using another TOTP application, then adjust the algorithm accordingly. Refer to this page for more information on the format of /etc/users.oath.

Set the permissions for /etc/users.oath appropriately.

sudo chown root:root /etc/users.oath
sudo chmod 600 /etc/users.oath

Install the TurboVNC Server.
Grant setuid permissions to Xvnc (necessary so it can read /etc/users.oath.)
```
sudo chmod u+s /opt/TurboVNC/bin/Xvnc
```
For each user, determine the Base32 version of their secret key.
```
oathtool --totp -v {secret}
```
Instruct each user to create a new account in Google Authenticator using manual entry and to enter their Base32 secret key (from above) as the key for this new account.

That's it. Users should now be able to use Unix Login or VeNCrypt *Plain authentication with the TurboVNC Viewer and enter the token from Google Authenticator as their password.

Optional Refinements

To require TOTP for all TurboVNC sessions, adjust permitted-auth-methods (TurboVNC 2.0.x and earlier) or permitted-security-types (TurboVNC 2.1.x and later) in the TurboVNC security configuration file on the server (usually /etc/turbovncserver-security.conf) in order to allow only the pam-userpwd authentication method (TurboVNC 2.0.x and earlier) or only the *Plain and UnixLogin security types (TurboVNC 2.1.x and later.)
To require SSH tunneling, add/uncomment no-remote-connections in the TurboVNC security configuration file.
To require built-in encryption, specify only the TLSPlain and X509Plain security types in permitted-security-types in the TurboVNC security configuration file (TurboVNC 2.1.x and later only.)
To disable reverse connections, add/uncomment no-reverse-connections in the TurboVNC security configuration file. This prevents users from making outbound connections from the server to a listening VNC viewer, which could circumvent the security/authentication restrictions configured on the server.
To enable multi-user collaboration using TOTP, add/uncomment enable-user-acl in the TurboVNC security configuration file. Users will now be able to run /opt/TurboVNC/bin/vncpasswd -a {other_user} to grant {other_user} temporary access to their session (authenticated via {other_user}'s TOTP.) /opt/TurboVNC/bin/vncpasswd -r {other_user} can be used to revoke that access.